alter apps

An app owns API keys, provider configuration, agents, and grants. These commands manage the app objects themselves.

alter apps list      [--include-archived] [--no-include-stats]
alter apps create    --name <name> [--description ...] [--website-url ...]
alter apps show      <app-id>
alter apps update    <app-id> [--name ...] [--description ...] [--website-url ...]
alter apps legal-profile <app-id> --legal-name ... --privacy-url ... --terms-url ...
alter apps archive   <app-id>
alter apps unarchive <app-id>
alter apps delete    <app-id> [--confirm <name>]

Reads need dashboard_apps:read; create and update need dashboard_apps:write; legal-profile needs dashboard_apps:write and an organization-admin principal; archive / unarchive need dashboard_apps:admin; delete needs dashboard_apps:delete. Every command except delete accepts --output (delete prints only a confirmation line).

list

List apps in the current organization.

Flag	Default	Description
--include-archived	off	Include archived (soft-deleted) apps. Default is active-only.
--no-include-stats	stats on	Skip per-app grant / key / API-call counts (faster).

The command returns the server’s first page (up to 100 apps) as an array; it does not expose pagination flags.

alter apps list
alter apps list --include-archived --output json

create

Create a new app.

Flag	Required	Description
--name <name>	yes	App name (maximum 100 characters; control characters rejected).
--description <text>	no	Free-form description (maximum 500 characters; control characters rejected).
--website-url <url>	no	Public website URL (http:// or https://).

alter apps create --name "Acme Production" --description "Customer-facing app"

show

Show one app by ID.

alter apps show <app-id>

update

Patch app fields. At least one of --name, --description, or --website-url is required — an empty update is rejected. Names are limited to 100 characters and descriptions to 500, with control characters rejected.

alter apps update <app-id> --description "Renamed for Q3"

legal-profile

Set the Customer identity and policy links Wallet and Connect show to End Users before identity and authorization data is collected. URLs are validated locally and by the backend. Provide at least one support channel.

alter apps legal-profile <app-id> \
  --legal-name "Acme, Inc." \
  --privacy-url "https://acme.example/privacy" \
  --terms-url "https://acme.example/terms" \
  --support-email "support@acme.example" \
  --agent-purpose "Schedule meetings using the accounts you authorize."

Flag	Required	Description
--legal-name <name>	yes	Customer legal name displayed to End Users.
--privacy-url <url>	yes	Customer Privacy Policy (http:// or https://).
--terms-url <url>	yes	Customer Terms of Service (http:// or https://).
--support-url <url>	one support channel	Customer support URL.
--support-email <email>	one support channel	Customer support email.
--agent-purpose <text>	no	Short description of the application/agent purpose.

archive / unarchive

Archiving is a reversible soft-delete: the app disappears from the default apps list view but keeps all its keys, grants, providers, and audit history. Because archiving pulls an app out of the default view for the whole organization, both commands require the admin-tier dashboard_apps:admin scope (an organization admin). This is separate from dashboard_apps:delete, which gates the irreversible cascade — :admin does not grant it.

alter apps archive <app-id>
alter apps unarchive <app-id>   # 409 if the app isn't archived

delete

Warning

apps delete is an irreversible cascade. It permanently removes the app and every key, grant, secret, agent, and audit row beneath it. There is no undo. To hide an app without losing its data, use archive instead.

Because the cascade is permanent, delete is gated behind the separate dashboard_apps:delete scope (not bundled into :admin) and a type-to-confirm check:

• Interactive: the CLI prompts you to type the app’s exact name.
• Non-interactive (CI): pass --confirm <name> matching the app’s name. There is no --yes shortcut — the name must be surfaced so the audit trail records the intent.

# Interactive — prompts for the name
alter apps delete <app-id>

# CI — name supplied explicitly
alter apps delete <app-id> --confirm "Acme Production"

A wrong --confirm value exits 2 (USAGE); declining the interactive prompt exits 8 (CANCELLED).

Recipes

Provision an app in CI and pin it for later steps

APP_ID=$(alter apps create --name "ci-staging" --output json | jq -r '.id')
alter link "$APP_ID"   # subsequent steps in this directory skip --app

Review and clean up archived apps

# List what's archived...
alter apps list --include-archived --output json \
  | jq -r '.[] | select(.archived_at) | "\(.id)\t\(.name)"'
# ...then permanently delete one (name required as confirmation)
alter apps delete "$APP_ID" --confirm "ci-staging"

Related

• alter keys, alter providers, alter agents — the resources an app owns
• Workspace linking — pin a default app so commands skip --app
• Apps — the underlying concept