Traceten CLI

What this lets you do

Run any endpoint of the Traceten API from a shell and get JSON you can pipe straight into jq. Sign in through your browser at a terminal, or with an API key in CI.

npx @traceten/cli stats overview --site ttid_7Rb4TrC1dTbnD8w3s1TS12 --from 2026-08-01 --to 2026-08-26

Before you start

Node.js 22 or newer.
A Traceten account, if you are signing in through the browser. Nothing else to set up.
An API key, for CI or for the commands a browser session cannot run (below). Create one in the dashboard under Settings, API keys, and give it the permissions the commands you want need. Reading numbers needs stats:read; editing goals, funnels, sites and webhooks needs config:write; anything that hands back a secret (creating a site, minting a key or a bot token, registering or rotating a webhook) needs credentials:write.
Your site’s ttid_ snippet key, which traceten sites list returns.

Install

npm install -g @traceten/cli

Or run it without installing:

npx @traceten/cli sites list

Log in

At a terminal, traceten login opens your browser. You approve the CLI in Traceten, pick the organization you want it to act for, and the session is stored on your machine.

traceten login

The listener it opens for the callback is on 127.0.0.1, on a port chosen at the moment you run it, and it closes as soon as the browser comes back. If your browser does not open, the URL is printed: paste it. For CI, and for the commands a browser session cannot run, use an API key instead. The key is read from stdin, never taken as a flag, because anything on the command line lands in your shell history and is visible to ps.

# CI: pipe it in. This never opens a browser.
echo "$TRACETEN_API_KEY" | traceten login

# At a terminal: paste it. The prompt does not echo.
traceten login --key

Either way the credential is written to ~/.config/traceten/config.json with permissions 0600, readable only by you. Nothing ever prints it back, not even a prefix. Check that it worked:

traceten account get

traceten logout removes the stored key and the stored session.

What a browser session cannot do

A browser session carries stats:read and config:write, so it can read your numbers and change goals, funnels, sites and settings. It can never carry credentials:write, so these commands need an API key and say so rather than failing with a bare 403:

Command	Why
`traceten account api-keys-create`	Mints an API key.
`traceten account bot-tokens-create`	Mints a bot token.
`traceten sites create`	Mints a key for the new site.
`traceten webhooks create`	Returns a signing secret.
`traceten webhooks rotate-secret`	Returns a signing secret.

This is deliberate: a sign-in you can revoke must not be able to create a credential you cannot. For the same reason, listing credentials (traceten account api-keys-list, api-keys-revoked and bot-tokens-list) is refused over a browser session as well, and answers 403 saying so.

Where the credential comes from

Three sources, checked in this order:

Order	Source	Set by
1	`TRACETEN_TOKEN`	The environment. Use this in CI.
2	Stored key	`traceten login --key`, at `~/.config/traceten/config.json`.
3	Browser session	`traceten login`, in the same file.

The environment wins, so a CI job never picks up a key a developer happened to leave on the machine. A stored key beats a browser session because it is the more capable of the two; if you have both, traceten logout and log in again to use the session. Set XDG_CONFIG_HOME to move the file, which is how you give a build agent its own. A browser session lasts 24 hours and renews itself in the background, so signing in once is enough. It never opens a browser on its own in the middle of another command. A renewal that fails ends one of two ways:

The grant is gone: you revoked it, or the client was removed. The session is deleted from your machine and the CLI exits 3, asking you to run traceten login again.
Traceten could not be reached: you are offline, or the sign-in service answered 429 or 5xx. Your session is left exactly as it was and the CLI exits 4. Run the same command again when the connection is back; you do not need to log in.

Signing out removes the session from your machine. It does not withdraw the grant, and there is no screen that revokes one: removing the person from your organization is the only thing that ends it. See Safety.

Running commands

The command is the path. GET /v1/stats/overview is traceten stats overview, and GET /v1/breakdowns/ai-sources is traceten breakdowns ai-sources. Every parameter is a flag with the same name, underscores turned into dashes, so site_id is --site-id. --site works everywhere --site-id does.

traceten breakdowns ai-sources --site ttid_7Rb4TrC1dTbnD8w3s1TS12 --from 2026-08-01 --to 2026-08-26

The full list is the command reference, which is generated from the same description of the API that the API itself is served from, so it cannot describe a command that does not exist. traceten help, traceten help <group> and traceten <group> <command> --help all work offline.

Global flags

Flag	What it does
`--json`	Compact single-line JSON, for piping.
`--verbose`	Writes the request line, the response status and the credential source to stderr. Never the key.
`--yes`	Confirms a command that changes or deletes something.
`--api-base <url>`	Point at another host, for local development. Absolute `http://` or `https://` URL.
`--help`	Help for whatever you asked for.
`--version`	The CLI version.

TRACETEN_API_BASE does the same job as --api-base, and the flag wins.

Output

Results go to stdout and everything else to stderr, so a pipe only ever receives data. What reaches stdout depends on where it goes:

stdout is	You get
A terminal	Tables for lists, aligned name and value lines for everything else.
A pipe or a file	The API’s response as indented JSON, exactly as before.
Either, with `--json`	The API’s response as compact, single-line JSON.

# At a terminal: a table.
traceten sites list

# Piped: JSON, ready for jq. Add --json for one line per response.
traceten --json breakdowns ai-sources --site-id ttid_7Rb4TrC1dTbnD8w3s1TS12 | jq '.data.sources[]'

The JSON is the API’s response, unchanged. Nothing is renamed, reordered or summarised, so what the API reference documents is exactly what you get, and a script or CI job that pipes the output sees no difference. The terminal view is for reading. A few commands (sites list, stats overview, stats timeseries and the breakdowns) put their most useful columns first. Every table is trimmed to the width of your terminal, dropping columns from the right, and says how many did not fit. A field whose name ends in _usd_cents is shown as dollars, and one ending in _at as a UTC date and time. Whole numbers get thousands separators, except identifiers such as asn, port, code and names ending in _id. Everything else is printed as the API sent it. Use --json when you need every field. Errors are the same either way: the API’s error body as JSON on stderr, with the exit codes below.

Commands that need `--yes`

Anything that deletes something, issues a credential, or changes how measurement works refuses to run without --yes:

traceten webhooks delete --site ttid_7Rb4TrC1dTbnD8w3s1TS12 --webhook-id 018f… --yes

It is a flag rather than a prompt so that CI can pass it deliberately. The command reference marks every command that needs one: the operations the MCP server puts behind a confirmation, plus the destructive ones the MCP does not expose to an assistant at all, such as deleting a site or issuing a bot token. traceten sites update is the one conditional case: it needs --yes only when you pass --cookie-apex-domain, because moving a site’s cookie scope resets returning visitors.

Exit codes

Code	Meaning
`0`	Success.
`1`	The API answered with an error. Its body is printed to stderr. `traceten ui` exits `1` when the API rejects your credential.
`2`	The invocation was wrong: unknown command or flag, missing value, a command your credential cannot run, or `traceten ui` without a terminal.
`3`	No credential, or a browser session that could not be renewed. Run `traceten login`.
`4`	The request never reached the API, the answer stopped arriving partway through, or your session could not be renewed for a network reason.

A 403 is exit code 1, and the body names the permission you are missing in required_scope.

Browse interactively

traceten ui opens an interactive screen in your terminal. Pick a site, then read its overview and change the date range with a keypress, with no flags to remember.

traceten ui

It signs in with the same credential as every other command, checked in the same order, so run traceten login first. With no credential it prints the usual message and exits 3. It never opens a browser on its own. The first time, it lists your sites. Move with the arrow keys (or j and k) and press Enter. The CLI remembers the site you picked and opens it straight away next time. If you have exactly one site, it opens that one without asking. The overview shows, for the range you picked:

Totals, each against the previous period of the same length (for the last 7 days, the 7 days before them):
- Visitors, sessions and pageviews. A visitor is one browser, not one person.
- AI visitors and AI sessions, each with its share of the total.
- Conversions, with conversions per visitor as a percentage.
- Revenue, net of refunds, in your site’s currency, plus the amount refunded when there was any. If a day in the range has no exchange rate, revenue is shown in USD and says so.
- Bounce rate and active time. Active time counts only the time the tab was in front, so it is not the length of a visit.
A chart of sessions and AI sessions, one bar per day, or one per week (from Monday) for 90 days. Each line is scaled to its own peak, which is printed beside it. A weekly chart names the range, not the weeks, and says when its first or last week is only partly inside the range.
Top AI assistants by sessions, with their conversions and revenue. Assistants below the top five are grouped on one line.
Traffic mix: how the sessions that started in the range split between AI, non-AI and unknown sources.
Top pages from AI traffic, counted by the AI-referred sessions that viewed each page. Other traffic is not counted here.
Top sources of all traffic, by sessions.

A change reads +234 (+23%). Rates change in percentage points (-8.8 pts). A change from zero reads new, and a change involving a figure that cannot be measured reads n/a. Green is the better direction, which for bounce rate and refunds is down. A figure that cannot be measured for the range shows n/a, never 0. The totals are the same figures traceten stats overview returns. Dates are UTC calendar days. At 116 columns or wider the panels sit in two columns. Narrower, they stack. In a short terminal panels are left out from the bottom of one priority order, whichever layout is showing: totals, chart, assistants, traffic mix, pages, sources. A panel is never shown while one above it is left out. A panel left out makes no request, and a line says how many did not fit. Each panel loads on its own, so one that fails shows its own error and the rest carry on.

Keys

Key	What it does
Up and down arrows, or `j` and `k`	Move through a list.
`Enter`	Choose.
`[` and `]`, or left and right arrows	Shorter or longer range: 7, 14, 30 or 90 days.
`r`	Reload.
`s`	Switch site.
`?`	Show every key.
`Esc`	Back to the overview, or close the key list.
`q` or `Ctrl+C`	Quit.

Nothing reloads on its own. Press r for fresh numbers; it reloads only the screen you are looking at. A change of range waits until you stop pressing [ or ], so stepping from 7 to 90 days loads once, not three times. Resizing the terminal never reloads what is already on screen; a panel that comes back after being left out for height loads once when it reappears.

Where it runs

It needs an interactive terminal at least 60 columns wide. Piped or redirected, it refuses with exit code 2 instead of drawing into a file: in a script, use traceten stats overview --json. The overview is laid out for 120 by 40 and still works at 60 columns. The screen opens in your terminal’s alternate buffer, like less, so your scrollback is untouched when you quit. traceten ui accepts --api-base and no other flag. If your session ends while the screen is open (the grant was revoked, or you ran traceten logout in another terminal), it says so. Press q, and the CLI exits 3 so you can log in again. If the API rejects your credential outright, the screen says what to do for the credential you are using, and the CLI exits 1, as any command does on a 401. For a key in TRACETEN_TOKEN that means fixing or unsetting the variable: it is used ahead of anything stored, so logging in again does not replace it.

What it stores

The ttid_ snippet key of the last site you picked, in ~/.config/traceten/config.json under tui.last_site. A snippet key is not a secret: it is the data-site value in your install snippet. traceten logout removes it only when it deletes the whole file, which happens when it removes your last stored credential and the file holds no api_base you set. It stays in two cases: when the file also holds an api_base, and when you sign in only through TRACETEN_TOKEN, where there is no stored credential and logout reports that nothing was stored. To forget it then, delete the tui entry from the file, or the file itself.

What leaves your account

Most commands print counts and aggregates. Two print text written by third party AI engines:

traceten visibility runs prints the verbatim answers the engines gave and the titles of the pages they cited. For Claude and ChatGPT runs it also prints queries: each search the engine ran while answering, with the URLs that search returned.
traceten visibility queries prints those search phrases grouped across runs, with the competitor domain each one brought back most often.

Neither is redacted. Answers discuss a market, so they can name people and companies other than you. A search phrase is generated by the model from your tracked prompt, sometimes reusing its wording; it is not a search any visitor or buyer ran, and it can name a person too. None of this output carries a visitor identifier or describes anybody who visited your site. Two practical consequences:

Answers are never truncated, so a single page of runs can be several megabytes. Redirect to a file rather than a terminal, and use --limit (1 to 50, default 10) to keep it small.
Treat the output of both commands like any other third party content before pasting it into a ticket, a spreadsheet or a shared log. Piping it into a build log makes it as durable as that log.

The other traceten visibility commands return rates, counts, the prompts and brand names you configured, and cited URLs. citations and by-prompt include URLs on other sites that an engine chose to cite, so those are third party addresses, but no command other than the two above prints prose.

Use it in CI

- name: Check yesterday's AI share
  env:
    TRACETEN_TOKEN: ${{ secrets.TRACETEN_TOKEN }}
  run: |
    npx @traceten/cli --json stats overview \
      --site ttid_7Rb4TrC1dTbnD8w3s1TS12 \
      --from "$(date -u -d yesterday +%F)" --to "$(date -u -d yesterday +%F)" \
      | jq -e '.data.ai_session_share'

Give the CI key stats:read only. If it leaks, it cannot send events or change anything.

Troubleshooting

No credential found. Nothing in TRACETEN_TOKEN and nothing stored. Run traceten login. Your Traceten session expired. The grant behind your session is gone: revoked from the dashboard, or removed. Run traceten login again. Could not reach Clerk to renew your session. A network problem, not a credential problem. The session is still on your machine; re-run the command once you are back online. Traceten only signs you in at https://clerk.traceten.com. Something pointed the CLI at an API that names a different sign-in service. Check TRACETEN_API_BASE and any --api-base in play. Nothing was opened and nothing was saved. Pointing the CLI at another instance on purpose needs an explicit --api-base, and it asks before opening the browser. A sign-in server named by TRACETEN_API_BASE or by your config file is refused outright, with a message saying so, because those can be set by something other than you. The browser did not open. The authorization URL is printed alongside the attempt. Paste it into a browser on the same machine, since the callback goes to a listener on that machine’s 127.0.0.1. On a machine with no browser at all, use an API key: echo "$KEY" | traceten login. A command says it needs credentials:write. You are signed in through the browser, and that can never mint a credential. Use an API key for that command; everything else keeps working. 401 on every command. The key is revoked, expired, or was replaced. Keys are shown once, so create a new one rather than looking for the old value. 403 with insufficient_scope. The key is valid but lacks a permission. Permissions cannot be changed after a key is created: make a new key with the right ones, deploy it, then revoke the old one. 404 on a site you own. With a key, a site you cannot reach is a 404 rather than a 403, so that a key cannot be used to discover which site ids exist. Check the key’s site scope, and check you passed the ttid_ snippet key rather than the UUID from the dashboard URL. 422 naming a parameter you did not send. Check for a typo in a flag. The CLI refuses flags a command does not have, but a value that fails the endpoint’s own validation is answered by the API. A command you expected is missing. The CLI covers the endpoints in the OpenAPI spec, which is not quite the whole documented surface. Two read endpoints (conversions and GET /v1/sources) authenticate with a dashboard session only, so there is no command for them. Two more are in the docs but not the spec, so they have no command either: PATCH /v1/goals/reorder and the data deletion and access endpoints. The deletion endpoints take an API key, so call them with curl, not the CLI.

Command reference: every command and its flags.
API keys and permissions: what each permission grants.
MCP server: the same surface, as tools for Claude, ChatGPT, Codex, VS Code, Claude Code and Cursor.

Command line

What this lets you do

Before you start

Install

Log in

What a browser session cannot do

Where the credential comes from

Running commands

Global flags

Output

Commands that need `--yes`

Exit codes

Browse interactively

Keys

Where it runs

What it stores

What leaves your account

Use it in CI

Troubleshooting

Next

​What this lets you do

​Before you start

​Install

​Log in

​What a browser session cannot do

​Where the credential comes from

​Running commands

​Global flags

​Output

​Commands that need --yes

​Exit codes

​Browse interactively

​Keys

​Where it runs

​What it stores

​What leaves your account

​Use it in CI

​Troubleshooting

​Next

What this lets you do

Before you start

Install

Log in

What a browser session cannot do

Where the credential comes from

Running commands

Global flags

Output

Commands that need `--yes`

Exit codes

Browse interactively

Keys

Where it runs

What it stores

What leaves your account

Use it in CI

Troubleshooting

Next