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

# Modus CLI

> Install @getmodus/cli and run Modus from a terminal, CI pipeline, or agent.

The official command-line client for Modus — chat with your scopes, manage workflows and context, and script against the Modus API from a terminal, a CI pipeline, or an agent.

**Package:** [`@getmodus/cli`](https://www.npmjs.com/package/@getmodus/cli) on npm (`modus` binary).

## Quick start

```bash theme={null}
npm install -g @getmodus/cli   # the -g is required — without it, `modus` won't be on your PATH

modus login                  # opens your browser to sign in
modus scopes list --pretty   # confirm it worked
```

<details>
  <summary><strong>Getting a permission error (EACCES)?</strong></summary>

  Your npm install prefix isn't writable by your user — common when Node was
  installed via an OS installer rather than a version manager. Point npm at a
  directory you own instead of using `sudo`:

  ```bash theme={null}
  mkdir -p ~/.npm-global
  npm config set prefix ~/.npm-global
  echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc   # zsh — use ~/.bashrc if you're on bash
  source ~/.zshrc                                                # or: source ~/.bashrc
  npm install -g @getmodus/cli
  ```
</details>

## Authenticate

```bash theme={null}
modus login              # browser-based OAuth (default) — interactive/local use
modus login --no-oauth   # PAT prompt instead — CI/scripts/headless
modus whoami             # confirm the resolved org/token/auth method
```

* **OAuth (default)** opens your browser and requests exactly the access your
  account already has in the Modus web app — nothing more, nothing held back.
  The access token refreshes automatically; `modus logout` revokes it
  server-side.
* **CI/scripts:** set `MODUS_API_KEY` — it always overrides the stored
  credential and is the preferred way to authenticate non-interactively.
* Avoid `modus login --token modus_xxx` — a token on the command line is
  readable from shell history, `ps`, and CI logs.

### Staging (and other non-prod)

Point the CLI at staging with a staging PAT and `MODUS_BASE_URL`. Chat uses a
separate agent host; for standard `api.*` origins the CLI/SDK derive
`agent.*` automatically (`api.staging…` → `agent.staging…`), so you only need
one URL:

```bash theme={null}
export MODUS_API_KEY='modus_…'   # staging PAT
export MODUS_BASE_URL='https://api.staging.getmodus.com'

modus whoami --pretty
modus scopes list --pretty
modus scopes chat 42 "what can you do?"
```

Or persist via login:

```bash theme={null}
modus login --no-oauth --base-url https://api.staging.getmodus.com
```

Escape hatch for custom origins: set `MODUS_AGENT_HOST` explicitly.

See [Authentication](/authentication) for token format and best practices.

## Output

* Commands that return data print **compact JSON by default** — pipe it to
  `jq`, a script, or an agent.
* Pass `--pretty` for a human-readable table or summary instead.
* **Exception:** `chat` / `scopes chat` stream raw response text by default;
  pass `--json` on those two for structured SSE events instead.

```bash theme={null}
modus scopes list             # {"items":[...],"nextPageToken":null}
modus scopes list --pretty    # aligned table
```

## Global flags

Most commands inherit:

* `--pretty` — human-readable table/summary instead of compact JSON

Chat commands (`modus chat`, `modus scopes chat`) stream text by default; pass `--json` for structured events.

## Next steps

* Browse the full [CLI command reference](/cli/overview) (every `modus` command)
* [Python SDK](/guides/sdk-python) / [TypeScript SDK](/guides/sdk-typescript)
* [API](/api-reference)