Scripts and AI agents

Use the Aspect CLI to move media between a computer and Aspect, retrieve proxies, and work with mounted projects. Every public command accepts --json for scripts and AI agents.

Discover commands

aspect --version --json
aspect --help --json
aspect download --help --json

Root help lists the public commands. Command help describes its usage, actions, settings, flags, environment variables, and examples. Read the installed CLI’s help when generating a command; available options can change between versions. The command reference documents the public interface.

Authenticate without a prompt

On a headless machine or CI runner, configure ASPECT_API_KEY through your environment or secret manager. The key authenticates commands directly; there is no separate login step.

# ASPECT_API_KEY is supplied by your job's secret manager.
aspect auth status --json
aspect ls "aspect://Studio/Production/Renders" --json

Keep keys out of command arguments, repository files, and logs. aspect auth login without a key argument is an interactive terminal flow; --json disables that prompt. Authentication follows this order:

The Aspect desktop app, when it is running and signed in.
ASPECT_API_KEY.
A key saved by aspect auth login.

An environment key does not switch away from a signed-in desktop account. aspect auth status --json reports the source as desktop, env, or auth-file, and reports when a key is ignored. A signed-in desktop app that is offline also takes precedence; the CLI does not silently switch to a key. See authentication for creating keys and managing sign-in.

Make destinations explicit

Include the workspace and project in each remote URL, and quote URLs or local paths that contain spaces:

aspect upload ./final.mov "aspect://Studio/Client Campaign/Renders" --json
aspect download "aspect://Studio/Client Campaign/Footage" ./proxies --variant stream_proxy --json

aspect://~/ depends on ASPECT_WORKSPACE, a saved default, or sole workspace membership. Explicit workspace URLs make a job independent of that local configuration. There is no --workspace flag. See paths and workspaces. Choose conflict behavior deliberately. Uploads and downloads skip existing filenames by default. Use --replace to replace them or --keep-both to preserve both copies. These two flags cannot be combined. For viewing or analysis, stream proxies can avoid downloading large originals. A directory download omits assets that do not have the selected variant, so check that you received the media your job needs.

Parse JSON and exit codes

With --json:

stdout contains the JSON result.
Command errors go to stderr as a JSON error object.
Interactive prompts and progress bars are disabled. Without --json, progress is written to stderr only when it is a terminal.

Keep stdout and stderr separate. Do not merge them with 2>&1 before parsing.

Exit code	Meaning
`0`	Command completed successfully. For a detached launch, this means the background transfer was started.
`1`	Command failure, a failed check, or a transfer that failed or was cancelled.
`2`	Usage error, such as missing arguments, an invalid URL, or incompatible options.

An error object has this shape:

{
  "error": {
    "code": "not_found",
    "message": "The requested item could not be found."
  }
}

Branch on error.code; display error.message to the person operating the job. Common codes include usage, not_logged_in, invalid_api_key, not_found, ambiguous_name, api_request_failed, network_timeout, network_unreachable, daemon_error, and daemon_owned_by_desktop.

Exit code 1 can include a normal JSON result on stdout. doctor returns its checks, transfer status and transfer wait return the transfer snapshot, and uploads or downloads with per-file failures return their summary. Check stdout before assuming stderr contains an error object.

For example, a foreground upload can return this summary and exit 1:

{
  "uploaded": 2,
  "skipped": 0,
  "failed": [
    {
      "path": "clip-03.mov",
      "error": "Transfer failed"
    }
  ]
}

Foreground downloads use downloaded instead of uploaded. Skipped files do not make a transfer fail. Treat the exit code as well as the result as significant, and allow additional JSON fields as the CLI evolves.

Run a background transfer

Add --detach when a transfer should outlive the foreground CLI process:

aspect download "aspect://Studio/Production/Footage" ./proxies --variant stream_proxy --detach --json

The launch result contains id:

{
  "id": "6bc60177-a942-484a-a7f8-f624c1b617d7"
}

Pass that ID to the transfer commands:

aspect transfer status 6bc60177-a942-484a-a7f8-f624c1b617d7 --json
aspect transfer wait 6bc60177-a942-484a-a7f8-f624c1b617d7 --json

wait blocks until a terminal state. Both commands return the snapshot directly, with fields including:

Field	Meaning
`id`	Transfer ID.
`op`	`upload` or `download`.
`state`	`running`, `succeeded`, `failed`, or `cancelled`.
`filesDone`, `filesTotal`	File progress counts.
`bytesDone`, `bytesTotal`	Byte progress counts.
`progress`	Completion fraction from `0` to `1`.
`speedMbps`, `etaSeconds`	Current megabits per second and estimated seconds remaining.
`result`	Final summary: `succeeded`, `skipped`, `failed` entries, and an optional overall `error`.

aspect transfer list --json wraps its snapshots in a transfers array. aspect transfer cancel <id> --json requests cancellation; use wait to collect the terminal outcome. The runner writes its first snapshot after launch. An immediate status or wait can briefly return transfer_not_found; retry that error briefly for a newly launched ID. Other failures need their own handling. This Python example starts a proxy download, handles that short startup window, and preserves the final JSON and exit code. It requires Python 3 and aspect on PATH:

import json
import subprocess
import sys
import time


def finish(process):
    sys.stdout.write(process.stdout)
    sys.stderr.write(process.stderr)
    raise SystemExit(process.returncode)


launch = subprocess.run(
    [
        "aspect", "download", "aspect://Studio/Production/Footage",
        "./proxies", "--variant", "stream_proxy", "--detach", "--json",
    ],
    capture_output=True,
    text=True,
)
if launch.returncode != 0:
    finish(launch)

transfer_id = json.loads(launch.stdout)["id"]
for attempt in range(20):
    result = subprocess.run(
        ["aspect", "transfer", "wait", transfer_id, "--json"],
        capture_output=True,
        text=True,
    )
    if result.stdout or result.returncode != 1:
        finish(result)
    try:
        code = json.loads(result.stderr).get("error", {}).get("code")
    except json.JSONDecodeError:
        finish(result)
    if code != "transfer_not_found" or attempt == 19:
        finish(result)
    time.sleep(0.25)

Background transfers still depend on the machine staying awake and running. CI systems may terminate background processes when a job ends; wait for the result inside the job when completion matters. See background transfers.

Connect AI agents

Install the official CLI skill:

aspect skills add

This requires Node.js and npx. It installs the aspect-cli skill from aspect-hq/aspect-cli at user scope for supported agents detected on the machine. The skill teaches authentication, path handling, JSON results, transfers, mounts, and offline pins. Use the CLI for local files, transfers, proxies, and mounts. Connect the Aspect MCP server for searching and understanding media, transcripts, collections, metadata, comments, and sharing:

https://api.aspect.inc/mcp

For example, an agent can find relevant clips through MCP and retrieve their proxies through the CLI. Both use the permissions of the authenticated account; connecting MCP does not itself authenticate the local CLI. See Searching and filtering for combining visual, transcript, document, and filename signals with metadata filters. Content search uses API/MCP calls alongside the CLI; there is no native CLI search command.

Documentation for language models

CLI documentation index: links to this section’s guides and reference.
Site documentation index: links across the Aspect documentation.
Full documentation text: the site’s documentation in a combined text format.

Use the documentation for workflows and concepts, and aspect <command> --help --json for the options supported by the installed binary.

Get started

Work with files

Mounted projects

Reference

Scripts and AI agents

Discover commands

Authenticate without a prompt

Make destinations explicit

Parse JSON and exit codes

Run a background transfer

Connect AI agents

Documentation for language models

​Discover commands

​Authenticate without a prompt

​Make destinations explicit

​Parse JSON and exit codes

​Run a background transfer

​Connect AI agents

​Documentation for language models

Discover commands

Authenticate without a prompt

Make destinations explicit

Parse JSON and exit codes

Run a background transfer

Connect AI agents

Documentation for language models