@tracescout/cli

TraceScout command-line tools — private source-map upload and debug-ID injection for stack-trace symbolication.

TraceScout symbolicates minified production stack traces at read time against source maps you upload privately. Maps are never served publicly and never leave your TraceScout workspace.

Install

npm install --save-dev @tracescout/cli
# or run without installing:
npx @tracescout/cli sourcemaps upload --help

Node.js ≥ 18. Zero runtime dependencies.

Upload source maps

export TRACESCOUT_AUTH_TOKEN=tsk_sm_...   # scoped upload token (see below)

npx tracescout sourcemaps upload \
  --project <project-id> \
  --release "$GIT_SHA" \
  --dist web \
  --url-prefix "~/" \
  --path ./dist

• --path may be a directory (recursive discovery of *.js.map next to their generated files) or a single map file.
• --url-prefix "~/" means "any host, this path" — the recommended identity for hashed asset paths (~/assets/index-abc123.js).
• Re-running the same upload is idempotent (the server dedupes by content + identity); retries never create duplicates.

Options

| Flag | Meaning | Default | |---|---|---| | --project <uuid> | TraceScout project id (required) | — | | --release <str> | Release identifying this build | — | | --dist <str> | Build variant (e.g. web, ios) | — | | --url-prefix <str> | Artifact URL identity prefix | ~/ | | --path <dir\|file> | Build output to scan | — | | --policy strip\|retain\|reject | sourcesContent policy | server default (strip) | | --dry-run | Plan without uploading (no token needed) | off | | --json | Machine-readable output | off | | --quiet | Suppress progress output | off | | --concurrency <n> | Parallel uploads | 4 | | --timeout <ms> | Per-request timeout | 30000 | | --retries <n> | Retries with exponential backoff | 3 |

Environment variables

| Variable | Meaning | |---|---| | TRACESCOUT_AUTH_TOKEN | Scoped upload token (never passed as a CLI argument) | | TRACESCOUT_API_URL | API base (default https://api.tracescout.com) | | TRACESCOUT_PROJECT_ID / TRACESCOUT_RELEASE / TRACESCOUT_DIST | Defaults for the matching flags | | HTTPS_PROXY / HTTP_PROXY | Standard proxy support |

Exit codes

0 success (including all-idempotent) · 1 one or more uploads failed · 2 usage error · 3 auth/feature error (bad token, feature disabled).

Debug IDs

tracescout sourcemaps inject --path ./dist injects a deterministic per-artifact debug ID into each generated JS file (//# debugId=<uuid>) and its map ("debugId" field). The upload command verifies bundle↔map IDs agree and refuses mismatches. With the Vite plugin this happens automatically at build time.

Debug IDs are the strongest match identity — prefer them over release+URL fallback matching.

Upload tokens

A workspace Owner/Admin mints a scoped, write-only upload token (tsk_sm_…, shown once) via the TraceScout API. The token can only upload source maps — it cannot read maps, sources, or any other data. Store it as a CI secret; rotate by minting a new token and revoking the old one.

Security

• The token is read from the environment only and never printed; Authorization headers are redacted in all output, including --debug mode.
• Source/map contents are never written to logs.
• Discovery never follows symlinks and never escapes the given --path root.

Docs: https://docs.tracescout.com/docs/guides/source-maps

License

Apache-2.0. TraceScout names and logos are trademarks of TraceScout — no trademark rights are granted.