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]
├── 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

`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 GitHub App installation token is used automatically — credentials are never stored in the Git remote URL.

Supported <repository> formats:

https://github.com/owner/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

# 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

`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

`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