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

# Aspect CLI

> Upload and download media, retrieve proxies, mount projects, and automate file workflows from your terminal on macOS, Windows, and Linux.

The `aspect` command connects the files on your computer to your Aspect workspace. Use it to upload a shoot, download a delivery, retrieve smaller video proxies, or mount a project so your applications can open its files directly.

The CLI runs on **macOS, Windows, and Linux**. It comes included with the [Aspect desktop app for macOS and Windows](https://aspect.inc/download), and can also be installed independently on machines such as Linux workstations and servers.

## Get started

<Steps>
  <Step title="Install the CLI">
    **macOS and Windows:** [Download the Aspect desktop app](https://aspect.inc/download). Install and open it to get the included CLI, then open a new terminal.

    **Linux or a standalone CLI installation:** use the installer for your operating system:

    <CodeGroup>
      ```bash macOS / Linux theme={null}
      curl -fsSL https://aspect.inc/cli/install.sh | sh
      ```

      ```powershell Windows theme={null}
      powershell -ExecutionPolicy Bypass -c "irm https://aspect.inc/cli/install.ps1 | iex"
      ```
    </CodeGroup>

    Open a new terminal after installation, then run `aspect --version`.
  </Step>

  <Step title="Sign in">
    If the Aspect desktop app is running and signed in, the CLI uses that account automatically. Check it with:

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

    On a machine without the desktop app, create an API key in Aspect's **Settings → API Keys** and use `aspect auth login` to enter it interactively. For a server or CI job, provide the key through `ASPECT_API_KEY`. See [Authentication](/docs/cli/authentication).
  </Step>

  <Step title="Find your files">
    ```bash theme={null}
    aspect ls
    aspect ls "aspect://Acme/"
    aspect ls "aspect://Acme/Documentary/"
    ```

    Replace `Acme` and `Documentary` with your workspace and project names. [Aspect paths](/docs/cli/paths) also accept IDs.
  </Step>

  <Step title="Download a file">
    ```bash theme={null}
    aspect download "aspect://Acme/Documentary/Footage/interview.mov" ./downloads
    ```

    To get its streaming proxy instead, add `--variant stream_proxy`.
  </Step>
</Steps>

## Choose a workflow

| You want to… | Start here |
| - | - |
| Send files or folders from your computer to Aspect | [Upload files](/docs/cli/uploads) |
| Save originals or a folder tree to a local disk | [Download files](/docs/cli/downloads) |
| Get smaller video files or poster images | [Retrieve proxies and previews](/docs/cli/proxies) |
| Find media by its content and combine search signals with filters | [Searching and filtering](/docs/cli/searching-and-filtering) |
| Open cloud media from editing applications or filesystem tools | [Mount projects](/docs/cli/mounts) |
| Keep media available for an offline session | [Cache and offline files](/docs/cli/cache-and-offline) |
| Run a transfer after closing your terminal | [Background transfers](/docs/cli/transfers) |
| Build a script or give a coding agent access to media | [Scripts and AI agents](/docs/cli/automation) |
| Look up a command or resolve an error | [Command reference](/docs/cli/commands) · [Troubleshooting](/docs/cli/troubleshooting) |

Content search combines the CLI with the [Aspect MCP server](/docs/api-reference/mcp) or [REST API](/docs/api-reference/index); the current CLI has no native search command. MCP and REST also cover metadata, collections, and review workflows.

<Tip>
  Giving these docs to an AI tool? Start with the [CLI documentation index](https://aspect.inc/docs/cli/llms.txt). Mintlify also provides an [index of all Aspect docs](https://aspect.inc/docs/llms.txt) and the [full documentation text](https://aspect.inc/docs/llms-full.txt).
</Tip>