CLI

tracehatch init, doctor and uninstall, their flags, and what each one changes.

On this page

Three commands. init connects an application, doctor re-checks it, and uninstall reverses what init wrote. Nothing is installed globally — the dashboard's command runs the right version for your installation.

Runtime: Node.js 20+ (your app can stay on 18)
Global install: Not needed
Writes a key: Only to your private environment file
Key as an argument: Never accepted

#init

Terminal

npx --yes @tracehatch/cli@0.3.0 init

Run it in the package that actually makes your model calls. It finds supported packages under the usual apps, packages, services, server and backend folders; if more than one matches it asks, and --yes does not guess.

Flag	Effect
`--cwd <path>`	Choose the application directly instead of being asked.
`--dry-run`	Preview only. Never authenticates, creates a key, installs or writes.
`--yes`	Skip the confirmation prompts. The file preview is still shown unless set.
`--capture-bodies`	Record prompts and outputs.
`--no-capture-bodies`	Do not record them. This is the default.
`--project <id>`	Preselect the project in the browser. Grants no access.
`--environment <id>`	Preselect the environment in the browser. Grants no access.
`--no-browser`	Print the authorization URL instead of opening it.
`--wait <seconds>`	Wait for an application model call. 0–600, default 90; `0` skips waiting.
`--api-url <url>`	API origin for a local or self-hosted installation.
`--web-url <url>`	Dashboard origin for a local or self-hosted installation.
`--help`, `--version`	Show the built-in help or the CLI version.

#What it changes

The integration is one line, because the SDK configures itself from TRACEHATCH_* settings and captures at the fetch boundary. No bootstrap file is generated, and the privacy choice is an environment setting rather than a code branch.

Any Node server — adds --import @tracehatch/sdk/auto to the existing start/dev script, keeping its entry file and arguments. Scripts behind inline environment assignments, cross-env, nodemon, tsx, ts-node and ts-node-dev are recognised.
Next.js — root or src instrumentation beside app/pages, guarded to the Node.js runtime. An existing ordinary register() at the start of the file is preserved and extended.
NestJS — import "@tracehatch/sdk/auto" as the first line of src/main.ts, for standard compiled entrypoints.

Anything it will not edit safely — a custom launcher, a nonstandard NestJS entry, an ambiguous instrumentation file, a script already using --require — is reported as an exact instruction to apply by hand. The rest of setup still completes; one file it will not guess at does not abandon the run.

#Safety

Keys stay in .env.local or .env. The wizard adds Git ignore rules, refuses tracked secret files and symbolic-link targets, and never accepts a key as a command-line argument.
Browser authorization creates the ingest key; the CLI exchanges a one-time device secret for it. The browser sees a confirmation code, never the key.
The preview shows complete code changes and hides all environment values, including existing multiline secrets. The lockfile change from installation is identified in the preview.
Existing keys and configuration are preserved. A conflicting value stops setup with instructions rather than overwriting.
Rerunning is safe: no duplicated imports or flags, no overwritten custom files, no replacing a file you modified after the preview.
A declined preview leaves your files unchanged. A key already approved in the browser can be revoked in API keys settings.

#doctor

Terminal

npx --yes @tracehatch/cli@0.3.0 doctor

VariationsTerminal

tracehatch doctor --wait 60   # wait up to 60s for a real application call
tracehatch doctor --fresh     # reset the baseline with a new diagnostic

Doctor resolves the SDK from the selected application's installed dependencies, loads its environment and sends a diagnostic without calling an AI provider. It verifies that exact trace id using the receipt scoped to the ingest key — an accepted HTTP batch alone does not count as success.

Exit code	Meaning
`0`	Connection verified. Application recording may still be waiting.
`2`	Connection works, but no application call arrived within `--wait`.
`1`	An error.

The next run reuses the receipt baseline, so it recognises a call you made between runs. A local .tracehatch/setup.json keeps the diagnostic id and nonsecret project metadata; it contains no key.

init already waits up to 90 seconds for that first real model call and exits non-zero if none arrives, so its output is the evidence that setup worked.

#uninstall

Terminal

npx --yes @tracehatch/cli@0.3.0 uninstall

Previews the diff first, then reverses exactly what init added: the preload flag, the auto import, the instrumentation block and Tracehatch's own environment names. A file you edited by hand is reported rather than rewritten.

The SDK dependency and the project key are left alone — remove and revoke them deliberately.

#Continuous integration

Set TRACEHATCH_API_KEY in the environment and init skips browser approval entirely, configuring the application with that existing key.

Unattended — use the same init command your dashboard showsTerminal

TRACEHATCH_API_KEY=… <your init command> --yes --cwd apps/api --wait 0

#Local or self-hosted Tracehatch

Point the CLI at your own installationTerminal

tracehatch init --api-url http://localhost:4000 --web-url http://localhost:3000

Hosted customers use the dashboard's own command, which already carries its origins. HTTPS is required except for loopback development addresses. The browser sign-in session uses the chosen web origin; telemetry and the device exchange use the API origin, and credentials are not forwarded across API redirects.

A self-hosted dashboard serves a matching CLI archive, so the CLI always matches the API it was downloaded beside.

#Versions

The canonical dashboard installs the exact npm version; a self-hosted dashboard installs its own archive. Edge, Python and browser-only applications use the gateway or the log endpoint instead.