Alter CLI

alter is the command-line client for the Alter developer portal. The day-to-day dashboard operations — create apps, mint keys, configure providers, issue managed-secret grants, read the audit log — are available as scriptable commands, authenticated with a Personal Access Token (PAT). A few org-wide and destructive operations stay dashboard-only by design (see What’s not in the CLI).

It’s built for two audiences: operators who’d rather stay in the terminal than click through the dashboard, and CI pipelines that need to provision Alter resources as part of a deploy.

Note

The CLI manages the dashboard surface (apps, keys, configuration). It is not the runtime SDK — application code that calls third-party APIs uses the Python or TypeScript SDK. The one bridge between them is alter sdk-passthrough, an escape hatch for one-off runtime requests while debugging.

Install

npm install -g @alter-ai/cli
alter --version

Requires Node 20.10 or later. The binary is named alter.

The developer portal shows these first commands too — on the dashboard under Build with your coding agent, and behind the CLI & MCP button in the header (inside an application it adds alter link pinned to that application) — alongside the Alter Docs MCP server setup, so a coding agent can run them for you.

First commands

Sign in

Opens the dashboard in the browser for the Authorize step, and the CLI receives a freshly-minted PAT.

alter auth login

Confirm it worked with alter auth status: it shows the active PAT, its scopes, and its expiry, and exits 3 when you are not signed in. The CLI keeps the token in your OS keychain, or in a fallback file when no keychain is available; see Your Credentials for every credential onboarding creates and where each belongs.

For CI and headless hosts, pass a pre-minted PAT instead.

Pin a default app

Most commands operate on one app. Pin it once per project so you don’t retype the ID. alter link takes the app’s UUID: find it in the id column of alter apps list, or create a new app and link it in one go:

alter apps list                      # existing app: copy its id
alter link <app-id>

# or create a new app and pin it
APP_ID=$(alter apps create --name my-app --output json | node -p 'JSON.parse(require("fs").readFileSync(0, "utf8")).id')
alter link "$APP_ID"

Node is already required by the CLI; this command needs no JSON utility. Confirm the pin with alter link --status. If creation succeeded but linking failed, find the new app’s ID with alter apps list and run alter link <app-id>; do not create the app again.

From anywhere in that directory tree, --app becomes optional. See workspace linking.

--app also accepts the app’s name (resolved via alter apps list, so the PAT needs dashboard_apps:read); an ambiguous name errors with the candidate IDs. A UUID-shaped value is always treated as an ID — an app literally named like a UUID must be targeted by its ID. ALTER_APP_ID and the workspace pin are UUID-only.

Run a command

alter apps list
alter keys list
alter audit list --since 24h

The resource model

The CLI mirrors the dashboard’s resource model. Each namespace maps to a concept you already know from the docs:

Namespace	Manages	Concept
auth	Sign in / out, inspect the active PAT	—
apps	Applications	Apps
keys	Runtime API keys	API keys
agents	Managed-agent identities + their keys	Agents
providers	OAuth provider configuration	Providers
managed-secrets	Backend credentials, grants, and access	Managed secrets
identity-providers	End-user identity provider setup + webhook lifecycle	Identity providers
policy	App-level policy reads + policy-rule management	Policies
audit	The audit log	Audit logs
analytics	Read-only usage analytics	—
grants	End-user OAuth + managed-secret grants	—
end-users	Read-only end-user list/detail	—
branding	Connect-widget theming	—
approvals	Read-only HITL approvals and deployment defaults	—
sdk-passthrough	One-off runtime provider requests and identity resolution	—

The remaining top-level commands cover CLI and project operations:

Command	Purpose
pats whoami	Inspect the active PAT.
link / unlink	Manage the current directory’s app pin.
design / verify	Validate the integration design and implementation.
init / doctor	Configure onboarding guidance and diagnose the integration.
completion	Print or install static shell completion.
self-update	Update an npm-installed CLI.

Namespaces generally follow alter <namespace> <verb> [arguments] [flags]; root commands such as link, unlink, verify, init, doctor, and self-update omit the verb. Run any command with --help for its full option list.

Global flags

Commander provides these program-level or shared output controls:

Flag	Effect
--fields <a,b,c>	Global option. Narrow JSON / JSONL emitted through the shared formatter to specific top-level keys; inert for tables and commands that print confirmation text.
--help	Show help for the selected command or subcommand.
--version	Program-level version output.
--output <format>	A per-command option on data-returning commands, not a global option. It accepts json, table, or jsonl. List commands normally default to table; object commands normally default to json. For a single-object response, jsonl falls back to pretty-printed JSON.

See output & scripting for how to combine these in pipelines, plus the exit-code contract.

What’s not in the CLI

A few dashboard operations are intentionally dashboard-only, because a single scripted call should never be able to weaken security for an entire organization:

• Minting or revoking PATs — a PAT can’t manage another PAT, including itself.
• Org-wide key policy — it affects every key and every grant in the org.
• Identity-provider re-pointing, deletion, and config reads — the CLI can create an app’s identity provider and manage its webhooks (both behind explicit, wildcard-excluded scopes), but changing or removing an already-trusted issuer, and reading the full config, stay dashboard-only.
• Org-level policy rules — rules that apply across every app in the organization are authored and read in the dashboard only. Per-app policy rules (including IP-allowlist and time-window rules) are the scriptable surface, behind their own explicit permissions.

This mirrors how GitHub keeps org-security settings web-only. The boundary is deliberate, not a missing feature.

Next steps

Authentication

Browser sign-in, headless PATs, and where credentials are stored.

Output & scripting

Output formats, exit codes, workspace linking, and shell completion.