CLI reference

Every `thirdeye` command, flag, and filter.

Every thirdeye subcommand. The thirdeye and thrdi binaries are aliases — pick whichever you prefer. Session IDs accept any unique prefix throughout.

Commands at a glance

Common flags available on most read commands: --json (parseable JSONL), --tree (human-readable), --platform, --cwd, --tag, --since, --until.

Interactive setup

thirdeye setup

thirdeye setup

Walks through tracing setup for Claude Code, Codex, Cursor, and GitHub Copilot CLI; installation of bundled agent skills; and optional live export to Pydantic Logfire. Choosing Logfire signs you in through the browser and mints the write token for you — there is no key to paste.

Tracing

thirdeye add

thirdeye add --claude
thirdeye add --codex
thirdeye add --cursor
thirdeye add --copilot
thirdeye add --list

Registers a hook so the next session on that platform is captured. Idempotent. --list prints the currently supported platforms and warns about stale hooks from removed platforms. Cursor installs hooks for both its IDE and CLI in ~/.cursor/hooks.json. For Codex, --force replaces an existing notify program. Copilot writes user-level hooks at $COPILOT_HOME/hooks/thirdeye.json (default ~/.copilot/hooks/thirdeye.json); see thirdeye copilot below for what it reads and how to opt already-completed history into export. On Windows, if the resolved binary path contains a space, the bare binary name is written into the hook config instead of the absolute path, relying on PATH resolution.

thirdeye remove

thirdeye remove --<platform>

Reverses the corresponding add. Captured data on disk is left in place.

thirdeye copilot

thirdeye copilot status [--source-home PATH]
thirdeye copilot sync [--source-home PATH] [--export]
thirdeye copilot reconcile [--export] [--session-id ID --rebuild]
thirdeye copilot watch [--source-home PATH] [--interval SECONDS]

Copilot-specific archive commands. status and sync report and import from --source-home (falls back to COPILOT_HOME, then ~/.copilot); reconcile rebuilds local V2 projections from the retained archive without touching the source. --export on sync/reconcile opts already-completed retained history into export; without it, projections refresh locally only. --session-id ... --rebuild rebuilds one archive's derived indexes and preserves the raw archive and delivery ledger. watch is an explicit foreground poller, not started by add or setup.

Pydantic Logfire

See Pydantic Logfire for trace shape and behavior.

thirdeye logfire enable

thirdeye logfire enable
thirdeye logfire enable --auth

Signs in to Logfire in the browser, mints a project write token, persists it, and enables live export. When a token is already saved, the command offers to reuse it instead of signing in again. When the account has more than one writable project you pick which to use; when it lists none, the command offers to create or attach one. --auth logs out first, so a different account or an expired login can re-authenticate. The token is not accepted as a command-line option. Logfire support ships with every installation — no extra to install.

thirdeye logfire status

thirdeye logfire status

Shows whether the package is installed and whether export, token, and active state are configured.

thirdeye logfire disable

thirdeye logfire disable

Stops export while retaining the saved key.

Reading history

thirdeye list

thirdeye list [--platform NAME] [--cwd PATH] [--tag NAME]
              [--since DATE] [--until DATE] [--json | --tree]

List sessions, newest first.

thirdeye events

thirdeye events <id> [--json | --tree] [--no-findings] [--eval NAME]
                     [--tag NAME] [--since DATE] [--until DATE]

All events for a session. Eval findings annotate the timeline by default; suppress with --no-findings or filter with --eval.

thirdeye event

thirdeye event <id> <seq> [--json]

One event, fully expanded.

thirdeye tail

thirdeye tail <id> [-n N] [--json]

Most recent N events for a session (default N follows tool's standard).

thirdeye search

thirdeye search <query> [--platform NAME] [--cwd PATH] [--tag NAME]
                        [--since DATE] [--until DATE] [--json | --tree]

Substring scan across every captured event.

thirdeye stats

thirdeye stats [--platform NAME] [--since DATE] [--until DATE] [--json]

Aggregate counts and totals across sessions.

Tags

thirdeye tag

thirdeye tag <id> <seq> --add tag1,tag2
thirdeye tag <id> <seq> --remove tag1
thirdeye tag <id> --list

Add or remove comma-separated tags on a specific event. --list shows every tagged event in a session.

thirdeye tags

thirdeye tags [--json]

Global inventory of every tag across all sessions, with counts.

Token usage

thirdeye usage

thirdeye usage [--platform NAME] [--harness NAME] [--model SUBSTR]
               [--since DATE] [--until DATE]
               [--top N] [--sort total|input|output|ts] [--json]

Global rollup, sessions ordered by total token spend.

thirdeye usage <id>

thirdeye usage <id> [--json]

Per-turn detail for one session, anchored to event seq.

thirdeye usage reindex

thirdeye usage reindex

Rebuild <thirdeye_home>/usage.db from every usage.jsonl under traces/. Safe to run any time.

thirdeye usage errors

thirdeye usage errors

Tail the capture audit log written when usage parsing fails.

Evaluations

thirdeye eval def list

thirdeye eval def list

List available rubrics (shipped + user-created).

thirdeye eval def show

thirdeye eval def show <name>

Print the directive text for a rubric.

thirdeye eval def create

thirdeye eval def create <name> --directive "<text>"
thirdeye eval def create <name> --from <path>

Create a custom rubric.

thirdeye eval def edit

thirdeye eval def edit <name>

Open a rubric in $EDITOR.

thirdeye eval def rm

thirdeye eval def rm <name>

Delete a rubric.

thirdeye eval run

thirdeye eval run <id> --agent claude|codex|gemini
                       [--using NAME] [--background]

Dispatch an evaluator agent against a session. --using selects the rubric (default default). --background detaches. Exit code is always 0; the verdict is in the result.

thirdeye eval show

thirdeye eval show <id> [--using NAME] [--json]

Latest eval result for a session.

thirdeye eval list

thirdeye eval list [--platform NAME] [--cwd PATH]
                   [--since DATE] [--until DATE]
                   [--verdict pass|warn|fail] [--using NAME] [--json]

History of eval runs across sessions.

thirdeye eval status

thirdeye eval status

Show background eval jobs and their state.

Browser UI

See Browser UI for the full reference.

thirdeye ui

thirdeye ui [--port N] [--host ADDR] [--no-browser]
thirdeye serve [--port N] [--host ADDR] [--no-browser]

Launch the local browser UI. Defaults to http://127.0.0.1:8765 and auto-opens your default browser. thirdeye serve is a full alias of thirdeye ui — same host, port, and browser flags. The browser UI ships with every installation — no extra to install.

thirdeye views

thirdeye views list --page sessions
thirdeye views save <name> --page sessions
thirdeye views delete <name> --page sessions

Manage saved filter views from the CLI. Views are persisted at <thirdeye_home>/views/<page>.json and shared with the UI sidebar.

Skills

See Agent skills for usage patterns.

thirdeye skills list

thirdeye skills list

Print bundled skill names.

thirdeye skills add

thirdeye skills add [-p PATH | --claude | --codex]
                    [--only NAME] [--force]

Install bundled skills as symlinks, one directory per skill. With no target flag the destination is .agents/skills/. On Windows without Developer Mode or admin rights, where a symlink can't be created, thirdeye copies the directory instead — rerun with --force after upgrading thirdeye to refresh copied skills.

--claude and --codex may be combined to install into both in one run. Use -p ~/.claude/skills to install user-level so the skills resolve in every repo.

Global options