Basic recording

premier record -- <command> [args...]

Examples:

premier record -- npm test
premier record -- python agent.py
premier record --open --name "Nightly agent" -- codex exec "repair billing"

Flags

Flag Meaning
-o, --output <path> .atrace directory (default under .premier/traces/)
--name <label> Human-readable run name in list + viewer
--tenant <id> Immutable tenant owner (default local)
--adapter <choice> Auto-detect or explicitly normalize provider JSONL
--open Open the embedded viewer focused on this run when finished
--bind <addr> Viewer bind when using --open (default 127.0.0.1:4317)
--viewer-dir <path> Optional disk viewer for UI development

What is recorded without emitters

  • Session start (cwd, command, collector URL)
  • Process stdout / stderr (UTF-8 safe)
  • Process exit code

Collector security

While the command runs, Premier starts a loopback-only HTTP collector:

  • Requires Authorization: Bearer $PREMIER_COLLECTOR_TOKEN
  • Limits body size
  • Never writes the token into the trace

Child processes inherit PREMIER_* env vars so SDKs can emit without configuration files.

Native provider evidence

When a recognized Claude, Codex, Grok, Gemini, or OpenCode command already requests structured output, --adapter auto normalizes its JSONL stream into typed events. See Provider adapters for exact flags and fidelity boundaries.

After the run

trace <id> → .premier/traces/<id>.atrace
next: premier open .premier/traces/<id>.atrace

Exit status of premier record matches the child when it fails (so CI still fails).