Command reference

The aspect CLI uploads and downloads media, lists your library, mounts projects, and manages local transfers and storage. See installation to get the CLI and authentication to connect your account.

Help and global options

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 for output formats and exit codes.

Authentication

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 for setup and account switching.

Browse workspaces and files

`ls`

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`

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.

Upload

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.

aspect upload ./final.mov ./thumbnail.jpg "aspect://Studio/Production/Renders"
aspect upload ./Footage "aspect://Studio/Production" --keep-both --detach

See uploads for destination behavior and conflict handling, and background transfers for tracking a detached upload.

Download

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.

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 for local folder behavior and proxies and previews for variant availability and filenames.

Background transfers

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 for result fields and cancellation behavior.

Mounts

`mount`

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`

aspect unmount Renders
aspect unmount "aspect://Studio/Production"

Unmount by volume name or the same Aspect URL used to mount it. See mounts for platform prerequisites, local access, and writes.

Offline pins and storage settings

`pin`

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`

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 for the difference between cached content and complete pins.

Status and diagnostics

`status`

aspect status

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

`doctor`

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`

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 for authentication, mount, and transfer errors.

Updates and agent setup

`upgrade`

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`

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.

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.

Get started

Work with files

Mounted projects

Reference

Command reference

Help and global options

Authentication

Browse workspaces and files

`ls`

`workspace`

Upload

Download

Background transfers

Mounts

`mount`

`unmount`

Offline pins and storage settings

`pin`

`settings`

Status and diagnostics

`status`

`doctor`

`daemon`

Updates and agent setup

`upgrade`

`skills add`

Environment variables

​Help and global options

​Authentication

​Browse workspaces and files

​ls

​workspace

​Upload

​Download

​Background transfers

​Mounts

​mount

​unmount

​Offline pins and storage settings

​pin

​settings

​Status and diagnostics

​status

​doctor

​daemon

​Updates and agent setup

​upgrade

​skills add

​Environment variables

Help and global options

Authentication

Browse workspaces and files

`ls`

`workspace`

Upload

Download

Background transfers

Mounts

`mount`

`unmount`

Offline pins and storage settings

`pin`

`settings`

Status and diagnostics

`status`

`doctor`

`daemon`

Updates and agent setup

`upgrade`

`skills add`

Environment variables