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.
npx tracwell init --url https://acme.comAdd 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
npx tracwell loginThis 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_).
export TRACWELL_API_KEY=tw_ro_...
npx tracwell overviewChoose a website
npx tracwell sites
npx tracwell use <website-id>
npx tracwell sites add "Acme" https://acme.comuse 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
npx tracwell snippet
npx tracwell verifysnippet prints the script tag and the npm setup for the website. verify returns waiting until the first event arrives, then receiving.
Read reports
npx tracwell overview
npx tracwell acquisition --days 30
npx tracwell revenue --from 2026-11-01 --to 2026-11-30
npx tracwell events
npx tracwell journeysReports 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
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-runNeeds 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
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
npx tracwell skill install
npx tracwell agents-md installskill 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
- TRACWELL_API_KEY
- Use an MCP key (
tw_ro_ortw_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
- JSON on stdout.
--compactprints 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.