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:

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

init#

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). --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#

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#

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.

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#

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.

open#

Opens the site's dashboard in the browser.

Options and environment#

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