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

# Install the CLI

> Install the asteroid command, sign in, and pick an organization.

The `asteroid` command calls the Asteroid API from your terminal, scripts and CI. It needs Node.js 22 or later.

**1. Install**

```bash theme={null}
npm install -g @asteroidai/cli
```

**2. Sign in**

```bash theme={null}
asteroid login
```

The CLI prints a code and opens your browser. Confirm the code to sign in. If you belong to more than one
organization, pick one. Then the CLI offers to install the Asteroid skills for Claude Code and Cursor.
Pass `--no-skills` to skip that step. `asteroid skill sync` installs or refreshes them at any time.

**3. Check it works**

```bash theme={null}
asteroid whoami
asteroid workflow list
```

Your user, organization and workflows come back.

## Organizations

`asteroid orgs` lists the organizations you can act in. `asteroid use <org>` sets the default by id or name.
`--org <org>` acts in another organization for one command.

## Skills

The Asteroid skills are `SKILL.md` files, in the Agent Skills format, that teach a coding agent how to use
the platform. `asteroid login` writes them into every skills directory it finds:

| Directory | Read by |
| :- | :- |
| `~/.claude/skills` | Claude Code |
| `~/.cursor/skills` | Cursor |
| `~/.agents/skills` | Agents that follow the Agent Skills convention |

`asteroid skill sync` brings them up to date. It writes the files that changed, removes the skills the API no longer
serves (`--no-remove` keeps them), and leaves a skill directory it did not create alone.

Do not edit an installed skill. The next sync overwrites the edit. If a skill is missing something about how a portal
works that would have helped you build your automation, save it as a portal memory with
`asteroid memory create --portal <name> --description <line> --content <text>`. Asteroid reviews portal memory to
improve the skill.

Keep it to general knowledge of the portal. It is not about one customer's account or instance of it.

| Save | Do not save |
| :- | :- |
| The portal uses SMS-only 2FA | One customer's settings, users or data |
| A session ends after 20 minutes of no activity | A one-off run failure |
| Claims are under Billing, then Batches, not under Claims | A defect in Asteroid. Use `asteroid bug report` |
| A site we have no skill for, and how it signs in | Patient data, credentials or customer names |

Once a day, a
command run at a terminal with your sign-in, without `--json`, says when the installed skills are out of date.
Commands run with `ASTEROID_API_KEY` never say it. `asteroid skill list` and `asteroid skill get <name>` show
the skills without installing them.

## CI and agents

Set `ASTEROID_API_KEY` instead of signing in. An API key belongs to one organization, so `--org` does not apply.

```bash theme={null}
export ASTEROID_API_KEY=...
asteroid execution list --json
```

Add `--json` to get the API response as JSON. Scripts should read `--json`, because the text output may change
between releases. Exit codes: 0 ok, 1 API or sign-in error, 2 usage error.

## Shell completion

Load the completion script when your shell starts.

| Shell | Add this line | To |
| :- | :- | :- |
| zsh | `source <(asteroid complete zsh)`, after `compinit` | `~/.zshrc` |
| bash | `source <(asteroid complete bash)` | `~/.bashrc` |
| fish | `asteroid complete fish \| source` | `~/.config/fish/config.fish` |
| PowerShell | `asteroid complete powershell \| Out-String \| Invoke-Expression` | `$PROFILE` |

## Environment

| Variable | Use |
| :- | :- |
| `ASTEROID_API_KEY` | Authenticate with an API key instead of `asteroid login`. |
| `ASTEROID_API_URL` | API host. Defaults to `https://odyssey.asteroid.ai`. |
| `ASTEROID_ORG` | Default organization, by id or name. |
| `ASTEROID_CONFIG_DIR` | Where the CLI keeps its config and, without a keychain, its sign-in. |
| `ASTEROID_NO_BROWSER` | Print the sign-in link without opening a browser. |
| `ASTEROID_NO_KEYCHAIN` | Store the sign-in in a private file, not the OS keychain. |

## Next

> [card] [CLI reference](https://docs.asteroid.ai/cli/reference.md)
>
> Every command, its arguments and its flags

> [card] [Call a workflow](https://docs.asteroid.ai/integrate/call-a-workflow.md)
>
> Run workflows from your own code


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