Tracwell CLI

Set up Tracwell and read your analytics from the terminal or a coding agent with the tracwell command.

The CLI uses the same tools and permissions as MCP. Use it in a terminal or with a local coding agent; use MCP for assistants without a shell, such as Claude on the web or ChatGPT.

Quick start

Run this in your project. It signs you in, finds or adds the website, saves it as the default, prints the install snippet, and installs the agent skill in the repo. Needs Node.js 20 or newer.

Terminal
npx tracwell init --url https://acme.com

Add the snippet to your site, load a page, then run npx tracwell verify. The CLI ships in the tracwell npm package, so npx tracwell needs no separate install.

Sign in

Terminal
npx tracwell login

This opens the browser. Sign in to Tracwell, choose websites, and choose what the CLI may do: read analytics (always), Manage goals and funnels, and Add websites. Only workspace owners can approve. The sign-in renews itself; npx tracwell logout revokes it. Manage it in Settings → MCP.

For CI and shells without a browser, create an MCP key in Settings → MCP and use it instead. Use a tw_ro_ (read) or tw_rw_ (read and manage goals and funnels) key, not your server key (tw_sk_), project key (tw_live_) or a notes-only key (tw_nw_).

Terminal
export TRACWELL_API_KEY=tw_ro_...
npx tracwell overview
Keys cannot add websites; use a browser sign-in with Add websites for that. Keep keys out of source control.

Choose a website

Terminal
npx tracwell sites
npx tracwell use <website-id>
npx tracwell sites add "Acme" https://acme.com

use saves a default website; --site <id> overrides it for one command. With only one website, the CLI uses it automatically. With several, it lists them and asks you to choose.

Install and verify

Terminal
npx tracwell snippet
npx tracwell verify

snippet prints the script tag and the npm setup for the website. verify returns waiting until the first event arrives, then receiving.

Read reports

Terminal
npx tracwell overview
npx tracwell acquisition --days 30
npx tracwell revenue --from 2026-11-01 --to 2026-11-30
npx tracwell events
npx tracwell journeys

Reports cover the last 7 days in UTC by default. Use --days, or --from and --to as YYYY-MM-DD. Other commands: goals, goal --goal-id, funnels, funnel --funnel-id and notes. See Reports and metrics for what each number means.

Goals and funnels

Terminal
npx tracwell goals add "Signed up" --event signup_completed --category signup
npx tracwell goals add "Viewed pricing" --page /pricing
npx tracwell funnels add "Checkout" --steps /pricing,event:checkout_started --window-hours 48
npx tracwell funnels add "Checkout" --steps /pricing,event:checkout_started --dry-run

Needs Manage goals and funnels. A goal matches one page (--page) or event (--event). Funnel steps are a comma list: /path is a page and event:name is an event. Add --dry-run to see the request without saving anything.

Any tool

Terminal
npx tracwell search funnel
npx tracwell help call analytics_funnel_preview
npx tracwell call analytics_funnel_preview --days 30 --steps '[{"type":"pageview","path":"/"},{"type":"pageview","path":"/pricing"}]'

tools lists every tool your login can use and search finds one by keyword. call runs any of them, with arguments as flags in kebab or camel case, or as --json '{...}'. help reads each tool's arguments live from Tracwell.

Agent skill

Terminal
npx tracwell skill install
npx tracwell agents-md install

skill install writes the Tracwell skill to .agents/skills/tracwell/SKILL.md, and to .claude/skills when the repo has a .claude folder. agents-md install adds a short Tracwell section to AGENTS.md. The skill is also at tracwell.app/skill.md.

Reference

Environment
TRACWELL_API_KEY
Use an MCP key (tw_ro_ or tw_rw_) instead of the saved sign-in. Same as --key.
TRACWELL_URL
Another Tracwell address, such as a local development server. Default https://tracwell.app.
TRACWELL_CONFIG_DIR
Where the sign-in and default website are saved. Default ~/.config/tracwell.
Output and exit codes
Output
JSON on stdout. --compact prints one line. Notes go to stderr.
0
Success
1
The request failed
2
Bad input, such as a missing argument
3
Sign-in needed. Run npx tracwell login.