> ## 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.

# Command reference

> Every public Aspect CLI command, action, and option

The `aspect` CLI uploads and downloads media, lists your library, mounts projects, and manages local transfers and storage. See [installation](/docs/cli/installation) to get the CLI and [authentication](/docs/cli/authentication) to connect your account.

## Help and global options

```bash theme={null}
aspect --help
aspect download --help
aspect --version
aspect download --help --json
```

| Option | Behavior |
| - | - |
| `--help` | Show help for the CLI or a command. `aspect help download` is equivalent to `aspect download --help`. |
| `-h` | Short form for root help or a command's leading help argument, such as `aspect download -h`. |
| `--version` | Print the version with `aspect --version`. |
| `--json` | Return machine-readable output and disable interactive prompts. Available on every public command. |

Running a command group, such as `aspect transfer`, without an action shows its help. Use `--help --json` to discover the actions and options in your installed version. See [scripts and AI agents](/docs/cli/automation) for output formats and exit codes.

## Authentication

```bash theme={null}
aspect auth login
aspect auth status
aspect auth logout
```

| Action | Behavior |
| - | - |
| `login` | Validate an API key and save it for later commands. In an interactive terminal, prompts for the key without displaying it. |
| `status` | Report the active authentication source: `desktop`, `env`, or `auth-file`, or explain why no credential is available. |
| `logout` | Remove the saved API key. Does not sign out the desktop app or unset environment variables. |

`auth login` accepts `--api-key <key>`. Prefer the interactive prompt for people and `ASPECT_API_KEY` for automation, so keys stay out of command arguments and shell history.

When the Aspect desktop app is running and signed in, its account takes precedence over API keys. Otherwise, `ASPECT_API_KEY` takes precedence over the saved key. Read [authentication](/docs/cli/authentication) for setup and account switching.

## Browse workspaces and files

### `ls`

```bash theme={null}
aspect ls
aspect ls "aspect://Studio/"
aspect ls "aspect://Studio/Production/Renders"
```

| Target | Result |
| - | - |
| No argument, or `aspect://` | Your workspaces. |
| `aspect://<workspace>/` | Projects in that workspace. |
| A project or directory | Its immediate child directories and assets. |
| A single asset | That asset's entry. |

With `--json`, the result is an array of entries with `id`, `name`, and `type`. A returned entry may also include `size` in bytes or `updatedAt` when available.

### `workspace`

```bash theme={null}
aspect workspace list
aspect workspace use "Studio"
```

| Action | Behavior |
| - | - |
| `list` | List available workspaces and identify the default. |
| `use <workspace>` | Save a default workspace by name or ID for `aspect://~/` URLs. |

`ASPECT_WORKSPACE` overrides the saved default for `~`. Explicit workspace URLs are useful in scripts because they do not depend on that default. See [paths and workspaces](/docs/cli/paths).

## Upload

```bash theme={null}
aspect upload <local-path>... "aspect://<workspace>/<project>[/<path>]"
```

Provide one or more local files or directories, followed by the remote destination. Directories are uploaded recursively. Existing names are skipped by default.

| Option | Behavior |
| - | - |
| `--replace` | Replace existing files with the same name. |
| `--keep-both` | Keep both copies when names conflict. Cannot be combined with `--replace`. |
| `--detach` | Start a background transfer and return its ID. |

```bash theme={null}
aspect upload ./final.mov ./thumbnail.jpg "aspect://Studio/Production/Renders"
aspect upload ./Footage "aspect://Studio/Production" --keep-both --detach
```

See [uploads](/docs/cli/uploads) for destination behavior and conflict handling, and [background transfers](/docs/cli/transfers) for tracking a detached upload.

## Download

```bash theme={null}
aspect download "aspect://<workspace>/<project>[/<path>]" [<local-dir>]
```

Download one asset, a directory, or a project. The local destination defaults to the current directory. Existing local filenames are skipped by default.

| Option | Behavior |
| - | - |
| `--variant <variant>` | Select `original` (default), `stream_proxy`, or `preview`. |
| `--replace` | Replace existing local files with the same name. |
| `--keep-both` | Keep both local copies by adding a numeric suffix. Cannot be combined with `--replace`. |
| `--detach` | Start a background transfer and return its ID. |

```bash theme={null}
aspect download "aspect://Studio/Production/Renders/final.mov" ./downloads
aspect download "aspect://Studio/Production/Footage" ./proxies --variant stream_proxy
aspect download "aspect://Studio/Production" ./backup --detach
```

`stream_proxy` retrieves the H.264 MP4 proxy, up to 1080p, with AAC audio when the source has audio. `preview` retrieves the preview image. A directory or project download leaves out assets without the requested variant; selecting a single asset without that variant fails.

See [downloads](/docs/cli/downloads) for local folder behavior and [proxies and previews](/docs/cli/proxies) for variant availability and filenames.

## Background transfers

```bash theme={null}
aspect transfer list
aspect transfer status <id>
aspect transfer wait <id>
aspect transfer cancel <id>
```

| Action | Behavior |
| - | - |
| `list` | List detached transfers recorded on this computer. |
| `status <id>` | Show one transfer's current progress and outcome. |
| `wait <id>` | Block until a transfer finishes, then return its final result. |
| `cancel <id>` | Request cancellation of a running transfer. |

IDs come from `upload --detach` or `download --detach`. These commands track detached CLI transfers, not every transfer in your workspace. A failed or cancelled transfer makes `status` and `wait` exit with code `1` while still returning its snapshot on stdout.

See [background transfers](/docs/cli/transfers) for result fields and cancellation behavior.

## Mounts

### `mount`

```bash theme={null}
aspect mount "aspect://Studio/Production"
aspect mount "aspect://Studio/Production/Renders" --name Renders
```

Mount a project or directory as a local volume. `--name <volume>` sets the volume's display name; the default is the project or directory name. Mounting a single asset is not supported.

### `unmount`

```bash theme={null}
aspect unmount Renders
aspect unmount "aspect://Studio/Production"
```

Unmount by volume name or the same Aspect URL used to mount it. See [mounts](/docs/cli/mounts) for platform prerequisites, local access, and writes.

## Offline pins and storage settings

### `pin`

```bash theme={null}
aspect pin list
aspect pin add "aspect://Studio/Production/Footage"
aspect pin remove "aspect://Studio/Production/Footage"
```

| Action | Behavior |
| - | - |
| `list` | Show pins, sync status, and synced and total bytes. |
| `add <url>` | Pin a project, directory, or asset for offline access through a mount. |
| `remove <url or pin-id>` | Remove a pin by URL or the ID returned by `pin list --json`. |

Adding an existing pin returns that pin. If a file is available because a parent directory is pinned, remove the parent pin to unpin it. Wait for synchronization to complete before relying on a pin offline.

### `settings`

```bash theme={null}
aspect settings list
aspect settings set cache-limit 200GB
aspect settings set pin-limit 1.5TB
```

| Setting | Behavior |
| - | - |
| `cache-limit` | Limit local storage for automatically cached content. Minimum: `10GB`. |
| `pin-limit` | Limit local storage for pinned content. Minimum: `5GB`; cannot be lower than the content already pinned. |

`settings list` reports the current settings. `settings set <setting> <size>` changes one. Sizes require a unit: `B`, `KB`, `MB`, `GB`, or `TB`. Units are decimal, and fractional values such as `1.5TB` are accepted. Settings persist on this computer and apply to its filesystem service.

See [cache and offline access](/docs/cli/cache-and-offline) for the difference between cached content and complete pins.

## Status and diagnostics

### `status`

```bash theme={null}
aspect status
```

Show authentication, the filesystem service, mounted volumes, an overall pin summary, and transfers together.

### `doctor`

```bash theme={null}
aspect doctor --json
```

Check authentication, the CLI installation, the filesystem service, and the operating system's mount prerequisites. `doctor` reports issues and suggested fixes; it does not install or repair prerequisites. A failing check returns exit code `1` with the checks on stdout.

### `daemon`

```bash theme={null}
aspect daemon status
aspect daemon start
aspect daemon stop
aspect daemon restart
```

| Action | Behavior |
| - | - |
| `status` | Show service state, version, mounts, and remaining write-back bytes per mount. |
| `start` | Start the service if needed. |
| `stop` | Stop the service. Remembered mounts return the next time it starts. |
| `restart` | Stop and start the service, picking up a newly installed version. |

The filesystem service starts automatically when a command needs it. Use these controls when troubleshooting. When the desktop app is signed in and owns the service, `start`, `stop`, and `restart` return `daemon_owned_by_desktop`; manage the service through the desktop app instead.

See [troubleshooting](/docs/cli/troubleshooting) for authentication, mount, and transfer errors.

## Updates and agent setup

### `upgrade`

```bash theme={null}
aspect upgrade
```

Install the latest CLI release. `--allow-downgrade` allows installing that release even if its version is older than the installed version. If the desktop app owns the filesystem service, the upgrade leaves restarting that service to the app.

### `skills add`

```bash theme={null}
aspect skills add
```

Install the official `aspect-cli` skill for supported AI agents detected on this computer. This command requires Node.js and `npx` and installs at user scope. See [scripts and AI agents](/docs/cli/automation).

## Environment variables

| Variable | Behavior |
| - | - |
| `ASPECT_API_KEY` | API key for headless use. Overrides the saved key; a signed-in desktop app takes precedence over both. |
| `ASPECT_AUTH_FILE` | Override the saved API-key file path. Default: `~/.aspect/cli/auth.json`. |
| `ASPECT_WORKSPACE` | Default workspace name or ID for `aspect://~/` URLs. Overrides the saved workspace default. |