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.

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.

Passing Input

All create and update commands read a JSON body from stdin using a heredoc. There is no --body, --data, or -d flag.

apimetrics create-call &lt;&lt;'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

Or pipe from a file:

apimetrics create-call &lt; my-call.json

Output Formats

Use -o / --rsh-output-format to control output:

Format	Description
`auto` (default)	Pretty in terminal, JSON when piped
`json`	Standard JSON
`yaml`	YAML
`table`	Tabular layout (best for lists)
`readable`	Colorized human-readable format
`gron`	Grep-friendly flattened format

# Table output
apimetrics list-calls -o table

# Raw JSON for scripting
apimetrics list-calls -o json

# Filter results with a query expression
apimetrics list-calls -f body[0].meta.name

When output is redirected to a pipe or file, color is disabled and only the body is printed as JSON automatically.

Global Flags

These flags work with every command:

Flag	Short	Description
`--rsh-output-format`	`-o`	Output format (auto/json/yaml/table/readable/gron)
`--rsh-filter`	`-f`	Filter/project response using a query expression
`--rsh-raw`	`-r`	Raw output (strips quotes from strings)
`--rsh-verbose`	`-v`	Verbose logging
`--rsh-header`	`-H`	Add a request header (repeatable)
`--rsh-query`	`-q`	Add a query parameter (repeatable)
`--rsh-profile`	`-p`	Use a named auth profile
`--rsh-server`	`-s`	Override the API server base URL
`--rsh-no-cache`		Disable HTTP caching
`--rsh-no-paginate`		Disable automatic pagination
`--rsh-retry`		Retry count (default 2)
`--rsh-timeout`	`-t`	HTTP request timeout
`--rsh-insecure`		Disable TLS verification
`--service-account`		Authenticate with a service account file instead of a browser login
`--project-id`		Use this project for the run, overriding the selected project

Shell Completion

Enable tab completion for your shell:

# Bash
apimetrics completion bash &gt;&gt; ~/.bash_profile

# Zsh
apimetrics completion zsh &gt;&gt; ~/.zshrc

# Fish
apimetrics completion fish &gt; ~/.config/fish/completions/apimetrics.fish

# PowerShell
apimetrics completion powershell &gt;&gt; $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:

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 it
setup-browser-monitor — Create a browser monitor, attach a schedule, and verify it
setup-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 monitoring
apimetrics-weekly-health-review — analyze the previous seven complete days
apimetrics-failure-investigation — root-cause one result or a failure series
apimetrics-incident-triage — blast radius and common cause across monitors
apimetrics-monitoring-estate-audit — coverage, hygiene, stale/duplicate monitors
apimetrics-slo-review — SLO design, attainment, and error-budget risk
apimetrics-config-as-code — safe bulk checkout/diff/push workflow
apimetrics-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.

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.

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

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.

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

{
  "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...

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.

Passing Input

All create and update commands read a JSON body from stdin using a heredoc. There is no --body, --data, or -d flag.

apimetrics create-call &lt;&lt;'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

Or pipe from a file:

apimetrics create-call &lt; my-call.json

Output Formats

Use -o / --rsh-output-format to control output:

Format	Description
`auto` (default)	Pretty in terminal, JSON when piped
`json`	Standard JSON
`yaml`	YAML
`table`	Tabular layout (best for lists)
`readable`	Colorized human-readable format
`gron`	Grep-friendly flattened format

# Table output
apimetrics list-calls -o table

# Raw JSON for scripting
apimetrics list-calls -o json

# Filter results with a query expression
apimetrics list-calls -f body[0].meta.name

When output is redirected to a pipe or file, color is disabled and only the body is printed as JSON automatically.

Global Flags

These flags work with every command:

Flag	Short	Description
`--rsh-output-format`	`-o`	Output format (auto/json/yaml/table/readable/gron)
`--rsh-filter`	`-f`	Filter/project response using a query expression
`--rsh-raw`	`-r`	Raw output (strips quotes from strings)
`--rsh-verbose`	`-v`	Verbose logging
`--rsh-header`	`-H`	Add a request header (repeatable)
`--rsh-query`	`-q`	Add a query parameter (repeatable)
`--rsh-profile`	`-p`	Use a named auth profile
`--rsh-server`	`-s`	Override the API server base URL
`--rsh-no-cache`		Disable HTTP caching
`--rsh-no-paginate`		Disable automatic pagination
`--rsh-retry`		Retry count (default 2)
`--rsh-timeout`	`-t`	HTTP request timeout
`--rsh-insecure`		Disable TLS verification
`--service-account`		Authenticate with a service account file instead of a browser login
`--project-id`		Use this project for the run, overriding the selected project

Shell Completion

Enable tab completion for your shell:

# Bash
apimetrics completion bash &gt;&gt; ~/.bash_profile

# Zsh
apimetrics completion zsh &gt;&gt; ~/.zshrc

# Fish
apimetrics completion fish &gt; ~/.config/fish/completions/apimetrics.fish

# PowerShell
apimetrics completion powershell &gt;&gt; $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:

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 it
setup-browser-monitor — Create a browser monitor, attach a schedule, and verify it
setup-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 monitoring
apimetrics-weekly-health-review — analyze the previous seven complete days
apimetrics-failure-investigation — root-cause one result or a failure series
apimetrics-incident-triage — blast radius and common cause across monitors
apimetrics-monitoring-estate-audit — coverage, hygiene, stale/duplicate monitors
apimetrics-slo-review — SLO design, attainment, and error-budget risk
apimetrics-config-as-code — safe bulk checkout/diff/push workflow
apimetrics-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, …)

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

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`

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

APImetricsCLI APIContext, Inc.

README

APImetrics CLI

Documentation

Installation

Manual installation

MacOS

Windows

Linux

Getting Started

1. Log in

2. Select a project

3. Run your first command

Service Accounts

Choosing a project

Notes

Passing Input

Output Formats

Global Flags

Shell Completion

AI Agent Integration

Claude Code Skills (operational workflows)

Other agents (OpenAI Codex, Cursor, Gemini CLI, …)

Configuration

Non-production builds

Logout

Issues and Contributing

APImetricsCLI APIContext, Inc.

README

APImetrics CLI

Documentation

Installation

Manual installation

MacOS

Windows

Linux

Getting Started

1. Log in

2. Select a project

3. Run your first command

Service Accounts

Choosing a project

Notes

Passing Input

Output Formats

Global Flags

Shell Completion

AI Agent Integration

Claude Code Skills (operational workflows)

Other agents (OpenAI Codex, Cursor, Gemini CLI, …)

Configuration

Non-production builds

Logout

Issues and Contributing