​
Commands

The CLI command name is selltraces.

​
Global options

--json may appear before or after a subcommand. For example, selltraces --json status and selltraces status --json both print the same machine-readable status object to stdout. Usage errors also become one JSON object on stdout when --json is present.

​
Root command

Smart entrypoint. On a first run with no saved local policy, this starts guided setup. On a configured machine, it verifies saved credentials and prints cached local delta before any scan or upload planning. In an interactive terminal it then refreshes into the same review/upload planner as selltraces upload. In non-interactive configured runs, it stops after cached delta; if credentials are missing or stale, it prints status and the relogin command instead of waiting on device login.

​
selltraces setup

Compatibility command for the complete setup/reconfiguration flow:
  1. Authenticate the machine.
  2. Discover supported source locations.
  3. Count discovered source records before parsing transcript content.
  4. Pick which sources may be inspected locally (Tab toggles, Up/Down moves, Enter saves).
  5. Save the local source policy.
  6. Index selected sources locally and review the project/repository allowlist.
  7. Preview local redaction and upload results.
  8. Require the user to type upload before historical traces are queued.
Source selection and indexing are local-only. No transcript content leaves the computer until the project allowlist, upload preview, and typed upload checkpoint have all completed. When setup is rerun on a configured machine, saved approved sources, approved projects, private projects, blocked terms, and upload consent are preserved by default. Newly discovered projects remain pending unless explicitly approved.

​
Non-interactive flags (agents & CI)

Every interactive step can be answered up front so the flow never blocks on a prompt: In --json mode the device-login URL and code are written to stderr so stdout stays a single JSON object. When the terminal is not a TTY and no flags are given, setup defaults to a safe preview with no upload.

​
selltraces onboard

Compatibility command that runs the same flow as selltraces setup.

​
selltraces login

Authenticates this machine. The device login flow prints a verification URL, user code, complete URL, expiration time, and polling status. Use --force to re-link the machine even when same-origin saved credentials are present. In --json mode, the verification URL and code are written to stderr so stdout stays reserved for the final linked/reused JSON object.

​
selltraces logout

Removes this machine’s saved credentials. Saved policy and repeat-sync state remain on disk.

​
selltraces status

Shows:
  • authenticated user and API base
  • detected source locations
  • approved sources
  • approved/private project counts
  • blocked-term count
  • local upload trace count
  • pending-upload count and retained retry-cache size
  • local lifetime queued estimate
Use --json for scripts and agents.

​
selltraces upload

The canonical returning command. It reviews and uploads approved traces once. --dry-run and --plan print the upload plan without uploading. A real upload checks saved credentials before transcript discovery; use selltraces login if the machine is not linked. First-run and non-returning interactive upload reviews surface the saved policy, expand only when new sources/projects need review, then show an upload plan and typed upload checkpoint. Returning interactive uploads instead show a “new value found” delta screen and use the explicit Upload approved delta menu action. New projects/repos and new source kinds stay pending review until approved. If exactly one pending project is waiting, project review asks a plain two-choice question: keep it private for now or include it in upload preview. Multi-project review uses a checkbox list with Tab to toggle the highlighted item, Up/Down to move, and Enter to save. Choosing Show skipped traces opens the skipped detail view and keeps it visible behind an explicit follow-up prompt instead of immediately redrawing the main menu. After a successful upload, the CLI prints a human dashboard job-status link at /dashboard/ingest/jobs/{jobId}, the trace ledger at /dashboard/traces, and the raw API status URL for scripts. Trace rows appear in the ledger after the ingest worker finishes the queued job. Non-interactive agents can perform the same policy changes as a human by making them explicit:
If a saved project policy already exists and no policy changes are needed, non-interactive upload still needs explicit confirmation:
On a first-run machine with no saved project policy, upload requires --approve-project / --private-project or an earlier setup policy before upload.

​
selltraces policy

Shows and edits local upload policy: approved sources, approved projects, projects kept private, and blocked terms. The command scans local approved sources for project inventory but never uploads trace content. Interactive human output is a compact editor:
  • A summary shows the policy file, scan scope, approved/detected sources, saved/current project counts, pending current projects, and blocked-term count.
  • Current projects appear in a scroll-limited checkbox list. Checked projects may upload after preview; unchecked projects remain private on this machine. The submitted answer echoes short project labels only; counts, status, and paths stay in hints and the post-submit summary.
  • Saved projects not seen in the current scan are preserved but not shown in the checkbox list.
  • Source and blocked-term edits are shown as compact command hints after the project editor.
Project-policy saves are inventory-count based so large ledgers stay responsive. If the selection is unchanged, policy reports Project policy unchanged without rewriting config.json. Exact blocked-term impact is reported by policy block term / policy unblock term, not by the project checkbox save. Piped/non-interactive human output keeps the full source/project/blocked-term report with exact mutation commands. policy --json includes the same granular information in sources.all and projects.all while preserving aggregate fields used by older scripts. policy block term <term> and policy unblock term <term> also report current local impact: how many current traces match, how many policy-active traces changed state, how many matches were or remain inactive because of other policy, and how many traces were checked. These commands still upload nothing.

​
selltraces doctor

Diagnoses runtime, authentication/API status, detected transcript locations, sqlite3 availability, the local ledger, and retry-cache state. Section flags limit the diagnostic to one area. doctor --json lists pass/fail checks and sets ok: false (exiting non-zero) when any fails: saved credentials the API rejects, or a Cursor or OpenCode store on this machine with no sqlite3 to read it.

​
selltraces delta

Shows cached local sync state without discovering or parsing transcripts:
  • already-synced trace count
  • pending local upload count
  • retained retry-cache payload count and bytes
  • local lifetime queued estimate
  • saved source/project policy counts
Use --json for a cached machine-readable object. Use --refresh to print the cached view first, then run a no-upload refresh preview.

​
selltraces feedback

Sends a bug report, feature request, or note to the SellTraces team. You can pass inline text, pass paths to readable files whose contents should be included, pipe stdin when no message arguments are provided, or type a prompt interactively. Logged-in machines attach their account; anonymous feedback is accepted too.

​
selltraces preview

Scans approved local traces and prints what would upload without sending an HTTP request. Preview uses the same upload-plan rules as upload.

​
selltraces sync

Compatibility alias for selltraces upload. Prefer selltraces upload in new docs, scripts, and support copy.

​
selltraces backfill

Reads existing approved transcripts on disk and ingests them with the same policy, preview, and upload-confirmation rules as upload. --dry-run and --plan preview without uploading. Non-interactive uploads require explicit policy and upload confirmation or explicit project/source decisions, matching upload.

​
Source and term flags

Limit sources:
Add one-off blocked terms:
--only overrides saved approved sources for that command. --exclude-term adds to saved blocked terms for that command without rewriting ~/.selltraces/config.json. Approve or keep private a project key from selltraces policy --json:

​
JSON output

status --json, delta --json, logout --json, feedback --json, policy --json, doctor --json, repos --json, reconcile --json, upload --json, preview --json, sync --json, and backfill --json are designed for automation. Dry-run and upload modes keep stdout as one machine-readable JSON object; progress spinners, device-login instructions, and human-readable diagnostics stay off stdout.