CLI

Alter CLI

Manage apps, keys, agents, providers, secrets, grants, and audit logs from the command line.

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.

Install

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

Requires Node 20+. The binary is named alter.

First commands

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

alter auth login

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 <app-id>

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

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 / wallet theming	—
`approvals`	Read-only HITL approval defaults	—
`sdk-passthrough`	One-off authenticated provider requests	—

Every namespace follows the same shape: alter <namespace> <verb> [arguments] [flags]. Run any command with --help for its full option list.

Global flags

These apply to every command:

Flag	Effect
`--output <format>`	`json`, `table`, or `jsonl`. List commands default to `table`; single-object commands default to `json`.
`--fields <a,b,c>`	Narrow JSON / JSONL output to specific top-level keys.
`--help`	Show help for the command or subcommand.
`--version`	Print the CLI version.

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.