Skip to content

cli.md

Latest commit

 

History

History
153 lines (114 loc) · 6.25 KB

cli.md

File metadata and controls

153 lines (114 loc) · 6.25 KB
Raw

Developer API CLI

amp is a manifest-driven CLI generated from the Amplitude Developer API OpenAPI spec. A handwritten runtime in src/cli.ts maps flags to HTTP requests.

Authentication

Authenticate via the OAuth device flow and save the result as a profile. Omit --profile and the CLI targets default — the implicit profile used when you don't name one. Picking a region stays explicit:

amp auth login --region us

That runs the device flow against the chosen region's Developer API, saves the token to ~/.amplitude/amp/credentials.json (0600), and activates the profile. A profile binds a credential to a region (base_url), so an EU token can never be sent to prod.

amp auth login --profile eu --region eu          # activates the EU profile
amp auth use prod                                 # switch (no re-auth)
amp auth list                                     # * marks the active profile
amp auth status                                   # type, base URL, expiry
amp logout --profile eu                           # remove one
amp logout --all                                   # remove every profile

A bare amp auth login re-authenticates the active profile in place (region from its record). --region maps us|eu to a base URL.

To use a Personal Access Token instead of the device flow:

echo "$PAT" | amp auth pat --with-token --region us            # stdin → "default" profile
amp auth pat --with-token --profile ci --region us             # name it; masked prompt at a TTY

--with-token reads the PAT from stdin when piped, or from a masked prompt at a terminal. Same rules as login: --profile is optional (defaults to default) and --region is required to create a profile; the credential is saved as { "type": "pat" }.

--with-token is mandatory: it makes the supply-an-existing-PAT path explicit and keeps the bare amp auth pat verb reserved.

Credential selection

Precedence (highest first): --token > AMP_TOKEN > --profile > AMP_PROFILE > the active (default) profile. AMP_TOKEN is king over profile selection so a CI-injected token can't be shadowed by a stray stored profile; amp auth status announces when it is in effect.

export AMP_TOKEN=amp_...        # one-off / CI; overrides stored profiles
export AMP_PROFILE=eu           # select a stored profile by name

Accepted forms for --token / AMP_TOKEN:

  • Raw PAT: amp_... (normalized to Bearer PAT=amp_...)
  • Prefixed: PAT=amp_...
  • Full bearer: Bearer PAT=amp_... (or any Bearer <jwt>)

amp auth token prints the active access token to stdout (TOKEN=$(amp auth token)).

Required scopes (examples)

amp auth login requests every scope the CLI can use by default (the granular read:/write: scopes below plus the legacy mcp:read/mcp:write org scopes), so all commands work immediately after login. The per-command scopes below document what each command needs.

Command family Scopes
context, projects list read:projects
events * read:taxonomy, write:taxonomy
flags * read:flags, write:flags
charts * read:analytics

Route-level scopes are defined on each OpenAPI operation (x-required-scopes).

When adding new CLI scopes, ensure the OAuth client used for amp auth login allows those scopes before default login requests them. This requires an out-of-band update on Amplitude's side — contact Amplitude if your integration needs additional scopes.

Developer API usage (server-side)

Authenticated requests to the Developer API (amp projects list, amp flags create, and other API commands) are measured and logged server-side as part of operating the service — route, HTTP status, your account/org, and client version (User-Agent).

Global flags

Flag / env Purpose
--region <us|eu> Data region name → base URL
--profile <name> / AMP_PROFILE Select a stored profile
--token / AMP_TOKEN / saved profile Auth token
--json Force raw JSON output (default when piped)
--yes Confirm DELETE operations
--dry-run Preview destructive/query side effects
--body-json '{...}' Merge extra JSON into request bodies

Help and output

amp help                  # product surfaces (context, projects, events, flags, charts, …)
amp help flags            # commands within a surface
amp flags list --help     # flags and examples for one command
amp version
amp auth status

In an interactive terminal, list and context commands print human-friendly tables and summaries. Pipe to a file or another command, or pass --json, for raw API JSON.

Prod smoke checklist

Run against a disposable project when possible. Requires a credential with the scopes listed above — either an active profile (amp auth login) or AMP_TOKEN.

export AMP_TOKEN=amp_...
pnpm smoke

Manual checklist:

  1. Health — GET /health returns 200 with {"status":"ok"}
  2. Context — amp context resolves auth and org/project context
  3. Projects — amp projects list
  4. Flags read — amp flags list --project <id> --limit 5
  5. Flags write — create → get → update description → archive dry-run → archive
  6. Charts read — amp charts list --project <id> --limit 5
  7. Events — list → create → update → (optional delete with --yes)

Known issue: flags update --enabled false fails for deployment-less flags. Avoid that path in smoke tests until it is fixed.

Generated files

Do not edit by hand:

  • src/generated/cli-manifest.ts — generated from the Developer API OpenAPI spec
  • openapi/bundled/* — the bundled Developer API OpenAPI spec

These artifacts are generated and kept in sync upstream.