@amplitude/developer-cli

CLI and developer artifacts for the Amplitude Developer API.

amp manages Amplitude first-class platform primitives (projects, taxonomy, and feature flags) via the Developer API. Related CLIs:

• ampli — instrumentation and typed SDK codegen
• amplitude-wizard — onboarding and setup

These guide every change to the CLI (see AGENTS.md for the full version):

1. Obvious by default. The best surface needs no explanation — discoverable help, consistent verbs, safe defaults, and errors that tell you what to do next.
2. Code is marketing. This source is public; it is organized for clarity, with small single-purpose modules, familiar naming, and schema-validated inputs.
3. Test the seams that matter. Pure logic is unit tested and the safety-critical paths (auth precedence, destructive-action confirmation, credential permissions) are covered explicitly.
4. Two readers: humans and agents. Interactive output maximizes visibility and readability (tables, summaries); piped output is compact and lossless (minimal characters) so agents don't pay tokens for decoration.

npm install -g @amplitude/developer-cli
amp help

Or run without installing:

npx @amplitude/developer-cli help

Run amp auth login to authenticate via the OAuth device flow. Omit --profile and the CLI targets the active profile, or default when none is active. Picking a region stays explicit:

amp auth login --region us                       # device flow → "default" profile
amp auth status                                  # active credential, type, expiry
amp context

Profiles bind a credential to a region (its base_url), so an EU token can never be sent to prod. Name one explicitly when you want more than one:

amp auth login --profile eu --region eu          # activates the EU profile
amp auth use prod                                 # switch back (no re-auth)
amp auth list                                     # * marks the active profile
amp logout --profile eu                           # remove one
amp logout --all                                   # remove every profile

A bare amp auth login re-authenticates the active profile in place. Profiles are saved to ~/.amplitude/amp/credentials.json (0600).

Create an account with explicit inputs and consent:

amp auth signup --non-interactive \
  --email alex@example.com \
  --full-name "Alex Morgan" \
  --region us \
  --accept-tos

--non-interactive is required. Signup returns outstanding requirements without prompting, opening a browser, or polling. --json controls presentation; piped output is also compact JSON.

--accept-tos agrees to the Terms of Service and acknowledges the Privacy Policy. Every accepted request sends both document references for server validation. Missing consent returns the documents as required information before a signup request. Outdated references return the server's error on stderr; update the client and retry.

Inspect status before issuing authenticated commands: exit 0 can mean authorization is still required. The continuation includes a readable command and an argument array:

amp auth login poll --profile default --json

See amp auth login poll --help for polling options.

Profiles follow login's rules: select --profile, otherwise the active profile, otherwise default. Signup requires an explicit --region. Successful signup at the same endpoint updates its identity. Changing its endpoint requires --force. Existing credentials and activation remain until authentication succeeds and the replacement is saved, including when signup returns a pending challenge.

Prefer a Personal Access Token? amp auth pat --with-token --region <us|eu> reads a PAT from stdin (or a masked prompt at a terminal) and saves it as a profile — --profile optional (defaults to default), same force-explicit create rule, same store. --with-token is required.

echo "$PAT" | amp auth pat --with-token --region us

For CI or a one-off shell, set a raw token — it overrides stored profiles:

export AMP_TOKEN=amp_...        # amp_… is treated as a PAT, anything else a bearer

AMP_PROFILE selects a stored profile by name; amp auth token prints the active access token to stdout (TOKEN=$(amp auth token)).

amp context
amp projects list
amp events list --project <project_id> --limit 5
amp events create --project <project_id> --event-type my_event --display-name "My Event"
amp flags list --project <project_id> --limit 5
amp flags create --project <project_id> --key my-flag --name "My Flag"
amp flags get --project <project_id> --flag <flag_id>
amp flags archive --project <project_id> --flag <flag_id> --dry-run
amp heatmaps click-map --project <project_id> --page-url https://example.com/pricing
amp zoning zone-metrics --project <project_id> --page-url https://example.com/pricing --metric click_rate_pageview

With a credential available (amp auth login, or AMP_TOKEN set):

pnpm smoke

See docs/cli.md for the full smoke checklist and PAT scope notes.