Read-first Amplitude Analytics API surface for exports, cohorts, events, users, and chart-style analytics queries.
Created by @debgotwired (Deb Mukherjee).
Quick Start
1. Install
See Install above.
2. Set Up Credentials
Get your API key from your API provider's developer portal. The key typically looks like a long alphanumeric string.
export AMPLITUDE_USERNAME="<paste-your-key>"
You can also persist this in your config file at ~/.config/amplitude-read-pp-cli/config.toml.
3. Verify Setup
amplitude-pp-cli doctor
This checks your configuration and credentials.
4. Try Your First Command
amplitude-pp-cli annotations
Usage
Run amplitude-pp-cli --help for the full command reference and flag list.
Commands
annotations
Manage annotations
amplitude-pp-cli annotations - List project annotations.
cohorts
Manage cohorts
amplitude-pp-cli cohorts get - Get cohort metadata or membership export status.amplitude-pp-cli cohorts list - List behavioral cohorts.
event_exports
Manage event exports
amplitude-pp-cli event-exports - Export raw event data over a time range.
events
Manage events
amplitude-pp-cli events - List event types tracked in an Amplitude project.
funnels
Manage funnels
amplitude-pp-cli funnels - Query funnel conversion metrics.
retention
Manage retention
amplitude-pp-cli retention - Query retention metrics.
revenue
Manage revenue
amplitude-pp-cli revenue - Query revenue analytics.
segmentation
Manage segmentation
amplitude-pp-cli segmentation - Query event segmentation metrics.
users
Manage users
amplitude-pp-cli users <user_id> - Get a user profile by user ID.
usersearch
Manage usersearch
amplitude-pp-cli usersearch - Search users by user ID, device ID, or user property filters.
Output Formats
# Human-readable table (default in terminal, JSON when piped)
amplitude-pp-cli annotations
# JSON for scripting and agents
amplitude-pp-cli annotations --json
# Filter to specific fields
amplitude-pp-cli annotations --json --select id,name,status
# Dry run — show the request without sending
amplitude-pp-cli annotations --dry-run
# Agent mode — JSON + compact + no prompts in one flag
amplitude-pp-cli annotations --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
amplitude-pp-cli doctor
Verifies configuration, credentials, and connectivity to the API.
Configuration
Config file: ~/.config/amplitude-read-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
AMPLITUDE_USERNAME | per_call | Yes | |
AMPLITUDE_PASSWORD | per_call | Yes | Set to your API credential. |
agentcookie (optional)
If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, amplitude-pp-cli doctor reports agentcookie: detected and auth-status labels the source as agentcookie. Skip this section if you don't use agentcookie - the CLI works the same as any other.
Troubleshooting
Authentication errors (exit code 4)
- Run
amplitude-pp-cli doctor to check credentials
- Verify the environment variable is set:
echo $AMPLITUDE_USERNAME
Not found errors (exit code 3)
- Check the resource ID is correct
- Run the
list command to see available items
Generated by CLI Printing Press