CLI

tracepath is a command-line client for the TracePath HTTP API: exceptions, logs, endpoints, tasks, traces, and metrics from a terminal. It is designed to be first-class for both humans (with gh-style ergonomics) and LLM agents invoking it via shell tools: JSON output when piped, stable error identifiers and exit codes, and nothing that hangs waiting for input.

Availability

The rest of this page describes the command surface and the conventions it follows, so you can see whether it fits your workflow before it ships. The MCP Server covers the same query surface and is available today over a remote endpoint that needs nothing installed.

Quick start

Once you have a binary on your PATH:

# 1. log in: prints a URL + short code, you approve in the browser
tracepath login --url https://app.tracepath.dev
 
# 2. pick a project (one-time; future calls use it implicitly)
tracepath projects list
tracepath projects use <project-id>
 
# 3. ask questions
tracepath exceptions list --since 24h
tracepath logs query --since 1h --search "OutOfMemory"
tracepath endpoints list --since 1h
tracepath metrics query --name http.server.duration --aggregation avg --since 1h

Pass --url https://app.tracepath.dev on the first login; it is stored in the profile, so later commands do not repeat it. tracepath login with no other flags runs a browser device flow with an auto-refreshing token, so you stay logged in for up to 90 days of inactivity. Password login (--password) and personal access tokens (--token) are also supported; see CLI Authentication for all three modes, and for what to use in CI.

Commands

Run tracepath <command> --help for full per-command flags.

Profiles

Several TracePath accounts coexist via profiles — useful when you belong to more than one organization, or want a separate read-only identity for scripts. Configuration (URL, username) lives in $XDG_CONFIG_HOME/tracepath/config.json so it can be checked in or managed declaratively; credentials and the active project live in $XDG_STATE_HOME/tracepath/state.json.

tracepath login --url https://app.tracepath.dev --profile work
tracepath profiles list
tracepath profiles use work
tracepath --profile personal exceptions list   # one-off override

Output formats

The --output flag picks the format. The default is table on a TTY and json otherwise, so piping always gets machine-readable output.

--fields a,b,c projects list responses to just those keys:

tracepath exceptions list --output json --fields exceptionHash,count,lastSeen

Errors and exit codes

Every error writes a stable JSON envelope to stderr (in json / yaml modes; prose in table mode):

{"error":"token_expired","message":"session expired or invalid","hint":"tracepath login","exit_code":4}

The error field is a stable snake_case identifier that scripts and LLMs can branch on. Exit codes:

Mutations require confirmation

exceptions archive and exceptions unarchive are the only commands that change server state, and they require explicit consent:

• Pass --yes to skip the prompt.
• Or set TRACEPATH_ASSUME_YES=1 in the environment.
• Or run interactively and answer the Continue? [y/N] prompt.

Calling a mutating command from a non-TTY context (script, LLM tool call) without one of the opt-ins fails immediately with usage_error (exit 2); no hung prompts.

MCP server

tracepath mcp serves the whole query/debug surface as an MCP server on stdio for clients like Claude Code, Claude Desktop, and Cursor, reusing the CLI session and current project. See MCP Server for the stdio setup, the zero-install remote server every backend hosts at /mcp, and headless use via TRACEPATH_URL + TRACEPATH_TOKEN.