# ai& CLI

Source: https://docs.aiand.com/cli/

The ai& CLI, `aiand`, signs you in through your browser and manages your API key for you. It sets up coding agents to run on ai&, sends prompts, and covers the everyday console tasks (model catalog, request logs, usage) from the terminal. It is open source at [github.com/aiandlabs/aiand-cli](https://github.com/aiandlabs/aiand-cli).

```bash
npm install -g @aiand/cli
aiand code                 # sign in, set up OpenCode, and open it on ai&
aiand run "hello"          # or send a single prompt
```

## Install

The CLI requires Node.js 22 or newer.

<Tabs syncKey="os">
<TabItem label="npm">

```bash
npm install -g @aiand/cli
```

</TabItem>
<TabItem label="macOS / Linux">

```bash
curl -fsSL https://raw.githubusercontent.com/aiandlabs/aiand-cli/main/install.sh | bash
```

</TabItem>
<TabItem label="Windows">

```powershell
irm https://raw.githubusercontent.com/aiandlabs/aiand-cli/main/install.ps1 | iex
```

</TabItem>
</Tabs>

The install scripts add `aiand` to your `PATH` by editing your shell profile. Set `AIAND_NO_MODIFY_PATH=1` to skip that change.

### Update and uninstall

To update, run the install command again.

To uninstall, the install script first turns off every coding agent aiand set up, then removes the CLI. Your profiles and credentials under `~/.config/aiand` are kept.

<Tabs syncKey="os">
<TabItem label="npm">

```bash
aiand init --off
npm uninstall -g @aiand/cli
```

</TabItem>
<TabItem label="macOS / Linux">

```bash
bash ~/.aiand/cli/install.sh uninstall
```

</TabItem>
<TabItem label="Windows">

```powershell
& "$env:USERPROFILE\.aiand\cli\install.ps1" uninstall
```

</TabItem>
</Tabs>

## Sign in

```bash
aiand login
```

`aiand login` opens your browser. Approving the sign-in creates an [API key](/organizations/api-keys/) for your organization, named `aiand@<hostname>` so you can tell machines apart in the console. If browser sign-in can't finish (no browser, a timeout, or no terminal), the CLI switches to a code you approve from any device:

```
  Your code   BCDF-GHJK
  Approve at  https://api.aiand.com/auth/device?user_code=BCDF-GHJK
```

To use a key you already created in the console instead:

```bash
aiand login --paste                # masked prompt
aiand login --with-token < key.txt # read the key from stdin
```

`aiand whoami` shows the signed-in identity, organization, and key expiry. `aiand status` adds where the key is stored and which coding agents are set up.

`aiand logout` offers to revoke a key that `aiand login` created. A pasted key is only removed from this machine; revoke it in the console.

### Where the key is stored

The key is stored in the OS keychain when one is available, otherwise in an encrypted file under `~/.config/aiand/`. The encryption key for that file sits next to it, so it protects against a casual look, not against anyone who can read the directory. Set `AIAND_KEY_STORAGE=plaintext` to store the key in a plain owner-only file instead.

Keys created by `aiand login` last 30 days. The CLI rotates them automatically during their last 3 days, or immediately if the API rejects one. Pasted keys are never rotated or revoked by the CLI.

<Aside type="tip">
  In CI and scripts, skip `aiand login` and set `AIAND_API_KEY`. The CLI uses that key directly and
  writes nothing to disk.
</Aside>

## Commands

| Command                               | What it does                                                     |
| ------------------------------------- | ---------------------------------------------------------------- |
| `aiand login` / `aiand logout`        | Start or end this machine's session                              |
| `aiand whoami`                        | Identity, organization, and key expiry                           |
| `aiand status`                        | Sign-in state and each coding agent's setup                      |
| `aiand code`                          | Open OpenCode on ai&, setting it up first if needed              |
| `aiand <agent>`                       | Open a coding agent on ai& the same way                          |
| `aiand <agent> on` / `off` / `status` | Set up a coding agent to use ai&, remove that setup, or check it |
| `aiand init`                          | Detect installed coding agents and set them up in one go         |
| `aiand run-agent <agent>`             | Run a coding agent on ai& for one session, changing no config    |
| `aiand restore <agent> --force`       | Put an agent's config back as it was before aiand changed it     |
| `aiand run <prompt>`                  | Send one prompt and stream the answer to stdout                  |
| `aiand chat`                          | Interactive conversation                                         |
| `aiand models`                        | Model catalog, priced in your billing currency                   |
| `aiand logs`                          | Recent requests, with `--follow` to tail new ones                |
| `aiand usage`                         | Requests and tokens, compared with the previous period           |
| `aiand orgs`                          | Organizations you belong to                                      |
| `aiand config`                        | Profiles and defaults                                            |
| `aiand key export`                    | Print the active key, for piping into another tool               |

Most commands accept `--json`, and every command accepts `--help`.

## Coding agents

The CLI supports three coding agents. `<agent>` is one of:

| Agent       | Command                            | Guide                                     |
| ----------- | ---------------------------------- | ----------------------------------------- |
| OpenCode    | `aiand opencode` (or `aiand code`) | [OpenCode](/integrations/opencode/)       |
| Claude Code | `aiand claude`                     | [Claude Code](/integrations/claude-code/) |
| Codex       | `aiand codex`                      | [Codex](/integrations/codex/)             |

`aiand <agent>` opens the agent on ai&. If you're signed out, it signs you in. If the agent isn't installed, it offers to install it. If the agent isn't set up for ai& yet, it runs `on` first, so the agent's own command uses ai& afterwards too.

```bash
aiand claude             # open Claude Code on ai&, setting it up first if needed
aiand claude on          # set up Claude Code to use ai&
aiand claude status      # check what Claude Code is configured to use
aiand claude off         # remove only what aiand added
aiand run-agent claude   # use ai& for this one session, change nothing
aiand init --all         # set up every installed agent
```

Arguments after the agent name are passed to the agent unchanged, as in `aiand claude -p "explain this repo"`. Put aiand's own flags before the agent name (`aiand --profile work codex`), and put `--` before an argument aiand would read as a verb (`aiand opencode -- status`). Pass `--model <id>` to `on` to choose the model.

`on` snapshots the agent's config before its first change, and `off` removes only what aiand added. To return to the exact config from before aiand, run `aiand restore <agent> --force`. What `on` writes for each agent is described in its guide.

<Aside type="note">
  When your key rotates, the CLI updates the agents it set up, so they keep working without running
  `on` again.
</Aside>

## Run prompts

```bash
aiand run "why is the sky blue?"
cat main.ts | aiand run "review this file"
aiand run -m deepseek-ai/deepseek-v4-flash --system "be terse" "summarize CAP theorem"
aiand run --no-stream --json "hello" | jq .usage
aiand chat
```

Piped input is appended to the prompt. The answer goes to stdout and everything else to stderr, so `aiand run "..." > out.md` saves only the answer. After each answer, a footer shows the model, tokens, cost, time, and request ID; `-q` hides it.

Without `-m`, the CLI uses your profile's model, or the recommended default from the catalog. `-m auto` lets ai& choose per request where your account supports it; see [Automatic Selection](/models/auto/). Set a default with `aiand config set model <id>`.

In `aiand chat`, type `/help` to list the in-session commands, such as `/model <id>` to switch models.

## Models, logs, and usage

```bash
aiand models --capability vision   # filter the catalog
aiand logs --range 1h --errors     # only failed requests
aiand logs --follow                # tail new requests
aiand usage --range 30days
aiand usage --metrics              # full breakdown
```

- `aiand models` lists the [catalog](/models/catalog/) with prices per 1M tokens in your billing currency. It also works signed out, priced in USD. Filter with `--search`, `--capability`, and `--sort`.
- `aiand logs` reads the [request logs](/analytics/logs/). `--range` takes `15m`, `1h`, `6h`, `24h` (default), `7days`, or `30days`.
- `aiand usage` summarizes [usage](/billing/usage/) against the previous period. `--range` takes `1h`, `24h`, `7days` (default), `30days`, or `3months`.

Logs and usage cover your whole organization, not just this machine.

## Organizations and profiles

The CLI's key is scoped to one organization, chosen at sign-in. `aiand orgs` lists the organizations you belong to. To work in a different organization, change your default organization in the console and run `aiand login --force`.

Profiles keep separate sign-ins, so each profile can hold a key for a different organization:

```bash
aiand login --profile work
aiand --profile work usage
aiand config use work              # make it the default profile
```

See [Switching Orgs](/organizations/switching/) for how organizations apply to API requests.

## Configuration

```bash
aiand config                       # current settings
aiand config set model deepseek-ai/deepseek-v4-flash
aiand config profiles              # list profiles
aiand config path                  # where the files are
```

Settings live in `~/.config/aiand/config.json` (or under `$XDG_CONFIG_HOME`). Credentials are kept in a separate file, so the config file is safe to share. Flags take precedence over environment variables, which take precedence over the stored profile.

| Variable               | Effect                                                                          |
| ---------------------- | ------------------------------------------------------------------------------- |
| `AIAND_API_KEY`        | Use this key; no sign-in, nothing stored                                        |
| `AIAND_PROFILE`        | Profile to use                                                                  |
| `AIAND_BASE_URL`       | API endpoint (default `https://api.aiand.com`)                                  |
| `AIAND_AUTH_URL`       | Sign-in endpoint, if different from the API                                     |
| `AIAND_CONFIG_DIR`     | Where config and credentials live                                               |
| `AIAND_HOME`           | Home directory to look for agent configs in, such as your Windows home from WSL |
| `AIAND_KEY_STORAGE`    | `keychain`, `file`, or `plaintext`                                              |
| `AIAND_NO_BROWSER=1`   | Never open a browser; print the sign-in link instead                            |
| `AIAND_UPDATE_CHECK=0` | Turn off the daily update notice                                                |
| `NO_COLOR`             | Turn off color                                                                  |

## Exit codes

| Code  | Meaning                                              |
| ----- | ---------------------------------------------------- |
| `0`   | Success                                              |
| `1`   | Request or usage error; the message says which       |
| `2`   | Not signed in, or the session could not be refreshed |
| `3`   | Sign-in denied, or the code expired                  |
| `70`  | A bug in the CLI; the stack trace is printed         |
| `127` | Unknown command, or the coding agent isn't installed |
| `130` | Interrupted (Ctrl-C)                                 |

`aiand status` exits `0` when signed in, even if ai& can't be reached to check the key, and `1` only when signed out, so scripts that check it keep working during an outage.

Report bugs and request features on [GitHub](https://github.com/aiandlabs/aiand-cli/issues).