Skip to main content
The CLI uses your Aspect identity and its existing permissions. On a workstation with the desktop app, sign in to the app. On a machine without it, use an API key.

​
With the desktop app

Open Aspect and sign in, then run:
The CLI uses the signed-in desktop account automatically. You do not need to create a key for this workflow.
A signed-in desktop session takes precedence over both an environment API key and a stored key. aspect auth status --json reports the source as desktop, env, or auth-file, and reports a key that is set but ignored. An offline signed-in desktop session does not silently switch to the key’s account.

​
Create an API key

Use a key for a Linux server, render worker, CI job, or another CLI-only installation.
  1. Sign in to the Aspect web app.
  2. Open Settings → API Keys.
  3. Choose Create new API Key and give it a name that identifies its use.
  4. Copy the key, which begins with sk_. The full key is shown once.
Each key acts as the user who created it and inherits that user’s access. Key creation currently accepts a name; it does not let you restrict a key to a project, folder, or read-only role. Choose the account used for an automated workflow accordingly.

​
Sign in on a CLI-only computer

Run this in an interactive terminal and paste the key at the hidden prompt:
auth login validates and stores an API key. It is not a browser sign-in flow. The default stored-key file is ~/.aspect/cli/auth.json; treat it as a credential file. If the CLI asks you to open or sign in to the installed Aspect app, follow that instruction. The desktop app is the sign-in path on that workstation.

​
Headless machines and CI

Set ASPECT_API_KEY through your job runner’s secret or environment settings. Authenticated commands use it without a preceding auth login:
On a machine without an active desktop session, the environment key overrides a stored key. Avoid embedding a real key in commands, checked-in scripts, logs, or prompts. auth login without a supplied key cannot prompt in --json mode; an environment key is the normal choice for scripts.

​
Sign out or revoke a key

This removes the CLI’s stored key and clears its saved default workspace. It does not revoke that key in Aspect, remove ASPECT_API_KEY from your environment, or sign out the desktop app. To revoke a key, delete it from Settings → API Keys in the web app. To change the desktop identity, sign out of the desktop app. Check aspect auth status after changing credentials so you know which identity the next command will use. If a command reports not_logged_in or invalid_api_key, follow Troubleshooting.