Pushing traces — TracesHub docs

This page covers the TracesHub side of syncing. The CLI mechanics — every flag and the exact wire behavior — live in the CLI docs: remote, push / pull / sync, and the Remotes & sync concept.

The short version

Your project’s Setup tab walks through exactly this, with the remote command prefilled — open app.traceshub.com → your project → Setup and paste. What it does:

# one-time, in your local clone (already traced with `agent-trace init`):
agent-trace remote add origin \
  "https://api.traceshub.com/at/<org>/<repo>" --token <YOUR_TOKEN>

# day to day:
agent-trace push
# or push + pull in one go:
agent-trace sync

The token comes from Settings → API tokens in the app — see API tokens. Once the remote is added, agent-trace push is all you run.

The remote URL

Each project’s remote is https://api.traceshub.com/at/<org>/<repo> — the same <org>/<repo> as the project page. The URL is the canonical project identity: teammates add the same URL (with their own tokens) from different machines and share one hosted store.

Tokens are bound per remote by the CLI and stored separately from the URL. Prefer --token-env VAR over --token when you don’t want the secret persisted on disk — only the variable name is saved. (Authentication details →)

Before every push the CLI verifies the token against the remote (whoami) and refuses to proceed if the token’s org or project scope doesn’t match the URL — so traces can’t accidentally land in the wrong project.

Nothing syncs until you say so

Recording is continuous and local; uploading is always an explicit push/sync. There is no background sync, no upload-on-commit. This is a core property of the CLI that TracesHub inherits.

What ships — and how to ship less

A plain push sends the attribution ledger, commit links, traces referenced by ledgers, and their conversations/summaries. You control the detail level:

CLI config toggles decide what gets recorded and included — e.g. whether prompts, summaries, or full session conversations are part of what’s stored and shipped. See the CLI configuration reference.
Push flags restrict a given push: --only traces|ledgers|commit-links limits the artifact family; --full opts in to also pushing unattributed traces (skipped by default).

So a team that wants attribution-only on the hub can have exactly that, while another pushes full transcripts. More in Data & privacy.

Pushing from CI

Nothing about the flow is interactive, so CI works with the same three commands:

Mint a dedicated token for CI (name it accordingly — e.g. “CI pipeline” — and prefer a project-scoped token; see API tokens).
Store it as a CI secret and expose it as an environment variable.
Use --token-env so the secret never lands in the workspace:

agent-trace remote add origin \
  "https://api.traceshub.com/at/<org>/<repo>" --token-env TRACESHUB_TOKEN
agent-trace push

Revoking the token in Settings → API tokens immediately cuts that pipeline off.

When a push is rejected

The gateway checks every request, so errors are specific:

Symptom	Likely cause	Fix
`401`	Token missing, revoked, or expired.	Mint a new token; re-add with `remote set-token` or update the env var.
`403`	Token lacks `traces:write`, or your effective access on this project is read-only.	Check the token’s scopes and your access on the project (Share tab / org settings).
Scope mismatch refused before push	Token’s org/project doesn’t match the remote URL.	Use a token for this org/project — `agent-trace remote show origin` prints the URL parts and a masked token preview.
`409` / push rejected	Traces are disabled on the project.	An org owner/admin enables them from the project header.
`404` on the remote	Wrong `<org>/<repo>` in the URL, or you don’t have access to the project.	Copy the exact command from the project’s Setup tab.
`429`	Rate limit.	Wait and retry; pushes are incremental, so nothing is lost.

agent-trace doctor also verifies the remote and token binding from the CLI side (reference).

After the first push

Open the project: Analytics shows each model’s share of the codebase, and Files gives per-line blame with the conversation behind every AI-written line. If Analytics shows zero AI lines right after a push, make sure the pushed commits are on the default branch — the codebase views are computed at its HEAD, while the Raw trace store tab reflects everything pushed on any branch.