CLI Reference

Complete command reference for the Trace CLI, including auth, org, repo, vulnerabilities, pentests, updates, and shell completion.

The Trace CLI (tracecli) lets you authenticate, manage repositories, inspect vulnerabilities, and review pentest findings directly from your terminal.

Install

npm install -g securewithtrace

Verify the installation:

tracecli --help

List commands (org list, repo list, repo filter, vulnerabilities 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>
│   ├── 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>
├── repo
│   ├── list
│   ├── filter
│   └── clone <repository> [directory]
├── vulnerabilities
│   ├── get <id>
│   └── list
├── pentest
│   ├── list
│   └── findings
│       └── list
├── upgrade (alias: self-update)
└── completion

`auth` commands

Manage CLI authentication for your Trace account.

Starts the device authorization flow, opens a browser when possible, and stores tokens under ~/.trace/.

tracecli auth login

`tracecli auth logout`

Removes local auth token files from ~/.trace/. Prompts for confirmation in interactive terminals.

Flag	Shorthand	Default	Description
`--no-confirm`			Skip confirmation prompt (for CI/scripts).

# 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, token expiry, and whether a refresh token is present.

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.

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV: header row then one data row — columns: `loggedIn`, `expired`, `hasRefreshToken`, `userId`, `orgId`, `activeOrg`.

# 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

# TSV for awk/cut (exits 1 when not logged in)
tracecli auth status --output tsv

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

`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).

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV columns: `name`, `slug`, `organizationId`, `active`.
`--limit <n>`	`-L`	all	Maximum number of organizations to display.
`--filter <expression>`	`-f`		Repeatable filter expression. Fields: `name`, `slug`. Operators: `=` exact, `!=` not exact, `:` contains, `!:` not contains.
`--web`	`-w`		Open the organization settings page in a browser instead of listing.
`--no-pager`			Disable the interactive pager and print all results at once. The pager also disables automatically when stdout is not a TTY, `NO_PAGER=1` or `TRACECLI_NO_PAGER=1` is set, or when using `--output json`/`--output tsv`.

`tracecli org current`

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

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV columns: `name`, `slug`, `organizationId`, `source`.
`--web`	`-w`		Open the organization settings page in a browser.

`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.

Flag	Shorthand	Default	Description
`--web`	`-w`		Open the organization settings page in a browser instead of switching. If `[organization]` is provided, opens that org's settings; otherwise opens the current org's settings.

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

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

# TSV output for awk/cut
tracecli org list --output tsv | cut -f1

# Limit output to first 5 organizations
tracecli org list --limit 5

# Filter by name substring
tracecli org list --filter "name:engineering"

# Filter by exact slug
tracecli org list --filter "slug=acme-corp"

# Open organization settings in browser
tracecli org list --web

# Show current active org
tracecli org current

# Show current org as JSON
tracecli org current --output json

# Open current organization settings in browser
tracecli org current --web

# Switch by slug
tracecli org switch engineering

# Switch by org ID
tracecli org switch org_01KJTJFFG497Z1C54Z07AP6NA3

# Prompt and choose interactively
tracecli org switch

# Open a specific org's settings page in a browser
tracecli org switch engineering --web

`application` commands

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

Reads (list, get) are available to any member with view access. Writes (create, update, delete) are Trace staff only — non-staff callers get a clear permission error.

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, api-service; default web). Web and API applications require --url; CLI and mobile applications must not have one — the CLI checks this locally before calling the API.

Flag	Shorthand	Default	Description
`--type <type>`		`web`	Application type: `web`, `cli`, `mobile`, `api-service`.
`--url <url>`			Application URL. Required for `web`/`api-service`; rejected for `cli`/`mobile`.
`--repo <id-or-url>`			Link a repository at creation. Accepts a repository UUID, a URL, or `owner/repo` shorthand (resolved against the org's repositories).
`--repo-path <path>`			Path within the linked repository (ignored without `--repo`).
`--help-center-url <url>`			Help center URL.
`--docs-url <url>`			Documentation URL.
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.

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

# Create a CLI application (no URL)
tracecli application create "Release Tool" --type cli

# 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

# JSON output for scripting
tracecli application create "Web Store" --url https://store.acme.com -o json

`tracecli application list`

Lists applications in the active organization.

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV columns: `applicationId`, `name`, `type`, `applicationUrl`, `repositories`, `createdAt`.
`--no-pager`			Disable the interactive pager for table output.

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

`tracecli application get <applicationId>`

Shows a single application by UUID.

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.

`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.

Flag	Shorthand	Default	Description
`--name <name>`			New name.
`--url <url>`			New application URL (web/api-service only).
`--help-center-url <url>`			New help center URL.
`--clear-help-center-url`			Remove the help center URL (sends `null`).
`--docs-url <url>`			New documentation URL.
`--clear-docs-url`			Remove the documentation URL (sends `null`).
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.

tracecli application update 418648ea-891b-47cf-b02c-272901079f24 --name "Web Store v2"
tracecli application update 418648ea-891b-47cf-b02c-272901079f24 --docs-url https://docs.acme.com

`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 scans still reference the application.

Flag	Shorthand	Default	Description
`--yes`	`-y`		Skip the confirmation prompt (required in non-interactive shells).

# Interactive (prompts y/N)
tracecli application delete 418648ea-891b-47cf-b02c-272901079f24

# Non-interactive / CI
tracecli application delete 418648ea-891b-47cf-b02c-272901079f24 --yes

`environment` commands

Manage the environments of an application (e.g. staging, production). Every environment command requires --app <applicationId> because environments are nested under an application.

Reads (list, get) are available to any member with view access; writes (create, update, delete) are Trace staff only. 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.

Flag	Shorthand	Default	Description
`--app <applicationId>`		required	Parent application UUID.
`--url <url>`		required	Primary URL for the environment.
`--description <text>`			Free-text description.
`--production`		off	Mark as the production environment.
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.

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>`

Lists the application's environments.

Flag	Shorthand	Default	Description
`--app <applicationId>`		required	Parent application UUID.
`--output <format>`	`-o`	`table`	Output format. TSV columns: `environmentId`, `name`, `primaryUrl`, `isProduction`, `description`, `createdAt`.
`--no-pager`			Disable the interactive pager for table output.

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

Shows a single environment by UUID.

Flag	Shorthand	Default	Description
`--app <applicationId>`		required	Parent application UUID.
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.

`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).

Flag	Shorthand	Default	Description
`--app <applicationId>`		required	Parent application UUID.
`--name <name>`			New name (same format rules as create).
`--url <url>`			New primary URL.
`--description <text>`			New description.
`--production`			Mark as the production environment.
`--non-production`			Mark as non-production.
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.

tracecli environment update <envId> --app <appId> --url https://staging2.acme.com
tracecli environment update <envId> --app <appId> --production

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

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

Flag	Shorthand	Default	Description
`--app <applicationId>`		required	Parent application UUID.
`--yes`	`-y`		Skip the confirmation prompt (required in non-interactive shells).

tracecli environment delete <envId> --app <appId>
tracecli environment delete <envId> --app <appId> --yes

`credential` commands

Manage the credentials attached to an environment. Every credential command requires --env <environmentId> (credentials nest under an environment, not directly under an application).

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 are Trace staff only. 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.

Flag	Default	Description
`--env <environmentId>`	required	Parent environment UUID.
`--type <type>`	required	Credential type (see list above).
`--label <label>`	required	Human-readable label (unique per environment).
`--secret-stdin` / `--secret-file` / `--secret-env`		Secret value source (all types except `username-password`).
`--username-stdin` / `--username-file` / `--username-env`		Username source (`username-password`).
`--password-stdin` / `--password-file` / `--password-env`		Password source (`username-password`).
`--output <format>`	`table`	`table`, `json`, `tsv`.

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

Type	Flags
`bearer-token`, `jwt-token`	`--header-name`, `--token-prefix`
`api-key`	`--placement <header\|query>`, `--key-name` (required together)
`cookie`	`--cookie-name` (required), `--cookie-domain`, `--cookie-path`
`magic-auth`	`--artifact-kind <magic_link\|otp>`
`username-password`	`--method <form\|basic\|json>` (required), `--login-url`, `--username-field`, `--password-field`, `--session-cookie-name`, `--csrf-token-selector`, `--csrf-field-name`
`passphrase`	(none)

# Bearer token piped from a secrets manager
vault read -field=token secret/x | tracecli credential create --env <envId> --type bearer-token --label prod --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
tracecli credential create --env <envId> --type username-password --label login \
  --username-env LOGIN_USER --password-env LOGIN_PASS --method form --login-url https://acme.com/login

`tracecli credential list --env <environmentId>`

Lists the environment's credentials (no secrets).

Flag	Default	Description
`--env <environmentId>`	required	Parent environment UUID.
`--output <format>`	`table`	`table`, `json`, `tsv`. TSV columns: `credentialId`, `label`, `credentialType`, `authConfig`, `createdAt`.
`--no-pager`		Disable the interactive pager for table output.

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

Shows a single credential (no secret). --output as above.

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

Updates a credential's label, environment, or auth config. Secrets are immutable — to rotate, delete and recreate. Auth-config flags must match the credential's existing type, which the CLI looks up automatically.

Flag	Default	Description
`--env <environmentId>`	required	Current parent environment UUID.
`--label <label>`		New label.
`--move-env <environmentId>`		Move to another environment in the same application.
`--clear-auth-config`		Remove the auth config (sends `null`).
per-type auth flags		Same flags as create; matched against the stored type.
`--output <format>`	`table`	`table`, `json`, `tsv`.

tracecli credential update <id> --env <envId> --label "prod (rotated 2026-06)"
tracecli credential update <id> --env <envId> --login-url https://acme.com/signin
tracecli credential update <id> --env <envId> --clear-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.

Flag	Default	Description
`--env <environmentId>`	required	Parent environment UUID.
`--yes` / `-y`		Skip the confirmation prompt (required in non-interactive shells).

`repo` commands

Manage repositories connected to your Trace organization.

`tracecli repo list`

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

tracecli repo list

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. Table columns (Title Case headers): Repository URL, Platform, Status. TSV columns: `repositoryUrl`, `platform`, `status`, `defaultBranch`, `language`. When `--dependency` is set, TSV columns are: `repository`, `versions` (comma-separated).
`--limit <n>`	`-L`	`30`	Maximum repositories to display per page (max 100).
`--page <n>`		`1`	Page number to display when matching results exceed `--limit`.
`--all`			Show all matching repositories (disables pagination).
`--platform <platform>`			Filter by platform: `GITHUB`, `GITLAB`, `BITBUCKET`.
`--status <status>`			Filter by status: `CONNECTED`, `DISCONNECTED`.
`--query <query>`			Case-insensitive search across URL, repo name, branch, and language.
`--default-branch <branch>`			Case-insensitive contains match on default branch.
`--language <language>`			Case-insensitive contains match on primary language.
`--filter <expression>`	`-f`		Repeatable advanced filter expression.
`--dependency <pkg>`			Filter repositories using a dependency (e.g. `lodash@4.17.21`).
`--web`	`-w`		Open the repositories dashboard in a browser instead of listing.
`--no-pager`			Disable the interactive pager and print all results at once. The pager also disables automatically when stdout is not a TTY, `NO_PAGER=1` or `TRACECLI_NO_PAGER=1` is set, or when using `--output json`/`--output tsv`.

Advanced filter expression syntax:

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

Examples:

# List all repositories
tracecli repo list

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

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

# TSV output for awk/cut
tracecli repo list --output tsv | cut -f1

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

# Limit results
tracecli repo list --language typescript --limit 10

# Show the second page when more than 30 repositories match
tracecli repo list --page 2 --limit 30

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

# Find repositories using a specific dependency
tracecli repo list --dependency lodash@4.17.21

# Open the repositories dashboard in a browser
tracecli repo list --web

`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, --web, and --dependency.

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

# Filter by language with a result limit
tracecli repo filter --language typescript --limit 10

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

# TSV output for awk/cut
tracecli repo filter --output tsv | cut -f1

# Open the repositories dashboard in a browser
tracecli repo filter --web

`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)

Flag	Shorthand	Description
`--branch <branch>`		Clone a specific branch.
`--depth <depth>`		Shallow clone depth.
`--web`	`-w`	Open the repository URL in a browser instead of cloning. SSH remotes are converted to their HTTPS equivalent automatically.

# 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

# Open the repository page in a browser instead of cloning
tracecli repo clone securewithtrace/trace --web

# Works with SSH remotes too — converts to HTTPS for the browser
tracecli repo clone git@github.com:securewithtrace/trace.git --web

`tracecli repo set-scanning-branch [repository] --branch <name>`

Switch the configured scanning branch for one repository (or every repository in your organization via --all-repos). The scanning branch is the branch Trace runs scheduled scans on, requires a SAST baseline against, and uses for the SARIF upload gate. It is independent of the GitHub default branch — Trace tracks both separately.

When the scanning branch changes, any prior branch is recorded in repository history so dashboard filters that include past scanning branches keep surfacing previously-fixed or dismissed vulnerabilities.

Flag	Shorthand	Default	Description
`--branch <name>`			Required. New scanning branch (1–255 chars, must exist on GitHub).
`--all-repos`			Apply the same branch to every connected repository in the org. Conflicts with the positional `repository` argument.
`--migrate-open-vulns`			Relabel open vulnerabilities from the previous branch to the new branch. Fixed/dismissed vulnerabilities stay on the old branch (history-aware).
`--output <format>`	`-o`	`table`	Output format: `table`, `json`. JSON output is structured per-row for bulk mode.

# Switch a single repository's scanning branch
tracecli repo set-scanning-branch https://github.com/acme/api --branch staging

# Switch and migrate open vulnerabilities to the new branch
tracecli repo set-scanning-branch https://github.com/acme/api --branch staging --migrate-open-vulns

# Bulk: point every repo at staging in one call
tracecli repo set-scanning-branch --all-repos --branch staging --migrate-open-vulns

In bulk mode each repository runs its own switch transaction. A partial failure (e.g. one repository lacks the target branch on GitHub) does NOT undo the successful switches — the per-row status table surfaces switched, branch-missing-on-github, forbidden, already-on-branch, not-found, or error so you can re-try the failures.

`vulnerabilities` commands

`tracecli vulnerabilities get <id>`

Fetch a single vulnerability by UUID or display ID. The <id> argument accepts a UUID, a numeric display ID such as 123, or a prefixed display ID such as TRACE-123.

Flag	Shorthand	Default	Description
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV columns: `traceId`, `vulnerabilityId`, `severity`, `status`, `repository`, `file`, `line`, `cweId`, `scanMode`, `title`, `description`.
`--web`	`-w`		Open the vulnerability detail page in a browser instead of printing.

# Fetch by TRACE display ID
tracecli vulnerabilities get TRACE-123

# Fetch by numeric display ID
tracecli vulnerabilities get 123

# Fetch by UUID
tracecli vulnerabilities get 00000000-0000-4000-8000-000000000123

# JSON output for automation
tracecli vulnerabilities get TRACE-123 --output json

# TSV output for awk/cut
tracecli vulnerabilities get TRACE-123 --output tsv | cut -f1,10

# Open the vulnerability detail page in a browser
tracecli vulnerabilities get TRACE-123 --web

`tracecli vulnerabilities list`

List vulnerabilities for your organization with optional filtering. Results are sorted by severity (highest first) and limited to the first 30 by default.

Flag	Shorthand	Default	Description
`--repo <repo>`			Filter by repository — accepts `owner/repo`, full URL, or bare repo name when unambiguous.
`--severity <level>`			Filter by severity: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`.
`--status <status>`			Filter by status: `OPEN`, `IN_PROGRESS`, `FIXED`, `ARCHIVED`, `FALSE_POSITIVE`.
`--filter <expression>`	`-f`		Additional filter expression: `field=value` or `field!=value`. Repeatable. Supported fields: `repositoryId`, `severity`, `vulnerabilityType`, `status`, `cweId`, `scanMode`.
`--limit <n>`	`-L`	`30`	Maximum results to return (max `100`).
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`.
`--web`	`-w`		Open the vulnerabilities dashboard in a browser instead of listing.
`--no-pager`			Disable the interactive pager and print all results at once. The pager also disables automatically when stdout is not a TTY, `NO_PAGER=1` or `TRACECLI_NO_PAGER=1` is set, or when using `--output json`/`--output tsv`.

# List vulnerabilities (default: table, up to 30)
tracecli vulnerabilities list

# Filter by repository and severity
tracecli vulnerabilities list --repo securewithtrace/trace --severity CRITICAL

# Filter by status
tracecli vulnerabilities list --status OPEN --limit 100

# Filter by CWE ID
tracecli vulnerabilities list --filter cweId=CWE-89

# Filter by vulnerability type and scan mode (repeatable)
tracecli vulnerabilities list --filter vulnerabilityType=SAST --filter scanMode!=DAST

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

# TSV output for awk/cut
tracecli vulnerabilities list --output tsv | cut -f1,7

# Open vulnerabilities dashboard in browser
tracecli vulnerabilities list --web

`tracecli vulnerabilities fix <id>`

Trigger a Trace auto-fix PR run for a vulnerability. The agent spins up an isolated sandbox, reads the vulnerability + the repo, generates a small surgical patch, opens a draft PR, and reports the result. Staff-only dogfood — gated behind the AUTO_FIX_PR capability. Customer-admin rollout is a follow-up.

The <id> argument accepts a UUID, a numeric display ID such as 123, or a prefixed display ID such as TRACE-123.

Flag	Default	Description
`--agent <flavor>`	(auto-detected)	Override the coding agent. One of `claude-code`, `codex`. Without this flag, Trace resolves the flavor from the repo's AI-tooling profile + tie-break (override → mtime-newest → Claude Code default).
`--watch`	off	Poll the run every 3 seconds until terminal. Rolling status writes to stderr; the final row writes to stdout so `--output json --watch \| jq .` reads a clean JSON document.
`--output <format>`	`table`	Output format: `table`, `json`.

Exit codes:

0 on success (when not watching, this means the run was successfully enqueued; with --watch, this means the final status was PR_OPENED).
1 on user or server error (auth, 403, 404, daily-cap exceeded, bad flag).
2 when --watch ends in a terminal status other than PR_OPENED (e.g. NO_SAFE_FIX, INFRA_FAILED, CANCELLED).
130 when the user sends SIGINT during --watch; the run continues server-side (the CLI does NOT auto-cancel).

# Trigger and exit immediately (scripting):
tracecli vulnerabilities fix TRACE-123

# Trigger and watch until terminal:
tracecli vulnerabilities fix TRACE-123 --watch

# Trigger with codex agent (requires AZURE_OPENAI_ENABLED):
tracecli vulnerabilities fix TRACE-123 --agent codex

# JSON output (final row to stdout; rolling status to stderr under --watch):
tracecli vulnerabilities fix TRACE-123 --watch --output json | jq .

`pentest` commands

`tracecli pentest list`

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

Flag	Shorthand	Default	Description
`--status <status>`			Filter by status: `SCOPING`, `IN_PROGRESS`, `REMEDIATION`, `CLOSED`.
`--limit <n>`	`-L`	`30`	Maximum results to return (max `100`).
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV columns: displayId, title, status, startedAt, endedAt, findingsTotal.
`--web`	`-w`		Open the pentests dashboard in a browser instead of listing.
`--no-pager`			Disable the interactive pager and print all results at once. The pager also disables automatically when stdout is not a TTY, `NO_PAGER=1` or `TRACECLI_NO_PAGER=1` is set, or when using `--output json`/`--output tsv`.

# 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'

# TSV output for awk/cut
tracecli pentest list --output tsv | cut -f1,2

# Open pentests dashboard in browser
tracecli pentest list --web

`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.

Flag	Shorthand	Default	Description
`--pentest <id>`			Required. Pentest display ID (e.g. `PT-3`) or UUID.
`--severity <severity>`			Filter by severity: `CRITICAL`, `HIGH`, `MEDIUM`, `LOW`, `INFORMATIONAL`.
`--status <status>`			Filter by status: `OPEN`, `IN_PROGRESS`, `CONTESTED`, `REMEDIATED`, `VERIFIED_FIXED`, `VERIFIED_OPEN`, `ACCEPTED_WITH_CONTROLS`, `DISMISSED`.
`--limit <n>`	`-L`	`30`	Maximum results to return (max `100`).
`--output <format>`	`-o`	`table`	Output format: `table`, `json`, `tsv`. TSV columns: severity, status, category, title, cweIds, cvssScore.
`--web`	`-w`		Open the pentest detail page in a browser (navigates to the specific pentest, not the list).
`--no-pager`			Disable the interactive pager and print all results at once. The pager also disables automatically when stdout is not a TTY, `NO_PAGER=1` or `TRACECLI_NO_PAGER=1` is set, or when using `--output json`/`--output tsv`.

# 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
tracecli pentest findings list --pentest PT-3 --output json

# TSV output for awk/cut
tracecli pentest findings list --pentest PT-3 --output tsv | cut -f1,4

# Open the specific pentest detail page in a browser
tracecli pentest findings list --pentest PT-3 --web

`upgrade` command

Check for new versions and upgrade tracecli in one step.

The command supports both:

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

Flag	Shorthand	Description
`--check`		Check for updates without installing.
`--no-confirm`		Skip interactive confirmation prompt (for CI/scripts).
`--yes`	`-y`	Skip interactive confirmation prompt (alias: `--no-confirm`).

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

# Upgrade to latest version
tracecli upgrade

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

# Alias
tracecli self-update

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

A new tracecli version is available: <current> -> <latest>
Run `tracecli upgrade` to install the latest version.

`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/:

Shell	File
Bash	`~/.trace/tracecli-completion.bash`
Zsh	`~/.trace/_tracecli`
Fish	`~/.trace/tracecli-completion.fish`

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.

CLI Reference

On this page