APImetrics CLI
A command-line interface for managing API monitors, schedules, SLOs, and more on the APImetrics platform, by APIContext Inc.
Documentation
For more information, please visit our main documentation site, available at https://docs.apicontext.com/cli.
Installation
Manual installation
The binaries for the APImetrics CLI can be downloaded from the releases page. Choose the appropriate version for your operating system and put the executable in your path for easy access from the command line.
MacOS
You can install the APImetrics CLI using Homebrew:
brew install apimetrics/tap/apimetrics
Windows
You can install the APImetrics CLI using the Windows Package Manager (winget):
winget install APIContext.APImetricsCLI
Linux
You can install the APImetrics CLI by downloading the binary from the releases page.
curl -LO https://github.com/APImetrics/APImetrics-cli/releases/latest/download/apimetrics-[version]-linux-amd64.tar.gz
tar -xzf apimetrics-[version]-linux-amd64.tar.gz
sudo mv apimetrics /usr/local/bin/apimetrics
Note: [version] should be replaced with the specific version you want to download, e.g., 0.0.1.
Getting Started
1. Log in
apimetrics login
This opens your browser for OAuth2 authentication. Your credentials are cached locally and refreshed automatically.
On a machine whose browser can't reach it — over SSH, in a container, or on a remote desktop — use the device flow instead:
apimetrics login --device
The CLI prints a URL and a short code. Open the URL in a browser on any device, check the code matches, and approve; the CLI finishes logging in once you do.
2. Select a project
All commands require an active project. Run the following to choose one:
apimetrics project select
To confirm which project is currently active:
apimetrics project show
3. Run your first command
# List all API calls in the current project
apimetrics list-calls
# List all schedules
apimetrics list-schedules
To see all supported commands, run
apimetrics --help
Service Accounts
A service account authenticates without a browser, which is what makes the
CLI usable from CI, cron jobs, and other headless environments. Create one in
the APImetrics web app and download the JSON file it gives you:
{
"name": "ci-runner",
"client_id": "...",
"client_secret": "...",
"audience": "https://client.apimetrics.io"
}
Point the CLI at that file with --service-account, and it authenticates every
request with those credentials instead of the cached browser login:
apimetrics list-calls --service-account ./ci-runner.apimetrics.json
The file holds a live secret — keep it out of version control, and prefer the
environment variable when you can:
export APIMETRICS_SERVICE_ACCOUNT=/secrets/ci-runner.apimetrics.json
apimetrics list-calls
Choosing a project
Service accounts are granted access to specific projects, and headless runs
can't answer an interactive project prompt. Name the project for the run with
--project-id, or its environment variable:
apimetrics list-calls \
--service-account /secrets/ci-runner.apimetrics.json \
--project-id ag9zfmFwaW1ldHJpY3MtcWNy...
export APIMETRICS_PROJECT_ID=ag9zfmFwaW1ldHJpY3MtcWNy...
--project-id applies to that run only and never overwrites the project saved
by project select. To see which projects a service account can reach, run
apimetrics project select --service-account ... from a terminal.
Notes
- Access tokens last an hour and are cached, keyed by the credentials
themselves — a service account never picks up your interactive login's token,
or another service account's. Rotating the secret invalidates the cache.
- The client credentials grant issues no refresh token (RFC 6749 §4.4.3): when
the access token expires the CLI simply requests a new one.
apimetrics login --service-account ... fetches a token without making an
API call, which is a quick way to check that credentials work.apimetrics logout --service-account ... drops that account's cached token
and leaves your browser login and selected project alone.
Create and update commands take their body from stdin (a heredoc is the clearest way to write one) or from CLI Shorthand arguments. There is no --body, --data, or -d flag.
apimetrics create-call <<'EOF'
{
"meta": {
"name": "My API Check"
},
"request": {
"method": "GET",
"url": "https://api.example.com/health"
}
}
EOF
You can also use CLI Shorthand as a concise alternative to JSON:
apimetrics create-call meta.name: "My API Check", request.method: GET, request.url: '"https://api.example.com/health"'
Quote any shorthand value that contains // (such as a URL), as above; unquoted, the shorthand parser rejects it. Shorthand also reads stdin and merges it with the arguments, so in scripts and other non-interactive shells redirect stdin from /dev/null (`... > ~/.bash_profile
Zsh
apimetrics completion zsh >> ~/.zshrc
Fish
apimetrics completion fish > ~/.config/fish/completions/apimetrics.fish
PowerShell
apimetrics completion powershell >> $PROFILE
Once enabled, press `tab` to explore available commands and their arguments.
## AI Agent Integration
The CLI includes built-in skills for AI coding agents (e.g. Claude Code). These skills teach agents how to create and configure monitors using the CLI.
**Install skills into Claude Code:**
```bash
apimetrics skills install --claude-code
Print all skills to stdout (for any agent or model that can read context):
apimetrics onboard
Available setup skills:
setup-api-monitor — Create an API (HTTP) monitor, attach a schedule, and verify itsetup-browser-monitor — Create a browser monitor, attach a schedule, and verify itsetup-mcp-monitor — Create an MCP protocol monitor with session steps
Claude Code Skills (operational workflows)
In addition to the setup commands above, the CLI ships eight richer, current-format Claude Code Skills covering the operational lifecycle. Install them into .claude/skills//SKILL.md:
apimetrics skills install --claude-skills
apimetrics-project-bootstrap — select a project and stand up verified scheduled monitoringapimetrics-weekly-health-review — analyze the previous seven complete daysapimetrics-failure-investigation — root-cause one result or a failure seriesapimetrics-incident-triage — blast radius and common cause across monitorsapimetrics-monitoring-estate-audit — coverage, hygiene, stale/duplicate monitorsapimetrics-slo-review — SLO design, attainment, and error-budget riskapimetrics-config-as-code — safe bulk checkout/diff/push workflowapimetrics-performance-analytics — latency percentiles, component timing, and DNS analytics
Read-only skills load automatically when a request matches; the two mutation skills require explicit invocation and gate every change behind approval.
Other agents (OpenAI Codex, Cursor, Gemini CLI, …)
The repo root ships an AGENTS.md — the cross-agent standard read by OpenAI Codex, Cursor, Gemini CLI, and others — that carries the same core CLI facts and workflow index. Any agent can also pull the full workflows on demand with apimetrics onboard, which prints the three setup skills followed by all eight workflow skills.
Configuration
Configuration and cached tokens are stored in platform-specific locations:
| OS | Config | Cache |
|---|
| macOS | ~/Library/Application Support/apimetrics/ | ~/Library/Caches/apimetrics/ |
| Linux | ~/.config/apimetrics/ | ~/.cache/apimetrics/ |
| Windows | %AppData%\apimetrics\ | %LocalAppData%\apimetrics\ |
Override these locations with environment variables:
export APIMETRICS_CONFIG_DIR=/path/to/config
export APIMETRICS_CACHE_DIR=/path/to/cache
--service-account and --project-id have environment variables too, so a CI
job can be configured once rather than repeating flags on every call:
export APIMETRICS_SERVICE_ACCOUNT=/secrets/ci-runner.apimetrics.json
export APIMETRICS_PROJECT_ID=ag9zfmFwaW1ldHJpY3MtcWNy...
Non-production builds
Builds for the non-production APImetrics environments install alongside the
production CLI: each has its own command name and its own config and cache
directories, so they can be logged in to different environments at the same
time.
| Environment | Command | API host | Config / cache directory |
|---|
| production | apimetrics | client.apimetrics.io | apimetrics |
| beta | apimetrics-beta | beta-client.apimetrics.io | apimetrics-beta |
| qc | apimetrics-qc | qc-client.apimetrics.io | apimetrics-qc |
| qc-stable | apimetrics-qc-stable | qc-stable.apimetrics.io | apimetrics-qc-stable |
| dev | apimetrics-dev | localhost:8080 | apimetrics-dev |
These environment variables all follow the command name, with hyphens replaced
by underscores — e.g. APIMETRICS_QC_STABLE_CONFIG_DIR and
APIMETRICS_QC_SERVICE_ACCOUNT. A service account is issued by one APImetrics
environment, so use it with the matching build.
Tagged environment builds are published on the
releases page as
prereleases, and are signed and notarized just like the production build, so
they run on macOS without a Gatekeeper warning. Homebrew and WinGet always
install the production CLI.
--version reports which environment a binary was built against:
$ apimetrics-qc-stable --version
apimetrics-qc-stable version 0.1.0
Environment: qc-stable (https://qc-stable.apimetrics.io)
Config directory: /Users/you/Library/Application Support/apimetrics-qc-stable
...
Note that the beta build authenticates against production Auth0, so logging
in to it uses your real production credentials.
Logout
apimetrics logout
This removes cached tokens. Run apimetrics login again to re-authenticate.
Add --service-account to remove just that service account's token.
Issues and Contributing
For support questions, visit APImetrics Support and open a request.
For reporting bugs or requesting features, please open an issue on the GitHub repository.
We welcome contributions! Feel free to fork the repository, make changes, and submit pull requests.