---
title: "Tracwell CLI - Tracwell docs"
description: "Set up Tracwell and read analytics from the terminal or a coding agent with npx tracwell."
canonical: "https://tracwell.app/docs/cli"
markdown: "https://tracwell.app/docs/cli.md"
---

# 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](https://tracwell.app/docs/agents) . 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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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](https://tracwell.app/docs/analytics) for what each number means.

## Goals and funnels

Terminal

```bash
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

```bash
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

```bash
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](https://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`.
