# Aspect CLI

> Upload and download media, retrieve proxies and previews, mount projects, and manage offline files on macOS, Windows, and Linux.

Use these guides for workflows and `aspect <command> --help --json` for the options in the installed CLI. CLI examples cover the public command surface available in v0.1.15. Content search uses the REST API or MCP alongside the CLI; there is no native CLI search command.

The CLI is included with the Aspect desktop app for macOS and Windows, available at https://aspect.inc/download. Install and open the app, then open a new terminal. Standalone CLI installers are also available for macOS, Windows, and Linux.

The CLI uses a signed-in Aspect desktop session first, then ASPECT_API_KEY, then a stored key. API keys inherit their creating user's permissions. Use --json for non-interactive commands and keep stdout and stderr separate.

Remote paths are aspect://<workspace>/<project>/<path>. Transfers skip existing filenames by default. Proxy downloads retrieve existing variants; they do not generate missing proxies or substitute originals. Pin files and wait for synced before relying on them offline. Mounted writes upload in the background after writable handles close. Before disconnecting, run aspect daemon status --json and require writeBackDrained to be true and writeSyncSummary.failureCount to be 0, with no mount errors; a drained queue alone does not rule out failed uploads.

## Get started

- [Aspect CLI](https://aspect.inc/docs/cli/index.md): Upload and download media, retrieve proxies, mount projects, and automate file workflows from your terminal on macOS, Windows, and Linux.
- [Installation and updates](https://aspect.inc/docs/cli/installation.md): Install the Aspect CLI on macOS, Windows, or Linux, check mount prerequisites, and update an existing installation.
- [Authentication and API keys](https://aspect.inc/docs/cli/authentication.md): Use your signed-in Aspect desktop account, store an API key for a CLI-only machine, or authenticate headless jobs through the environment.
- [Paths and core concepts](https://aspect.inc/docs/cli/paths.md): Address workspaces, projects, directories, and assets with aspect:// URLs, use IDs, and choose a default workspace.

## Work with files

- [Upload files](https://aspect.inc/docs/cli/uploads.md): Upload files and directory trees to Aspect, control name conflicts, and handle interrupted or large transfers.
- [Download files](https://aspect.inc/docs/cli/downloads.md): Download original media, directories, and projects to your computer, with explicit conflict handling and completion results.
- [Retrieve proxies and previews](https://aspect.inc/docs/cli/proxies.md): Download generated H.264 video proxies and poster images for review, analysis, or automation without downloading the original media.
- [Searching and filtering](https://aspect.inc/docs/cli/searching-and-filtering.md): Filter CLI listings, combine visual, transcript, document, and filename search signals, and apply metadata requirements through REST or MCP.
- [Background transfers](https://aspect.inc/docs/cli/transfers.md): Run uploads and downloads in the background, inspect progress, wait for results, and cancel a transfer by ID.

## Mounted projects

- [Mount projects](https://aspect.inc/docs/cli/mounts.md): Mount an Aspect project or folder, open files on demand, save changes, and check background uploads before unmounting.
- [Cache and offline files](https://aspect.inc/docs/cli/cache-and-offline.md): Control local cache usage, pin complete files for offline access, and confirm synchronization before going offline.

## Reference

- [Scripts and AI agents](https://aspect.inc/docs/cli/automation.md): Use JSON output, background transfers, and the Aspect skill in scripts, CI, and AI tools
- [Command reference](https://aspect.inc/docs/cli/commands.md): Every public Aspect CLI command, action, and option
- [Troubleshooting](https://aspect.inc/docs/cli/troubleshooting.md): Resolve authentication, path, mount, transfer, proxy, and offline-pin errors using Aspect's built-in diagnostics.

## Related resources

- [Download the desktop app](https://aspect.inc/download): Aspect for macOS and Windows, including the CLI.
- [All Aspect documentation](https://aspect.inc/docs/llms.txt): Automatically maintained index for the entire documentation site.
- [Full documentation text](https://aspect.inc/docs/llms-full.txt): Combined documentation text.
- [Aspect MCP server](https://aspect.inc/docs/api-reference/mcp.md): Connect AI tools for search, transcripts, metadata, collections, and collaboration.
- [CLI releases](https://github.com/aspect-hq/aspect-cli/releases/latest): Published binaries and installation scripts.