> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runaether.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Overview

> The aether command-line interface for projects, tasks, workspaces, billing, and integrations

The Aether CLI manages projects, tasks, and cloud workspaces from your terminal. It connects to the Aether API, follows long-running agent tasks, and exposes every part of the platform that the web app does.

Install it with the [install script or Homebrew](/cli/installation), then run the interactive setup:

```bash theme={"dark"}
aether setup
```

## Global Flags

These persistent flags are available on every command.

| Flag | Short | Description |
| - | - | - |
| `--project` | `-p` | Override the default project ID or name for this command |
| `--json` | | Output results as JSON |
| `--no-color` | | Disable colored output |
| `--api-url` | | Override the Aether API URL |
| `--debug` | | Print debug information to stderr |

## Configuration

The CLI stores configuration in `~/.aether/config.json`, created on first login. It holds your default project, API URL, and authentication tokens. Set `AETHER_CONFIG_DIR` to use a different directory.

Manage non-sensitive config keys with [`aether config`](/cli/config).

### Environment Variables

Environment variables take precedence over the config file.

| Variable | Description |
| - | - |
| `AETHER_TOKEN` | Platform API key used as a bearer token (skips the interactive login flow) |
| `AETHER_PROJECT` | Default project ID or name (overrides the config file) |
| `AETHER_API_URL` | API base URL (overrides the config file) |
| `AETHER_PREVIEW_DOMAIN` | Domain used when printing workspace preview URLs |
| `AETHER_DEBUG=1` | Enable debug output to stderr |
| `NO_COLOR` | Disable colored output (any non-empty value) |

## Command Groups

### Core

| Command | Description |
| - | - |
| [`aether setup`](/quickstart#step-2-run-aether-setup) | Interactively prepare a fresh machine for Aether |
| [`aether run`](/cli/run) | Create a task and watch the agent work |
| [`aether models`](/cli/models) | List agent types and their models |
| [`aether project`](/cli/project) | Manage projects |
| [`aether task`](/cli/task) | Manage tasks and agent runs |
| [`aether usage`](/cli/usage) | Show a credits, tokens, and VM-uptime summary |
| [`aether billing`](/cli/billing) | Manage billing, credits, checkout, and portal sessions |
| [`aether warm-slot`](/cli/warm-slot) | Manage warm slots |
| [`aether notification`](/cli/notification) | Manage notifications and delivery preferences |
| [`aether feedback`](/cli/feedback) | Submit product feedback |

### Workspace

| Command | Description |
| - | - |
| [`aether workspace`](/cli/workspace) | Manage cloud workspaces |
| [`aether file`](/cli/file) | Read, write, and manage workspace files |
| [`aether env`](/cli/env) | Manage project environment variables |
| [`aether git`](/cli/git) | Git operations on the workspace repository |

### Integrations

| Command | Description |
| - | - |
| `aether mcp serve` | Serve Aether's MCP tools to Claude Code or Codex; started by the client from its MCP configuration (see [Cloud delegation](/guides/cloud-delegation)) |
| `aether mcp login` | Sign in once for `aether mcp serve`, so sessions start without a browser (`aether setup` runs it) |
| [`aether github`](/cli/github) | Connect and sync with GitHub repositories |
| [`aether sentry`](/cli/sentry) | Connect to Sentry and manage repo links |
| [`aether slack`](/cli/slack) | Manage the Slack integration and routes |
| [`aether linear`](/cli/linear) | Manage the Linear integration and routes |

### Configuration

| Command | Description |
| - | - |
| [`aether auth`](/cli/auth) | Log in, log out, and manage authentication |
| [`aether opencode api-key`](/cli/opencode#aether-opencode-api-key) | Manage LLM provider (BYOK) API keys |
| [`aether token`](/cli/token) | Manage platform API keys for the REST API |
| [`aether settings`](/cli/settings) | Manage account-level agent and model preferences |
| [`aether secret`](/cli/secret) | Manage project secret files |
| [`aether skill`](/cli/skill) | Push, pull, and sync saved agent skills |
| [`aether codex`](/cli/codex) | Manage Codex provider authentication |
| [`aether claude-code`](/cli/claude-code) | Manage Claude Code provider authentication |
| [`aether cursor`](/cli/cursor) | Manage Cursor (legacy) provider authentication |
| [`aether opencode`](/cli/opencode) | Manage OpenCode provider authentication |
| [`aether profile`](/cli/overview#profile) | Show the current user profile |
| [`aether config`](/cli/config) | View and manage CLI configuration |
| [`aether version`](/cli/overview#version) | Print version information |
| [`aether completion`](/cli/completion) | Generate shell completion scripts |

<Warning>
  Three commands sound alike but manage three different kinds of credential. Don't mix them up:

  | Command | Manages | Format |
  | - | - | - |
  | [`aether token`](/cli/token) | Platform API keys for programmatic REST access (`AETHER_TOKEN` bearer keys) | `aether_…` |
  | [`aether opencode api-key`](/cli/opencode#aether-opencode-api-key) | Bring-your-own LLM provider keys (OpenRouter) | `sk-or-…` |
  | [`aether auth token`](/cli/auth) | Prints the credential the CLI logged in with, for piping to other tools | `aether_…` |
</Warning>

## Resolving IDs (Short Prefixes)

Most commands that take an `<id>` argument — `project`, `task`, `workspace`, and `token` — accept a short prefix instead of the full UUID. For projects, tasks, and workspaces the prefix is matched against the first characters of the ID (the listings print the first 8 characters); for tokens, any unique prefix works.

```bash theme={"dark"}
# These are equivalent when the prefix is unique
aether task get a1b2c3d4-e5f6-7890-abcd-ef1234567890
aether task get a1b2c3d4
```

Resolution fails loudly: an unknown prefix returns "no … found matching", and a prefix that matches more than one record returns an "ambiguous prefix" error asking for a longer prefix. Values containing a `-` or 32+ characters are treated as full IDs and used as-is.

## Profile

Print the current user's profile (email, ID, display name, onboarding status).

```bash theme={"dark"}
aether profile
```

## Version

Print version, commit, Go version, and OS/arch.

```bash theme={"dark"}
aether version
```

```
aether version 0.1.0 (a1b2c3d)
  go: go1.26.4
  os/arch: darwin/arm64
```

<Note>
  The CLI docs are hand-written and verified against the source commands. They are not generated from the binary.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.