Contributor CLI quickstart

The standalone trace-commons-contributor client discovers local Claude Code and Codex sessions, plus Letta Trajectory files you name explicitly. Parsing and redaction happen on your machine.

1. Install the client

On macOS or Linux, one command:

curl -fsSL https://raw.githubusercontent.com/TraceCommons/trace-commons-server/main/scripts/install.sh -o install.sh
sh install.sh

It picks the right build for your platform, verifies it, and installs to ~/.local/bin — no sudo, nothing outside your home directory. It is written as download-then-run rather than piped into sh so you can read it first, which we would rather you did.

The script will not install a binary it cannot verify: the published checksum must match, and on macOS the signature must be valid and name Developer ID Application: Iqlusion Inc (KXSWJN7WY8). Checking who signed it matters more than checking that a signature exists — a valid signature from someone else is exactly what a looser check would accept. There is no flag to skip verification; on failure it reports which check failed and installs nothing.

Useful flags: --dir <path> to install elsewhere, --version 0.3.0 to pin a release instead of taking the newest.

On macOS you can use the Homebrew tap instead:

brew tap TraceCommons/tap
brew trust tracecommons/tap
brew install trace-commons-contributor

brew trust is required — Homebrew refuses to load a formula from a third-party tap without it, stopping at “Refusing to load formula … from untrusted tap”.

On Windows, in PowerShell:

irm https://raw.githubusercontent.com/TraceCommons/trace-commons-server/main/scripts/install.ps1 -OutFile install.ps1
.\install.ps1

Same policy as the unix installer: the published checksum must match, the Authenticode signature must be valid and name us, and there is no flag to skip either. It installs to %LOCALAPPDATA%\Programs\TraceCommons without administrator rights. Reopen the terminal afterwards so the updated PATH applies. Useful flags: -Dir <path> and -Version 0.3.0.

Or do the same by hand:

$exe  = "trace-commons-contributor-x86_64-pc-windows-msvc.exe"
$base = "https://github.com/TraceCommons/trace-commons-server/releases/download/contributor-v0.3.0"

Invoke-WebRequest "$base/$exe" -OutFile $exe
Invoke-WebRequest "$base/$exe.sha256" -OutFile "$exe.sha256"

# The published checksum must match.
$want = ((Get-Content "$exe.sha256") -split '\s+')[0]
$got  = (Get-FileHash $exe -Algorithm SHA256).Hash
if ($got -ne $want) { throw "checksum mismatch: got $got, published $want" }

# The signature must be valid AND ours.
$sig = Get-AuthenticodeSignature $exe
if ($sig.Status -ne "Valid") { throw "signature not valid: $($sig.StatusMessage)" }
if ($sig.SignerCertificate.Subject -notmatch "O=Iqlusion Inc") {
  throw "unexpected signer: $($sig.SignerCertificate.Subject)"
}

# Install under your own profile -- no admin rights required.
$dir = "$env:LOCALAPPDATA\Programs\TraceCommons"
New-Item -ItemType Directory -Force $dir | Out-Null
Move-Item -Force $exe "$dir\trace-commons-contributor.exe"
[Environment]::SetEnvironmentVariable(
  "Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")

Reopen the terminal afterwards so the new PATH applies. Get-AuthenticodeSignature ships with Windows PowerShell and needs no Visual Studio or SDK, unlike signtool. Check the subject rather than only Status -eq "Valid": a validly signed binary from somebody else passes a status-only check.

The Windows certificate is short-lived by design — the one that signed 0.1.0 was valid for three days — because Azure Trusted Signing issues a fresh certificate per signing job. The RFC3161 timestamp records that signing happened while it was live, so the signature keeps verifying afterwards. A past expiry date is expected here.

Or download a binary by hand from contributor-v0.3.0, the current CLI release. Note the tag: this repository publishes CLI releases as contributor-v* and desktop-app releases as app-v*, so GitHub’s “latest release” is whichever was cut most recently and is not reliably the one holding the CLI you came for. That is not hypothetical — app-v0.2.1 held the “latest” label for a day with no CLI in it at all. The current newest, app-v0.3.0, is the subtler version of the same trap: it does carry a CLI zip, but only a Windows one, so on macOS or Linux the latest release still has nothing for you.

Platform	File	Signed by
macOS, Apple silicon	trace-commons-contributor-aarch64-apple-darwin	Developer ID, notarized
macOS, Intel	trace-commons-contributor-x86_64-apple-darwin	Developer ID, notarized
Windows, x86_64	trace-commons-contributor-x86_64-pc-windows-msvc.exe	Authenticode, timestamped
Linux, x86_64	trace-commons-contributor-x86_64-unknown-linux-gnu	not signed

On macOS and Linux a downloaded binary needs chmod +x and a place on your PATH; on Windows use the PowerShell steps above. A .sha256 sits beside each file.

The macOS and Windows signatures are checkable offline, against Apple’s and Microsoft’s roots rather than against us, so they still mean something if the file was mirrored or re-hosted:

codesign -dvvv trace-commons-contributor-aarch64-apple-darwin 2>&1 | grep Authority
# Authority=Developer ID Application: Iqlusion Inc (KXSWJN7WY8)
# Authority=Developer ID Certification Authority
# Authority=Apple Root CA

The Linux binary carries no signature; the Linux desktop app is distributed as a GPG-signed flatpak instead.

Building from source instead

Still supported, and necessary on platforms not in the table — Linux on arm64, for example. Needs a Rust toolchain:

cargo build --release --bin trace-commons-contributor
./target/release/trace-commons-contributor --help

2. Redeem your invite

The operator sends a complete invite link through a private channel. Pass the full link, including the code after #:

trace-commons-contributor login \
  --invite '<full invite link>' \
  --allowed-hosts issuer.tracecommons.ai,ingest.tracecommons.ai

The command generates a local Ed25519 device key, registers its public half, and saves the returned tenant and service configuration. The private key never leaves your machine. A successful first-time device registration spends one use of the invite but does not submit a trace.

Read Invites and enrollment for the full security and policy model.

3. Confirm enrollment

trace-commons-contributor whoami

If you are joining through a trusted Trace Commons instance instead of a pilot invite, the older device-key and instance-signed grant flow remains available:

trace-commons-contributor login
# Give the printed device_key_id to the instance operator, then:
trace-commons-contributor login --grant '<base64-grant>'

4. Discover local sessions

trace-commons-contributor list

This reads local indexes only. It does not upload.

5. Dry-run, then submit

trace-commons-contributor submit --dry-run --since 7d
trace-commons-contributor submit --since 7d

The real submit shows an interactive selection unless you deliberately pass --yes.

6. Confirm the result

trace-commons-contributor status
trace-commons-contributor whoami

status refreshes known receipts from the server. whoami is local-only and does not print the raw contributor subject.

Source contract: merged crates/trace-commons-contributor command definitions and contributor README. See Verified source versions.