TraceIQTraceIQDocs

CLI

traceiq-cli sets up TraceIQ in your app and lets you work with your projects from the terminal: switch projects, write env files, and read logs, events and errors. Run it with npx, or install it globally to get the shorter traceiq command.

bash
npx traceiq-cli            # setup wizard
npx traceiq-cli help       # every command

npm install -g traceiq-cli
traceiq help logs          # flags for one command

Setup wizard

With no command, the CLI detects your framework (Next.js, Vite + React, Node), installs the SDK, writes your project ID and write key to the env file, and waits until the first real event reaches TraceIQ.

  • traceiq — Install and verify. Flags: --project-id, --write-key, --api-url, --dry-run, --skip-verify.
  • traceiq audit — Check the instrumentation already in this project (alias: doctor).
  • traceiq verify — Wait for a live event using the credentials in your .env file.

Log in

Every other command uses a personal access token. Create one in Settings under Personal access tokens with projects:read, analytics:read and errors:read, then log in. The token is saved to ~/.traceiq/config.json, readable only by you.

bash
traceiq login                       # prompts for the token (input hidden)
traceiq login --token tiq_pat_...   # non-interactive
traceiq login --api-url https://api.traceiq.run   # a self-hosted or local API
traceiq whoami
traceiq logout

In CI, set TRACEIQ_TOKEN instead of logging in. logout only forgets the token locally; revoke it in Settings to disable it.

Projects and env files

bash
traceiq projects list
traceiq projects use              # pick from a list
traceiq projects use my-app       # by id, slug or name

traceiq env pull                  # writes .env.local (or your existing .env file)
traceiq env pull --print          # print instead of writing
traceiq env pull --write-key trq_...

Logs, events, errors, status and env pull use the active project; pass --project <id> to use another one for a single run. env pull writes TRACEIQ_PROJECT_ID, TRACEIQ_API_URL and TRACEIQ_WRITE_KEY with the prefix your framework needs (NEXT_PUBLIC_, VITE_, or none for Node) and keeps the rest of the file. Write keys are stored hashed, so the CLI keeps the key already in your env file for that project, or uses --write-key.

Logs, events and errors

bash
traceiq logs                              # last hour, oldest first
traceiq logs --level error --since 24h
traceiq logs -s checkout --follow         # stream new logs until Ctrl+C
traceiq logs --trace 4bf92f35... --json   # one JSON object per line

traceiq events --follow
traceiq events --name signup_completed -n 50

traceiq errors --days 30
-l, --levelalldebug, info, warn or error.
-s, --search—Matches message, route, service, trace or request ID, and user ID.
--sourceallapi, sdk, ai, webhook, job, …
--statusallsuccess, warning or error (comma-separated for several).
--trace—Only logs for one trace.
--since1hA window such as 15m, 2h, 7d, or an ISO date.
-n, --limit50How many to show first (max 200; events max 100).
-f, --followoffKeep polling for new entries. --interval sets the seconds between polls (default 2).
--jsonoffNewline-delimited JSON, for piping into jq or a file.

Status and the dashboard

bash
traceiq status             # API health, last event, last log, event counts
traceiq open logs          # also: events, errors, users, web, api, flags, replays, alerts, settings
traceiq open logs --print  # print the URL instead of opening a browser

status exits with code 1 when the API can't be reached, so it also works as a CI check.

Configuration

--api-url / TRACEIQ_API_URL'https://api.traceiq.run'API to talk to. login --api-url saves it.
--token / TRACEIQ_TOKENsaved by loginPersonal access token (tiq_pat_...).
-p, --projectsaved by projects useProject for this run.
--dashboard-url / TRACEIQ_DASHBOARD_URLfrom the API URLWhere open sends you. A localhost API maps to http://localhost:3000.
TRACEIQ_CONFIG_DIR~/.traceiqWhere the token and active project are stored.

Flags win over environment variables, which win over the saved config. Creating, renaming or deleting projects and showing or rotating write keys need a signed-in dashboard session, so they stay in Settings; the CLI points you there if you try them.

Previous← Server-side ingestionNextMCP server →