@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

Design tenets

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.

Install

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

Or run without installing:

npx @amplitude/developer-cli help

Authentication

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).

Signup

Create an account with explicit inputs. By utilizing this command you agree to the Terms of Service and acknowledge the Privacy Policy applies.

amp auth signup \
  --email [email protected] \
  --full-name "Alex Morgan" \
  --region us \
  --accept-tos

--non-interactive skips browser interaction and waiting for authorization. --json controls output format; piped output is compact JSON.

--accept-tos passes the Terms of Service and Privacy Policy URLs alongside the signup request.

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)).

Examples

amp context
amp projects list
amp projects api-keys get --project <project_id>
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 guides list --project <project_id> --limit 10
amp surveys get --project <project_id> --survey <survey_id> --include-unpublished-changes
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

Project ingestion API key

Explore the project API-key commands with amp projects api-keys --help, or add --json for structured help.

Retrieve a project's primary ingestion API key using your authenticated profile or supplied token:

amp projects api-keys get
amp projects api-keys get --project 12345
amp projects api-keys get --project 12345 --json
AMPLITUDE_API_KEY="$(amp projects api-keys get --project 12345 --raw)"

At a terminal, the command shows the project name, ID, and full key. Piped output is compact API JSON with the key at data.api_key; --json forces JSON in any environment. --raw prints only the key followed by a newline and cannot be combined with --json.

Supply a positive integer project ID. --project-id and --project_id are also accepted. You can omit the selector when the organization has exactly one non-deleted project; otherwise use amp projects list to find its ID.

Retrieval requires projects:read and permission to view the project's API key. The command retrieves the designated project key without creating, rotating, or saving it. Failures leave stdout empty and report the error on stderr.

Smoke test

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.