Quick start

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

# or Homebrew (macOS/Linux) — no npm/Node.js required beforehand
brew install modus-data/tap/modus-cli

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

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:

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

Authenticate

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 Modus-owned api.getmodus.com / api.<env>.getmodus.com origins the CLI/SDK derive agent.* automatically (api.staging… → agent.staging…), so you only need one URL:

# Replace with your own staging PAT from the staging Modus app → Settings → API Tokens
export MODUS_API_KEY='modus_<orgUuid>_<prefix>_<secret>'
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:

modus login --no-oauth --base-url https://api.staging.getmodus.com

Escape hatch for custom origins: set MODUS_AGENT_HOST explicitly.

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.

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

Examples

# Chat with a scope (streams the response, then exits)
modus scopes chat 42 "What changed in revenue last week?"
modus scopes chat 42                        # same, but interactive

# Create a scope, then deploy it
modus scopes create --name "Revenue Analyst" --model claude-sonnet-5
modus scopes create --example > scope.json  # full config fixture
modus scopes create --file scope.json
modus scopes deploy 42

# Workflows
modus workflows list --pretty
modus workflows runs list 7
modus workflows runs get 7 wf_7_run_1
modus workflows run 42 "Run the weekly digest now"

# Context
modus context items list --context-type saved_query
modus context notes create "Q3 pricing" "We raised list price 8% in July."
modus context files upload ./report.pdf
modus context files upload ./docs --wait-until ready
modus context files upload-from-url https://example.com/report.pdf
modus context files list --pretty
modus context dashboards list --pretty
modus context dashboards create --example > dashboard.json
modus context dashboards create --file dashboard.json
modus context dashboards publish <dashboardId> --expected-revision 1
modus context dashboards elements list <dashboardId> --pretty
modus context dashboards layout update <dashboardId> --file layout.json

# Active runs
modus runs list-active --pretty
modus runs cancel <runId>

Features

• Scopes — chat, create, deploy, evaluations, memories, supervision, MCP configuration, ownership transfer.
• Workflows — create, trigger, run history, ownership transfer.
• Context — organization context items, notes, saved queries, file uploads, dashboards (drafts, publishing, version history, access, ownership transfer) and their tiles, filters and layout.
• Connections, usage, and org members.

Commands

Run modus --help or modus <topic> --help (e.g. modus scopes --help) for the full, current list — this README doesn't duplicate it since it drifts.

Development

pnpm --filter @getmodus/cli run build
pnpm --filter @getmodus/cli exec vitest run
./bin/dev.js --help   # run from source (tsx), no build needed