# CLI

The `twelvebit` CLI sets up a project from the terminal. It has no dependencies and needs Node.js 18 or later. Run it with `npx`, no install needed:

~~~sh
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz <command>
~~~

## init

~~~sh
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz init example.com
~~~

1. Signs you in with a device code. The CLI shows a code and opens `https://twelvebit.app/device`. Check that the code in the browser is the same, then approve. If the codes differ, deny.
2. Finds the site for the domain, or creates it (with the time zone of your computer).
3. Creates a site key named "CLI (your hostname)" and writes `TWELVEBIT_API_KEY` to `.env`, but only when `.gitignore` covers `.env`. Otherwise it prints the key once and tells you where to put it.
4. Writes a starter `analytics.yaml` if there is none.
5. Writes agent guidance into the repo (see [skills](#skills)). `--no-skills` skips this step.
6. Detects the framework from `package.json` and prints the script tag and where it goes.
7. Prints the next prompt for your coding agent.

This is the same workflow as the setup prompt in the dashboard and on the home page: the prompt tells the agent to run `init`, and no key passes through the chat.

Without a domain, `init` uses `project:` in `analytics.yaml`, then `homepage` in `package.json`. You can run `init` again at any time: it keeps what exists and reports the status.

## login, logout, whoami

`login` signs in with a device code, like `init`, without touching the project. `logout` removes the saved session for this server from `~/.twelvebit/config.json` (it does not change `.env`). `whoami` shows the signed-in account and the site of the key in `.env`.

## skills

~~~sh
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz skills
~~~

Writes a twelvebit section into `AGENTS.md` (between `<!-- twelvebit:start -->` and `<!-- twelvebit:end -->`) and the Claude Code skill `.claude/skills/twelvebit/SKILL.md`. They tell coding agents how to track events, run `check` and query the data through MCP. Other text in `AGENTS.md` stays as it is; when the repo has only `CLAUDE.md`, the section goes there. A re-run replaces only the section. The CLI refuses to write through a symbolic link.

## validate

Checks `analytics.yaml` against the full schema without network: keys, names, types, enums, funnels, reserved names and names that would collide in generated code (`a_1` and `a1`). It prints every problem with its path and exits with code 1. `push` and `codegen` run it first.

## push

Uploads `analytics.yaml`. The server validates it and answers with the events that were added, removed and changed.

## pull

Downloads the stored plan into `analytics.yaml`. Use `--force` to replace a local file that differs. The server does not keep comments, so the pulled file has none.

## check

~~~sh
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz check --strict
~~~

Scans the source files (or the paths you give) for `twelvebit("…")` calls, `track.…()` calls and `data-tb-goal` attributes, and compares them with `analytics.yaml`: undeclared events, planned events not used, undeclared props, values outside an enum, missing required props and a stale `analytics.gen.ts`. With a site key it also reads the props the site received in the last 7 days (`prop_drift` in the install check). `--offline` skips that request, so the check needs no network and runs in CI and in broken builds. `--strict` exits with code 1 on drift. See [Tracking plan](/docs/tracking-plan#drift-checks).

## codegen

Writes `analytics.gen.ts` with one typed function per event, then pushes the plan. `--no-push` skips the push.

## status

Prints the install check: first event, recent events, counts, hosts, and which planned events have arrived. `--json` prints the raw response.

## mcp

~~~sh
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz mcp claude        # prints the command for Claude Code
npx -y https://twelvebit.app/cli/twelvebit-cli.tgz mcp claude --run  # runs it
~~~

Agents: `claude`, `codex`, `cursor`. See [MCP](/docs/mcp).

## open

Opens the site's dashboard in the browser.

## Options and environment

| Option | Default | What it does |
|---|---|---|
| `--url` | `TWELVEBIT_URL`, then `https://twelvebit.app` | The twelvebit server |
| `--env` | `.env` | The env file for `TWELVEBIT_API_KEY` |
| `--manifest` | `analytics.yaml` | The tracking plan file |
| `--out` | `analytics.gen.ts` | The codegen output file |

| Variable | Use |
|---|---|
| `TWELVEBIT_API_KEY` | The site key. Read from the environment, then from the env file. |
| `TWELVEBIT_URL` | The twelvebit server, for self-hosting or local development. |

The device sign-in is saved in `~/.twelvebit/config.json` (file mode 600), one entry per server.

---

Source: https://twelvebit.app/docs/cli · All docs: https://twelvebit.app/llms.txt