Navigation

Use the CLI

Complete command reference

This page provides a complete reference for all Aperture CLI commands.

Authentication Commands

aperture auth login

Authenticate with the Aperture API using email/password or a token.

# Interactive login (prompts for password)
$ aperture auth login --email user@example.com


# Token-based login
$ aperture auth login --token <JWT_TOKEN>

Options:

--email <EMAIL>
Email address for authentication
--token <TOKEN>
JWT token for direct authentication

After successful login, the CLI automatically saves your authentication token and sets the first organization as your active context.

aperture auth

# Log out and clear stored credentials.
$ aperture auth logout


# Check authentication status.
$ aperture auth status


# Display detailed information about the current user and context.
$ aperture auth whoami


#Refresh the authentication token.
$ aperture auth refresh

Context Commands

Context commands manage your active organization and project, which are used as defaults for other commands.

aperture context show

Display the current context.

$ aperture context show

Output:

> Current Context:
>  Organization: acme-corp (44d59b7b-4a4b-4971-a213-569c3afdda11)
>  Project: contact-details (contact-details)

aperture context set-org

Set the active organization.

# Set directly
$ aperture context set-org acme-corp


# Interactive selection
$ aperture context set-org

aperture context set-project

Set the active project (web app). You must set an organization before setting a project.

# Set directly
$ aperture context set-project contact-details


# Interactive selection
$ aperture context set-project

Project Commands

Manage web applications in your organization.

aperture project list

List all web apps in the current organization.

$ aperture project list [OPTIONS]

Options:

--org <ORG_SLUG>
Override the current organization context
--json
Output in JSON format

aperture project info

Display detailed information about a web app.

# Current project
$ aperture project info


# Specific project
$ aperture project info contact-details

Build Commands

Manage application builds.

aperture build upload

Upload a new build to Aperture.

$ aperture build upload <PATH> --version <VERSION> [OPTIONS]

Arguments:

<PATH>
Path to the build archive (.spar file)

Options:

--version <VERSION>
Build version (e.g., “1.2.0”) (required)
--web-app-id <ID>
Web app ID (uses current context if not provided)
--tag <TAG>
Git tag or release tag
--commit-sha <SHA>
Git commit SHA
--source-type <TYPE>
Source type (default: “upload”)
--metadata <JSON>
Additional metadata as JSON string
--verify-key <KEY_PATH>
Public key to verify the archive signature

Example:

$ aperture build upload ./my-app.spar \
  --version 1.2.0 \
  --tag v1.2.0 \
  --commit-sha abc123def456

aperture build list

List builds for a web app.

$ aperture build list [OPTIONS]

Options:

--web-app-id <ID>
Web app ID (uses current context if not provided)
--limit <NUMBER>
Maximum number of builds to display (default: 20)
--json
Output in JSON format

aperture build download

Download a build archive.

# Download by ID
$ aperture build download <BUILD_ID>


# Interactive selection
$ aperture build download


# Specify output path
$ aperture build download <BUILD_ID> -o ./downloads/my-build.spar

Options:

--web-app-id <ID>
Web app ID (uses current context if not provided)
--output <PATH> / -o <PATH>
Output file path (default: build-{version}.spar)

aperture build info

Display detailed information about a build.

# Specific build
$ aperture build info <BUILD_ID>


# Interactive selection
$ aperture build info

Spar Archive Commands

These commands work with spar archives locally without requiring API access.

aperture spar archive

Create a spar archive from a file or directory.

$ aperture spar archive <SOURCE> [OUTPUT] [OPTIONS]

Arguments:

<SOURCE>
Path to the file or directory to archive (required)
[OUTPUT]
Output path for the archive (optional)

Options:

--signing-key <KEY_PATH>
Path to a signing key file to create a signed archive

Examples:

# Create an archive
$ aperture spar archive ./my-app


# Create with specific output
$ aperture spar archive ./my-app ./archives/my-app.spar


# Create a signed archive
$ aperture spar archive ./my-app ./archives/my-app.spar --signing-key ./keys/private.key

aperture spar extract

Extract files from a spar archive.

$ aperture spar extract <SOURCE> [DESTINATION] [OPTIONS]

Arguments:

<SOURCE>
Path to the spar archive (required)
[DESTINATION]
Where to extract files (optional)

Options:

--href <FILE_PATH> / -p <FILE_PATH>
Extract a specific file by its path
--verify [KEY | 'checksum']
Verify the archive before extraction

Examples:

# Extract entire archive
$ aperture spar extract my-app.spar


# Extract a specific file
$ aperture spar extract my-app.spar -p config/settings.json


# Extract with verification
$ aperture spar extract my-app.spar --verify ./keys/public.key

aperture spar verify

Verify the integrity of a spar archive without extracting.

$ aperture spar verify <SPAR> --verifier <KEY | 'checksum'>

Examples:

# Verify checksums
$ aperture spar verify my-app.spar -k checksum


# Verify signature
$ aperture spar verify my-app.spar -k ./keys/public.key

aperture spar list

List the contents of a spar archive.

$ aperture spar list <ARCHIVE_PATH> [OPTIONS]

Options:

--json / -j
Output in JSON format
--sort-by-name / -n
Sort entries by file name
--sort-by-size / -s
Sort entries by file size (descending)
--pattern <REGEX> / -p <REGEX>
Filter files by regex pattern

Examples:

# List all files
$ aperture spar list my-app.spar


# Filter by pattern
$ aperture spar list my-app.spar -p "\.json$"


# JSON output sorted by size
$ aperture spar list my-app.spar --sort-by-size --json

aperture spar update

Create a delta/differential update from a remote archive.

$ aperture spar update <LOCAL_PATH> <REMOTE_URL> <OUTPUT_PATH> [OPTIONS]

Options:

--verify-key <KEY_PATH>
Public key to verify the remote archive signature

aperture spar local-update

Create a delta/differential update between two local archives.

$ aperture spar local-update <SOURCE_PATH> <TARGET_PATH> <OUTPUT_PATH> [OPTIONS]

Example:

$ aperture spar local-update ./v1.0.spar ./v2.0.spar ./update-1.0-to-2.0.spar

Complete Workflows

Build and Deploy Workflow

# 1. Login
$ aperture auth login --email your-email@example.com


# 2. Set context
$ aperture context set-org your-org-slug
$ aperture context set-project my-app


# 3. Build your web app
$ npm run build


# 4. Create archive
$ aperture spar archive ./dist ./builds/my-app-v1.0.0.spar --signing-key ./keys/private.key


# 5. Upload
$ aperture build upload ./builds/my-app-v1.0.0.spar \
  --version 1.0.0 \
  --tag v1.0.0 \
  --commit-sha $(git rev-parse HEAD)

CI/CD Integration (GitHub Actions)

name: Build and Deploy to Aperture


on:
  push:
    tags:
      - "v*"


jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3


      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: "18"


      - name: Build Application
        run: |
          npm ci
          npm run build


      - name: Deploy to Aperture
        env:
          APERTURE_TOKEN: ${{ secrets.APERTURE_TOKEN }}
        run: |
          aperture auth login --token $APERTURE_TOKEN
          aperture context set-org ${{ vars.APERTURE_ORG }}
          aperture context set-project ${{ vars.APERTURE_PROJECT }}
          aperture spar archive ./dist ./build.spar
          aperture build upload ./build.spar \
            --version ${GITHUB_REF#refs/tags/v} \
            --tag ${GITHUB_REF#refs/tags/} \
            --commit-sha $GITHUB_SHA

Notes

  • All paths must exist and be valid
  • Archive verification is optional but recommended for security
  • JSON output is useful for scripting and integration with other tools

Previous

Install the CLI

Next

Enable Autocompletion