CLI Overview

The Trace CLI (tracecli) lets you authenticate, set up the applications you want tested, manage repositories, upload source archives, and review pentest findings directly from your terminal, including the pentest commands for listing engagements and pulling their findings.

Install

npm install -g securewithtrace

Verify the installation:

tracecli --help

Interactive pager

List commands (org list, repo list, repo filter, inbox list, inbox emails, upload list, pentest list, pentest findings list) render results through an interactive pager when stdout is attached to a TTY. Navigate with:

• ↑ / ↓ or k / j: move selection by one line
• PgUp / PgDn or b / f / Space: scroll by one page
• Home / g: jump to first result
• End / G: jump to last result
• q, Esc, or Ctrl+C: exit the pager

The pager is skipped automatically when:

• stdout is not a TTY (e.g. piped to another command or redirected to a file)
• the NO_PAGER=1 or TRACECLI_NO_PAGER=1 environment variable is set
• the command is invoked with --output json or --output tsv
• the command is invoked with --no-pager

Command tree

tracecli
├── auth
│   ├── login
│   ├── logout
│   └── status
├── org
│   ├── list
│   ├── current
│   └── switch [organization]
├── application (alias: app)
│   ├── create <name>
│   ├── list
│   ├── get <applicationId>
│   ├── repos <applicationId> (alias: repositories)
│   ├── update <applicationId>
│   └── delete <applicationId>
├── environment (alias: env)
│   ├── create <name> --app <applicationId>
│   ├── list [--app <applicationId>]
│   ├── get <environmentId> --app <applicationId>
│   ├── update <environmentId> --app <applicationId>
│   └── delete <environmentId> --app <applicationId>
├── credential (alias: cred)
│   ├── create --env <environmentId> --type <type> [--label <label>]
│   ├── list --env <environmentId>
│   ├── get <credentialId> --env <environmentId>
│   ├── update <credentialId> --env <environmentId>
│   ├── delete <credentialId> --env <environmentId>
│   ├── set-mfa <credentialId> --env <environmentId>
│   ├── mfa-code <credentialId> --env <environmentId>
│   └── clear-mfa <credentialId> --env <environmentId>
├── inbox
│   ├── create <label>
│   ├── list
│   ├── emails <label>
│   ├── email <label> <messageId>
│   └── delete <label>
├── repo
│   ├── list
│   ├── filter
│   └── clone <repository> [directory]
├── upload (alias: code-upload)
│   ├── create <file> (alias: source)
│   ├── build <file> --app <applicationId>
│   ├── list
│   ├── get <codeUploadId>
│   ├── resume <codeUploadId> <file>
│   ├── wait <codeUploadId>
│   ├── delete <codeUploadId>
│   └── link --app <applicationId> --upload <codeUploadId>
├── code-size
├── pentest
│   ├── list
│   ├── questionnaire <pentestId>
│   └── findings
│       ├── list
│       └── status-update
├── upgrade (alias: self-update)
└── completion

Authentication

tracecli sends Authorization: Bearer <token> on every API request. Two credential sources are supported; the first match wins.

1. TRACE_API_KEY — a long-lived Trace API key (trace_sk_...). When this environment variable is set and non-empty, it takes precedence over any files under ~/.trace/. Mint a key in the dashboard under API Keys. This is the path for CI and other non-interactive automation.
2. Device-flow login — tracecli auth login stores a WorkOS JWT and refresh token under ~/.trace/ (token and refresh-token). Use this on a developer machine.

A malformed TRACE_API_KEY fails immediately with a shape error (expected trace_sk_...) rather than sending a request that would 401. API keys are not refreshed; a 401 means the key is invalid, expired, or revoked — check the dashboard API Keys page. auth login, auth logout, and org switch refuse to run while TRACE_API_KEY is set, because mutating ~/.trace would not change which credential is used. org current and org list still work: the API returns the key's bound organization.

Some commands require a human session and reject API keys (the API returns 403 Human principal required for this operation). That includes application / environment / credential writes, application repos, source uploads, and staff-only routes. For those, unset TRACE_API_KEY and run tracecli auth login.

pentest findings status-update accepts either credential. With a key it posts to a separate automation endpoint, which your organization has to have finding automation enabled for; ask Trace to turn it on.

auth commands

Manage CLI authentication for your Trace account.

tracecli auth login

Starts the device authorization flow, opens a browser when possible, and stores tokens under ~/.trace/. Refuses to run when TRACE_API_KEY is set — unset the environment variable first.

tracecli auth login

tracecli auth logout

Removes local auth token files from ~/.trace/. Prompts for confirmation in interactive terminals. Refuses to run when TRACE_API_KEY is set; unsetting the environment variable is what actually drops API-key auth.

# Log out interactively (prompts for confirmation)
tracecli auth logout

# Skip confirmation prompt (for CI/scripts)
tracecli auth logout --no-confirm

tracecli auth status

Shows current login status, including whether you are using a user session or an API key, token expiry (user sessions), and whether a refresh token is present. For an API key, only the public key id (trace_sk_<keyId>) is shown — never the secret half. When the key came from TRACE_API_KEY, the status output says so.

Exits with code 1 when not logged in, regardless of output format. This lets scripts use tracecli auth status || tracecli auth login without extra parsing. In json and tsv modes, the structured data is still written to stdout before exiting; the exit code signals whether action is needed.

# Show login status (table mode, exits 1 and prints to stderr when not logged in)
tracecli auth status

# Machine-readable JSON (for scripts/CI, exits 1 when not logged in)
tracecli auth status --output json

# Use in scripts to auto-login when session is missing
tracecli auth status || tracecli auth login

# CI: authenticate with a dashboard API key instead of device-flow login
export TRACE_API_KEY=trace_sk_...
tracecli auth status --output json

org commands

Manage active organization context for CLI commands.

tracecli org list

Lists organizations available to your account and marks the currently active organization. Table output includes Title Case column headers (Name, Slug, Org ID).

tracecli org current

Shows the active organization context used by repo and pentest commands.

tracecli org switch [organization]

Switches the active organization context for subsequent CLI commands. The optional argument accepts organization ID, slug, or name. If omitted in an interactive terminal, tracecli prompts you to choose from your available organizations. Refuses to run when TRACE_API_KEY is set — API keys are bound to a single organization.

# List available orgs and see which one is active
tracecli org list

# JSON output for scripting
tracecli org list --output json | jq '.[].slug'

# Show current active org
tracecli org current

# Switch by slug
tracecli org switch engineering

# Switch by org ID
tracecli org switch org_01KJTJFFG497Z1C54Z07AP6NA3

# Prompt and choose interactively
tracecli org switch

application commands

Manage applications in the active organization. Applications are the scope object for environments, credentials, and pentests.

Reads list and get are available to any member with view access. repos is not: link details (role, path, scan state) require an organization admin or Trace staff signed in with a browser session — API keys are rejected. Writes (create, update, delete) require an organization admin signed in with a browser session (or Trace staff) on a pentest-enabled organization — API keys are rejected for these writes.

All commands accept --output <format> (-o) with table (default), json, or tsv. The group is also available under the app alias.

tracecli application create <name>

Creates an application. --type is case-insensitive (web, cli, mobile, desktop, api-service; default web). Web and API applications require --url; CLI, mobile, and desktop applications must not have one, the CLI checks this locally before calling the API.

# Create an API application
tracecli application create "Billing API" --type api-service --url https://billing.acme.com

# Create a web app and link a repository at creation
tracecli application create "Web Store" --url https://store.acme.com --repo acme/store --repo-path apps/web

tracecli application list

Lists applications in the active organization.

tracecli application list
tracecli application list --output json | jq '.[].name'

tracecli application get <applicationId>

Shows a single application by UUID. Accepts --output <format> (-o): table (default), json, tsv.

The Repos line counts every link, including scan-disabled ones. That total is not a readiness signal: scans and pentest start-readiness both skip disabled links. Use application repos for the per-link scan state.

tracecli application repos <applicationId>

Lists the repositories linked to an application, with the SCAN column showing whether each link is scan-enabled. Also available as application repositories.

A link with SCAN=no is still linked — it counts in application get's Repos total — but scans skip it and it does not satisfy the repository precondition for starting a pentest. This is the command to reach for when an application appears to have repositories but work won't start.

tracecli application repos <appId>
# count only the links that actually count
tracecli application repos <appId> -o json | jq '[.[] | select(.scanEnabled)] | length'

tracecli application update <applicationId>

Updates an application. The update is partial: only the flags you pass are changed. The application type cannot be changed, and repository links are managed separately (not via update). Pass at least one field.

tracecli application delete <applicationId>

Deletes an application. Prompts for confirmation in interactive terminals; in non-interactive shells (CI, pipes) it refuses unless --yes is passed. Deletion is blocked by the API when pentests still reference the application.

environment commands

Manage the environments of an application (e.g. staging, production). Environments are nested under an application, so every environment command requires --app <applicationId> — except list, where it is optional (omit it to list every environment in the organization).

Reads (list, get) are available to any member with view access; writes (create, update, delete) require an organization admin (or Trace staff) on a pentest-enabled organization, and reject API keys. All commands accept --output <format> (-o): table (default), json, tsv. The group is also available under the env alias.

tracecli environment create <name> --app <applicationId>

Creates an environment. The name must be lowercase letters, digits, or dashes, starting with a letter (validated locally). An application may have at most one production environment. Mobile and desktop applications do not have environments; the API rejects create on those types.

tracecli environment create staging --app <appId> --url https://staging.acme.com
tracecli environment create production --app <appId> --url https://acme.com --production

tracecli environment list [--app <applicationId>]

With --app, lists that application's environments. TSV columns: environmentId, name, primaryUrl, isProduction, description, createdAt.

Without --app, lists every environment in the organization with an APPLICATION column naming its owner, so you can find a target without already knowing its application UUID. TSV columns for this form: environmentId, applicationId, applicationName, name, primaryUrl, isProduction, createdAt.

There is no org-scoped environments endpoint, so the unscoped form fans out one request per application. If any of those requests fails the command aborts and names the application rather than printing a short list that would look complete.

tracecli environment list
tracecli environment list --app <appId>

tracecli environment get <environmentId> --app <applicationId>

Shows a single environment by UUID. Accepts --output <format> (-o).

tracecli environment update <environmentId> --app <applicationId>

Updates an environment. Partial, only the flags you pass are changed. Pass at least one. Use --production / --non-production to set the production flag (passing both is an error). Other fields: --name, --url, --description.

tracecli environment delete <environmentId> --app <applicationId>

Deletes an environment. Prompts for confirmation interactively; refuses without --yes in non-interactive shells. The API blocks deletion while the environment is frozen by an active pentest.

credential commands

Manage the credentials attached to an environment. Credential records nest under an environment (--env on create/list/get/update/delete). Mint a Trace-hosted inbox first with inbox create when the test account needs a magic-link or OTP address.

Secrets are never displayed. list/get return only the label, type, and (non-secret) auth config, never the secret value. Reads are available to any member with view access; writes require an organization admin (or Trace staff) on a pentest-enabled organization, and reject API keys. The group is also available under the cred alias.

Secret input

Secret material is read from one of --secret-stdin, --secret-file <path>, or --secret-env <name>, or a no-echo prompt when none is given on a TTY. There is no inline --secret flag, so secrets don't leak through shell history, ps, or CI logs. For username-password, both the username and password use the same mechanism (--username-* and --password-*); at most one secret may come from stdin.

tracecli credential create --env <environmentId> --type <type> [--label <label>]

Creates a credential. --type is one of bearer-token, jwt-token, api-key, passphrase, username-password, cookie, magic-auth.

Per-type authConfig convenience flags (each rejected if it doesn't match --type):

# Bearer token piped from a secrets manager (label defaults to "Bearer token (<env name>)")
vault read -field=token secret/x | tracecli credential create --env <envId> --type bearer-token --secret-stdin

# API key with placement config
tracecli credential create --env <envId> --type api-key --label "prod key" --secret-env API_KEY --placement header --key-name X-API-Key

# Username/password with form-login config (label defaults to "<username> (<env name>)")
tracecli credential create --env <envId> --type username-password \
  --username-env LOGIN_USER --password-env LOGIN_PASS --method form --login-url https://acme.com/login

# Passwordless login that reads a Trace-hosted inbox (mint the address first)
ADDRESS=$(tracecli inbox create portal -o json | jq -r .address)
echo "$ADDRESS" | tracecli credential create --env <envId> --type magic-auth --secret-stdin

tracecli credential list --env <environmentId>

Lists the environment's credentials (no secrets). TSV columns: credentialId, label, credentialType, authConfig, mfa, createdAt. The mfa column is the second-factor kind (TOTP) or empty.

tracecli credential get <credentialId> --env <environmentId>

Shows a single credential (no secret).

tracecli credential update <credentialId> --env <environmentId>

Updates a credential's label, environment, or auth config. This command does not change the secret — rotate a secret from the dashboard (Applications → environment → credential → Rotate secret), which keeps the same credential and its scan history. Auth-config flags must match the credential's existing type, which the CLI looks up automatically. Use --move-env <environmentId> to move it to another environment in the same application, or --clear-auth-config to remove the auth config.

tracecli credential delete <credentialId> --env <environmentId>

Deletes a credential. Prompts for confirmation interactively; refuses without --yes in non-interactive shells. The API blocks deletion while the credential is in use by an active pentest.

tracecli credential set-mfa <credentialId> --env <environmentId>

Attaches a TOTP second factor to an account credential, so Trace can log into a target that enforces MFA. Only username-password and magic-auth credentials can carry one — a bearer token or API key has no login step for a factor to sit in front of.

The setup key is either a full otpauth:// URI or the bare base32 key a setup page shows under "can't scan the QR code?" — not a 6-digit code. Like every secret in this CLI it is read from stdin, a file, or an environment variable, never an inline flag, so it stays out of shell history and CI logs.

Trace stores the key encrypted under its own KMS envelope, separate from the password, so rotating one leaves the other intact. There is no command, endpoint, or dashboard view that reads the key back out; the only thing Trace will return is a generated code.

tracecli credential set-mfa <credentialId> --env <envId> --setup-key-stdin
tracecli credential set-mfa <credentialId> --env <envId> --setup-key-env TOTP_SETUP_KEY

Re-running it replaces the existing factor in place, keeping the same credential and its scan history.

tracecli credential mfa-code <credentialId> --env <environmentId>

Prints the account's current TOTP code. Use it to confirm an enrolment took. The code always has a few seconds of life left — if the current window is nearly over, the API waits for the next one rather than returning a code that would be rejected as stale.

--output tsv prints the bare code with no surrounding text, for piping into a form filler.

tracecli credential clear-mfa <credentialId> --env <environmentId>

Removes the second factor. Succeeds whether or not one was enrolled.

inbox commands

Provision and read org-scoped Trace-hosted email inboxes. These are the addresses you register as magic-link / OTP identities (or as the username on a username-password account). They do not take --env.

tracecli inbox create <label>

Provisions a Trace-hosted inbox. <label> must be lowercase letters, digits, or dashes, starting with a letter, at most 40 characters. Creates require an organization admin (or Trace staff) on a pentest-enabled organization. The minted address is {org-slug}-{label}@pentest.securewithtrace.com.

tracecli inbox create portal
ADDRESS=$(tracecli inbox create qa-admin -o json | jq -r .address)

Use the printed address as the test-account email when creating a magic-auth or username-password credential.

tracecli inbox list

Lists the organization's inboxes and the per-org quota. TSV columns: address, label, createdAt. Available to any member with view access.

tracecli inbox emails <label>

Lists emails in a Trace-hosted inbox the active organization owns. Newest first. An inbox that is not assigned to your organization looks the same as a missing label.

tracecli inbox emails portal
tracecli inbox emails portal --limit 10 -o json

tracecli inbox email <label> <messageId>

Reads one email, including its body. <messageId> comes from the ID column of inbox emails (or from JSON/TSV). TSV columns: messageId, from, to, subject, receivedAt, unread, truncated, links, body.

tracecli inbox email portal m-1

tracecli inbox delete <label>

Deletes an inbox. Prompts for confirmation interactively; refuses without --yes in non-interactive shells.

repo commands

Manage repositories connected to your Trace organization. These are the sources Trace clones for a whitebox pentest.

tracecli repo list

Lists all repositories in your organization with their connection status and platform.

tracecli repo list

Advanced filter expression syntax:

• Format: <field><operator><value>
• Fields: platform, status, url, repo, branch, language
• Operators: = exact, != not exact, : contains, !: not contains

# List all repositories
tracecli repo list

# Filter by platform and status
tracecli repo list --platform GITHUB --status CONNECTED

# JSON output for automation (CI: export TRACE_API_KEY)
tracecli repo list --output json | jq '.[].repositoryUrl'

# Advanced repeatable filter expressions
tracecli repo list --filter "platform=GITHUB" --filter "repo:trace" --filter "status!=DISCONNECTED"

# Return every matching repository in one command
tracecli repo list --all

tracecli repo filter

Filter repositories using the same options and behavior as tracecli repo list. Accepts all flags from repo list, including --output, --limit, --filter, and --web.

# Filter by expression
tracecli repo filter --filter "platform=GITHUB" --filter "status=CONNECTED"

# JSON output for automation
tracecli repo filter --output json | jq '.[].repositoryUrl'

tracecli repo clone <repository> [directory]

Clone a repository by URL or shorthand. When the repository is connected to Trace, a short-lived access token is used automatically: a GitHub App installation token for GitHub repositories, or a vended app token for Bitbucket repositories. Credentials are never stored in the Git remote URL. Repositories on other hosts (or cloned over SSH) fall back to your local Git credentials.

Supported <repository> formats:

• https://github.com/owner/repo
• https://bitbucket.org/workspace/repo
• git@github.com:owner/repo.git
• owner/repo (expanded to GitHub HTTPS)

# Clone by owner/repo shorthand
tracecli repo clone securewithtrace/trace

# Clone into a custom directory
tracecli repo clone securewithtrace/trace trace-src

# Clone a specific branch with depth 1
tracecli repo clone securewithtrace/trace --branch main --depth 1

# Clone a connected Bitbucket repository
tracecli repo clone https://bitbucket.org/workspace/repo

upload commands

Upload a source ZIP when the application is not on GitHub, or attach an APK/IPA build to an existing application. The group is also available under the code-upload alias.

Uploads require an organization admin (or Trace staff) signed in with a browser session on a pentest-enabled organization. API keys are rejected.

upload create is a code upload: a .zip that becomes an uploaded repository after malware scanning finishes. Link it with upload link. upload build --app is a mobile build attached to an existing application. The two are not interchangeable.

The file is hashed locally, then uploaded in 10 MB parts straight to storage. Interrupted transfers resume from the parts that already landed, as long as you pass the same file (size and SHA-256 must match).

tracecli upload create <file>

Uploads a .zip source archive. Also available as upload source. APK and IPA files are rejected and pointed at upload build --app.

tracecli upload create ./checkout.zip
tracecli upload create ./checkout.zip --name "Checkout" --wait

If the transfer is interrupted, the command prints a upload resume line with the upload id.

tracecli upload build <file> --app <applicationId>

Uploads an .apk or .ipa and attaches it to an existing application. Source ZIPs are rejected and pointed at upload create.

tracecli upload build ./app-release.apk --app <applicationId>
tracecli upload build ./app.ipa --app <applicationId> --name "iOS build"

tracecli upload list

Lists uploads in the active organization.

tracecli upload get <codeUploadId>

Shows one upload by UUID. Accepts --output <format> (-o): table (default), json, tsv.

tracecli upload resume <codeUploadId> <file>

Resumes an interrupted upload. <file> must be the same bytes as the original (size and SHA-256). Parts already stored are skipped. Accepts --wait and --output.

tracecli upload resume <codeUploadId> ./checkout.zip

tracecli upload wait <codeUploadId>

Polls until the upload reaches READY, REJECTED, FAILED, or DELETING. Exits 0 only on READY. Accepts --output.

tracecli upload delete <codeUploadId>

Deletes the upload and its stored bytes. Prompts for confirmation interactively; refuses without --yes in non-interactive shells.

tracecli upload link --app <applicationId> --upload <codeUploadId>

Links a ready source ZIP to an application. The upload must be READY with a clean malware scan. APK and IPA builds cannot be linked this way (upload build --app attaches them at upload time).

tracecli upload link --app <applicationId> --upload <codeUploadId>

code-size command

tracecli code-size

Show the billable lines of code across your connected repositories: the same number shown on the integration settings pages, for the active organization (tracecli org current).

Billable SLOC is counted from each repository's current scanning branch. Blanks, comments, tests, docs, config and vendored code are excluded, which is why the billable number is roughly half what a plain scc run reports. The "What's counted" table sums exactly to the raw line total, so you can reconcile the two. How counting works covers the rules and how to reproduce them.

tracecli code-size

Code size for acme

  4,256,689 billable SLOC
  of 15,359,962 total lines across 30 measured repositories

What's counted
  Billable code                            4,256,689
  Blank & comment lines in billable files  1,137,136
  Tests                                    2,869,063
  Documentation                              410,265
  Configuration & data                     6,242,480
  Vendored & generated                       444,329

By repository
  acme/platform             490,858
  acme/portal               308,114
  ... 10 more

Repositories connected but not yet measured are named in the summary and left out of the totals, rather than counted as zero.

Options

# Every repository, no collapsing
tracecli code-size --repos 0

# Just the number, for a script
tracecli code-size --output json | jq '.totals.billableSloc'

# Repository and count, tab-separated
tracecli code-size --output tsv | cut -f1,2

pentest commands

Work with penetration tests from the terminal: list the engagements in your organization, fill the optional intake questionnaire, pull findings, and update finding status as you remediate. These operate on the active organization (tracecli org current).

tracecli pentest list

List pentests for your organization, including status, date range, and finding counts.

# List pentests
tracecli pentest list

# Filter by status
tracecli pentest list --status IN_PROGRESS

# JSON output for scripting
tracecli pentest list --output json | jq '.[].title'

tracecli pentest questionnaire <pentestId>

View or fill the optional customer intake questionnaire for a pentest (identified by display ID like PT-1 or UUID). Answers help Trace scope the engagement while it is still in DRAFT or READY_TO_START. The form is never required to start a pentest.

Modes

• --show — print answers (and whether editing is still open).
• --file <path> — upload a full answers object (overwrite).
• --submit — freeze answers. Combine with --file, or use alone to freeze whatever is already stored.
• TTY default (no flags) — load-merge-write: GET existing answers, prompt each question with @clack/prompts (skip / empty keeps the previous value; first-time skip omits the key), confirm, then PUT the merged object. Free-text answers are multi-line: Enter starts a new line and Enter on an empty line finishes the answer; option lists toggle with Space and advance with Enter.
• Non-TTY without --show / --file / --submit — exits 2 with guidance.

Auth: reads accept a browser session or API key. Writes require an organization admin (or Trace staff) signed in via tracecli auth login — API keys are rejected.

# Print current answers
tracecli pentest questionnaire PT-1 --show

# Upload answers from a file (answers object only)
tracecli pentest questionnaire PT-1 --file answers.json

# Upload and freeze
tracecli pentest questionnaire PT-1 --file answers.json --submit

# Freeze the current answers
tracecli pentest questionnaire PT-1 --submit

# Interactive fill / edit (TTY)
tracecli pentest questionnaire PT-1

Example answers.json (partial objects are valid — omit keys you are not setting):

{
  "issueClasses": ["AUTHZ_IDOR", "INJECTION"],
  "issueClassesNotes": "Webhook replay worries us too",
  "focusAreas": "Billing API and admin console",
  "surfaces": ["WEB", "PUBLIC_API"],
  "surfacesNotes": "Plus an internal admin console on its own host"
}

Each question also takes free text, so the two option-list questions (issueClasses, surfaces) carry an issueClassesNotes / surfacesNotes companion for anything the options don't cover.

tracecli pentest findings list

List findings for a specific pentest, sorted by severity. The pentest can be identified by display ID (e.g. PT-3) or UUID. Results are filtered client-side and limited to 30 by default.

# List findings for a pentest
tracecli pentest findings list --pentest PT-3

# Filter to critical findings only
tracecli pentest findings list --pentest PT-3 --severity CRITICAL

# Show open findings, limit to 20
tracecli pentest findings list --pentest PT-3 --status OPEN --limit 20

# JSON output, pull structured findings into your own tooling
tracecli pentest findings list --pentest PT-3 --output json

# TSV output for awk/cut (severity + title)
tracecli pentest findings list --pentest PT-3 --output tsv | cut -f1,4

Without --detail, every output format returns a summary row per finding — title, severity, category, status, CWE IDs, CVSS vector and score, and the affected repository/file/line references. That is enough to triage, ticket, or chart, but it does not include the finding's write-up. For the finding lifecycle and what each status means, see the Pentest Overview.

Pulling full findings

--detail returns the same findings with every prose section attached: description, proof of concept, remediation, root cause analysis, impact, attack scenario, severity considerations, and verification. It is the form to use when something other than a person is going to read the findings — a coding agent that fixes them, or your own remediation tooling.

# Every finding for an engagement, full write-up included
tracecli pentest findings list --pentest PT-3 --detail --output json

# Narrow it first — the filters apply the same way
tracecli pentest findings list --pentest PT-3 --detail --output json --severity CRITICAL

# Hand the whole engagement to an agent to work through
tracecli pentest findings list --pentest PT-3 --detail --output json > findings.json

A few things worth knowing:

• --detail requires --output json. Prose does not survive the table or TSV layouts, so those combinations are rejected rather than silently truncated.
• Pagination is handled for you. The command walks every page and prints one JSON array, and there is no default cap on the result count — you get the whole engagement unless you pass --limit yourself.
• A Trace API key works here, so this runs unattended in CI, and --pentest PT-3 works with one — the detail endpoint resolves the display ID itself rather than looking it up first. Findings stay scoped to your organization, and you get the ones published to you.
• After the agent finishes a fix, mark the finding with status-update (IN_PROGRESS while working, REMEDIATED when it is ready for retest). An API key can drive that write once finding automation is enabled for your organization.

tracecli pentest findings status-update

Move a published finding to IN_PROGRESS or REMEDIATED — the same customer transitions as the dashboard, so an agent that pulled findings with --detail can mark them as it works. Leave a finding IN_PROGRESS (and skip REMEDIATED) to keep it out of the retest queue.

IN_PROGRESS is allowed from OPEN or VERIFIED_OPEN. REMEDIATED is allowed from OPEN, IN_PROGRESS, or VERIFIED_OPEN. The identifiers are sent as typed — the API resolves PT-3 / PTF-7 itself.

Auth: a browser session attributes the change to you. A Trace API key works once Trace enables finding automation for your organization, and the CLI routes key traffic to a separate automation endpoint. Key-driven changes are recorded as api-key:<key name> and appear as yours (not Trace's) in the finding's history, and the key's REMEDIATED is a claim like any other: only a Trace retest can mark a finding verified fixed.

# Agent starts a fix
tracecli pentest findings status-update --pentest PT-3 --finding 7 --status IN_PROGRESS

# Fix is ready for Trace to re-test
tracecli pentest findings status-update --pentest PT-3 --finding PTF-7 --status REMEDIATED

# Same, with a note, machine-readable
tracecli pentest findings status-update --pentest PT-3 --finding 7 --status REMEDIATED \
  --note "Fixed in PR 412" --output json

tracecli pentest findings attach-evidence

Attach a screenshot, screen recording, HTTP transcript, HAR, or data export to a finding — for proof captured by hand rather than by an agent. Trace staff only.

The file uploads directly to storage rather than through the API, so recordings of any reasonable size work. The exhibit kind and content type are derived from the file extension.

# Attach a screenshot as internal working material
tracecli pentest findings attach-evidence --pentest PT-3 --finding 7 --file ./poc.png

# Attach a screen recording with a caption, placed under Proof of Concept
tracecli pentest findings attach-evidence --pentest PT-3 --finding PTF-7 --file ./poc.mov \
  --caption "Cookie survives logout, replayed 40s later" --section proofOfConcept

# Attach a data export and publish it to the customer
tracecli pentest findings attach-evidence --pentest PT-3 --finding 7 --file ./roster.json \
  --caption "Full member roster returned to a non-member" --customer-facing

New exhibits are staff-internal unless --customer-facing is passed, and they append after the finding's existing evidence. HAR captures and video are always staff-internal at attach — a HAR can carry a live session token, and a recording needs a redaction pass — so publish a video with the toggle in the staff console's evidence panel after reviewing it. Evidence can only be attached while the pentest is open; reopen a closed one first.

upgrade command

Check for new versions and upgrade tracecli in one step.

The command supports both:

• tracecli upgrade (recommended)
• tracecli self-update (alias)

# Check if an update is available
tracecli upgrade --check

# Upgrade to latest version
tracecli upgrade

# Non-interactive upgrade (CI/scripts)
tracecli upgrade --no-confirm

When a newer version is available, tracecli also shows a lightweight upgrade notice in interactive terminals.

completion command

Generate and install shell completion scripts.

tracecli completion --shell bash
tracecli completion --shell zsh
tracecli completion --shell fish

If --shell is omitted, tracecli auto-detects from the SHELL environment variable.

Generated files are written under ~/.trace/:

Each shell requires a one-time setup line added to your shell config. tracecli completion --shell <shell> prints the exact instructions after writing the file.