Axiom CLI for coding agents

A coding agent investigating a failing change can use Axiom CLI in the terminal to query production logs from an Axiom account. Observability data records what a service did, such as log events and traces. The CLI also ingests and streams data, so agents should use query commands when they only need to inspect existing records.

Axiom Processing Language (APL) is Axiom’s query language for selecting and filtering data. The example below uses APL to retrieve a few records from a dataset, Axiom’s named collection of observability data. It shows where local setup ends and the read-only request to Axiom begins.

Install and authenticate

Axiom documents four installation methods. See installation through Homebrew, Go, source builds, and Docker. On macOS, install the CLI with Homebrew:

brew install axiomhq/tap/axiom

Check the official CLI documentation for other installation methods and current command options. The CLI repository also documents its configuration and supported commands.

The CLI needs an Axiom personal access token to access an account. Axiom recommends tokens that begin with xapt-. Set the token in the shell environment that will run the CLI:

export AXIOM_TOKEN="<personal-access-token>"
export AXIOM_ORG_ID="<organization-id>"

Both values in angle brackets are placeholders. Replace them with your Axiom organization ID and a token that can access the relevant data. Store the token in a secret manager or another protected environment-variable source. Do not paste it into an agent prompt or commit it to a repository. The CLI also supports interactive authentication and a home-directory .axiom.toml configuration file. Command-line flags take precedence over environment variables, which take precedence over the configuration file, as described in the CLI repository.

Query a dataset

After a code change, a coding agent can check recent service logs for errors. First, confirm the CLI command syntax available in the installed version:

axiom query --help

Then query a dataset. Replace <dataset-name> with the exact dataset name in the Axiom organization:

axiom query "['<dataset-name>'] | limit 5"

The query reads from Axiom, selects the named dataset, and returns up to five records in the terminal without ingesting or deleting any records. Replace the placeholder with the exact dataset name. The configured Axiom organization must contain that dataset and grant access to it.

Check the CLI’s help output for available time-range and output options before adding flags. Avoid assuming a JSON output flag or a particular format: use only options shown by the installed CLI’s axiom query --help. A coding agent can then summarize relevant records or narrow the query based on fields it sees in the returned data.

A realistic prompt for an agent is:

Query the api-logs dataset for up to five recent records. Report any error messages and their timestamps. Do not ingest, delete, or annotate data.

Replace api-logs with the name of a dataset the configured account can access. Keep the request narrow, since log records can contain sensitive information.

Keep inspection separate from writes

Axiom CLI also supports ingesting JSON, newline-delimited JSON (NDJSON), and CSV data, as well as streaming data. Those commands send data to Axiom and change what the organization stores. An agent investigating an incident should use query for inspection and treat ingest as a separate action that requires an explicit reason and review. The CLI command reference lists the available command groups and their options.

The CLI repository includes a Claude Code plugin with APL skills that explore datasets and find traces. The skills also detect anomalies. Claude Code users can install it with:

claude plugin marketplace add axiomhq/cli
claude plugin install axiom-cli@axiom-cli

The plugin provides /explore-dataset, /find-traces, and /detect-anomalies. It is specific to Claude Code; the repository does not establish that other coding agents can use the plugin directly. Agents with shell access can invoke the CLI when their environment has it installed. The environment also needs credentials and access to the required Axiom data. See the plugin instructions for details.