@alter-ai/cli

Command-line client for the Alter Vault dev portal. Authenticates with a Personal Access Token (PAT) and exposes the dashboard's resource model as scriptable commands.

📖 Full docs: docs.alterauth.com/reference/cli

Install

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

Sign in

alter auth login                          # interactive browser flow
ALTER_PAT=alter_pat_... alter apps list   # headless / CI

Commands

auth                login | status | logout
apps                list | create | show | update | archive | unarchive | delete
keys                list | statistics | mint | show | rotate | revoke | rename
agents              list | create | show | update | suspend | resume | revoke | audit |
                    registry-list | registry-show |
                    (+ mint-key, list-keys, revoke-key, deprecate-key, undeprecate-key)
providers           list | list-catalog | create | show | update | delete
                    spec {list, status} | operations {list, get}
identity-providers  create | discover | webhook {enable, disable, rotate, status}
managed-secrets     list | show | create | rotate | delete | templates | access |
                    set-delegation-policy | set-allowed-hosts | users |
                    grants {list, list-for-agent, create, update, revoke} |
                    groups {list, show}
policy              show-app | simulate | rules {create, list, get, update, delete}
audit               list | show | explain | portal-actions | grant-events | traces |
                    threads | thread | agents | agent | integrity-check
grants              list | revoke
analytics           summary | dashboard | api-calls | by-provider | by-app |
                    policy | latency | errors
end-users           list | show
branding            get | set | reset
approvals           defaults | list | show
pats                whoami
link / unlink       pin an app to the current directory
design / verify     design-doc gate | code + runtime verification
init / doctor       project scaffolding | environment diagnosis
completion          install | print
self-update         --to <v>
sdk-passthrough     request <grant-id> --url <url> | resolve-identity

Data-returning commands expose --output=json|table|jsonl. For single-object reports (including design, verify, and doctor), jsonl falls back to pretty-printed JSON. --fields a,b,c is global but only affects JSON / JSONL emitted through the shared output formatter; it is inert for table output and commands that print confirmation text. See scripting for exit codes and CI patterns, and authentication for token storage details.

Agent scope updates use optimistic concurrency because --scopes replaces the complete provider allowlist. Read the current version, then include it in the update so a concurrent operator change is rejected instead of overwritten:

alter agents show --app "$APP_ID" --agent "$AGENT_ID" --output=json
alter agents update --app "$APP_ID" --agent "$AGENT_ID" \
  --scopes '{"github":["read:user"]}' --expected-version 7

A concurrent change exits with code 5 and a safe conflict message. Fetch the agent again, reconcile the desired scopes, and retry with its new version.

License

MIT