Skip to content

cli-interface.md

Latest commit

 

History

History
160 lines (121 loc) · 4.61 KB

cli-interface.md

File metadata and controls

160 lines (121 loc) · 4.61 KB
Raw

CLI interface

trce has human-facing commands and a small integration surface for harness hooks. Recording is always local; only share and unshare perform network requests.

Install harness hooks

trce init \
  --harness claude-code|codex-cli \
  --scope project|global \
  [--config-dir <path>] \
  (--dry-run | --yes)

--dry-run prints every planned write. --yes applies the plan and creates or preserves the device token in ~/.trce/config.toml without contacting a server or printing the token.

Project installs write .claude/ or .codex/ in the current directory. Global installs use the matching directory in the user's home. --config-dir supports alternate harness homes.

Claude Code

trce init --harness claude-code --scope project --yes

The install merges lifecycle hooks and a statusline into settings.json, then adds the trce-share skill. Start a new session after installing.

/trce-share
/trce-share live

Codex CLI

trce init --harness codex-cli --scope project --yes

The install merges lifecycle hooks into hooks.json. Codex may ask you to trust the project and review hooks with /hooks. Start a new session after approval. To share, run trce share --latest or ask Codex to run it.

Share

trce share \
  [--latest | --native-session-id <id> | --trace <path>] \
  [--harness claude-code|codex-cli] \
  [--live | --local] \
  [--server <url>] \
  [--token <token>] \
  [--json]

Defaults and selectors:

  • With no selector, share finds the latest supported session for the current repository.
  • --native-session-id selects a recorded harness session.
  • --trace publishes an existing normalized trace.
  • --harness limits latest-session lookup to one harness.

Modes:

  • The default performs a one-shot upload.
  • --live backfills the session, starts the uploader, and publishes new events until the session ends. It requires a recorded session and cannot be combined with --trace or --local.
  • --local writes redacted artifacts without uploading.
  • --json produces machine-readable output for scripts and agents.

Before upload, the CLI writes the redacted trace, redaction report, and local HTML preview under ~/.trce/shares/<native-session-id>/. Uploads use the public HTTP protocol, and the server can be overridden by flag or ~/.trce/config.toml.

Unshare

trce unshare <share-id-or-url> [--server <url>] [--token <token>] [--json]

unshare deletes the hosted copy owned by the device token. Local spools, native transcripts, and generated artifacts stay on disk.

Import and local rendering

trce import claude --transcript <path> [--spool <path>] --out <path>
trce import codex --rollout <path> --out <path>
trce normalize --spool <path> --out <path>
trce render --trace <path> --out <path>
trce render --spool <path> --out <path>

import adapts native transcript or rollout JSONL into the normalized schema. normalize converts a hook spool. render creates a local HTML view.

Statusline

trce statusline [--native-session-id <id>] [--json]

The statusline reads local session state and reports recording, live, or shared status. The native session ID can be supplied by integrations that cannot infer it from the harness environment.

Hook contract

trce spool \
  --harness claude-code|codex-cli \
  --event <event-name> \
  [--native-session-id <id>]

The hook payload is read from stdin and appended as one JSONL envelope under ~/.trce/spool/. This command is synchronous on every tool call and therefore:

  • performs no network requests
  • performs no normalization, redaction, or upload
  • writes no stdout unless --json is passed
  • appends and exits

--spool-dir is available for tests and integrations. --session remains an alias for --native-session-id for compatibility.

Live uploader

trce daemon \
  --native-session-id <id> \
  [--server <url>] \
  [--poll-ms 1000] \
  [--once] \
  [--json]

share --live starts the daemon after its initial backfill. The daemon imports the current native session, uploads unseen source IDs, and advances local state only after a complete delta succeeds. --once performs a single pass for diagnostics and integration tests.

Upload bounds

  • Each event is limited to 64 KiB in shared payloads and retains truncation metadata when reduced.
  • A protocol request is limited to 5,000 events and 10 MiB.
  • The CLI targets batches of at most 100 events and 1 MiB.
  • Retries are idempotent by normalized session ID and event source ID.

These limits affect shared artifacts only. Raw local recordings are not modified.