> ## Documentation Index
> Fetch the complete documentation index at: https://aspect.inc/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Scripts and AI agents

> Use JSON output, background transfers, and the Aspect skill in scripts, CI, and AI tools

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

```bash theme={null}
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](/docs/cli/commands) 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.

```bash theme={null}
# 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:

1. The Aspect desktop app, when it is running and signed in.
2. `ASPECT_API_KEY`.
3. 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](/docs/cli/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:

```bash theme={null}
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](/docs/cli/paths).

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](/docs/cli/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:

```json theme={null}
{
  "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`.

<Note>
  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.
</Note>

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

```json theme={null}
{
  "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:

```bash theme={null}
aspect download "aspect://Studio/Production/Footage" ./proxies --variant stream_proxy --detach --json
```

The launch result contains `id`:

```json theme={null}
{
  "id": "6bc60177-a942-484a-a7f8-f624c1b617d7"
}
```

Pass that ID to the transfer commands:

```bash theme={null}
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`:

```python theme={null}
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](/docs/cli/transfers).

## Connect AI agents

Install the official CLI skill:

```bash theme={null}
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](/docs/api-reference/mcp) for searching and understanding media, transcripts, collections, metadata, comments, and sharing:

```text theme={null}
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](/docs/cli/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](https://aspect.inc/docs/cli/llms.txt): links to this section's guides and reference.
* [Site documentation index](https://aspect.inc/docs/llms.txt): links across the Aspect documentation.
* [Full documentation text](https://aspect.inc/docs/llms-full.txt): 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.