tracecli

tracecli is the official CLI for Trace.

Use it to authenticate, browse and filter connected repositories, clone repositories, and inspect vulnerabilities directly from the command line.

Install

npm install -g securewithtrace

Then verify:

tracecli --help

Requirements

• Bun runtime available on your PATH
• Git (for tracecli repo clone)
• A Trace account with access to at least one organization

Quick Start

# 1) Authenticate
tracecli auth login

# 2) Confirm session
tracecli auth status

# 3) List connected repositories
tracecli repo list

# 3b) Filter repositories
tracecli repo list --platform GITHUB --status CONNECTED --query trace

# 4) View vulnerabilities
tracecli vulnerabilities list --severity HIGH

What You Can Do

• Authenticate securely with device authorization flow (auth login/logout/status)
• List and filter repositories connected to your Trace organization (repo list, repo filter)
• Find repositories by dependency with optional version filtering (repo list --dependency)
• Clone repositories with secure token handling (repo clone)
• Filter vulnerabilities by repo, severity, and status (vulnerabilities list)
• Export results as JSON or TSV for automation (vulnerabilities list --output json)
• Upgrade easily with built-in update checks and upgrade command (upgrade, self-update)

Command Reference

Authentication

tracecli auth login
tracecli auth status
tracecli auth logout

Organization context

tracecli org list
tracecli org current
tracecli org switch
tracecli org switch <organization-id-or-slug>

When your account belongs to multiple organizations, use tracecli org switch to set the active organization context used by repository, vulnerability, and pentest commands.

Repositories

# List org repositories known to Trace
tracecli repo list

# List only connected GitHub repositories that match "trace"
tracecli repo list --platform GITHUB --status CONNECTED --query trace

# Advanced filtering syntax (repeatable)
tracecli repo list --filter "platform=GITHUB" --filter "repo:trace" --filter "status!=DISCONNECTED"

# Alias command for filtering
tracecli repo filter --filter "language:typescript" --filter "branch=main"

# Find repositories that use a specific dependency
tracecli repo list --dependency lodash

# Filter by dependency at a specific version
tracecli repo list --dependency [email protected]

# Filter by scoped package with partial version match
tracecli repo list --dependency @types/node@20

# Dependency results as JSON
tracecli repo list --dependency react --json | jq '.[].fullName'

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

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

Vulnerabilities

# List vulnerabilities across your organization (default: 30 results)
tracecli vulnerabilities list

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

# Filter by severity and status
tracecli vulnerabilities list --severity CRITICAL --status OPEN

# Increase result limit
tracecli vulnerabilities list --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

Flags:

| Flag | Shorthand | Description | |------|-----------|-------------| | --repo <repo> | | Filter by repository name or owner/repo | | --severity <level> | | Filter by severity | | --status <status> | | Filter by status | | --filter <expression> | -f | Repeatable filter expression: field=value or field!=value. Supported fields: repositoryId, severity, vulnerabilityType, status, cweId, scanMode | | --limit <n> | -L | Max results (default: 30, max: 100) | | --output <format> | -o | Output format: table (default), json, tsv | | --web | -w | Open vulnerabilities dashboard in browser |

Supported filter values:

• --severity: CRITICAL, HIGH, MEDIUM, LOW
• --status: OPEN, IN_PROGRESS, FIXED, ARCHIVED, FALSE_POSITIVE

Repository filter options:

• --platform: GITHUB, GITLAB, BITBUCKET
• --status: CONNECTED, DISCONNECTED
• --query: case-insensitive contains match across URL, repo name, default branch, and language
• --default-branch: case-insensitive contains match for default branch
• --language: case-insensitive contains match for primary language
• --filter: repeatable advanced expression in the form <field><operator><value>
  • Supported fields: platform, status, url, repo, branch, language
  • Supported operators: = (exact), != (not exact), : (contains), !: (not contains)
• --dependency: filter by dependency name with optional @version (e.g. lodash, [email protected], @types/node@20)

Pentests

# List pentests for your organization
tracecli pentest list

# Increase result limit
tracecli pentest list --limit 50

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

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

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

# Findings as JSON
tracecli pentest findings list --pentest PT-3 --output json

# Findings as TSV
tracecli pentest findings list --pentest PT-3 --output tsv | cut -f1,4

# Open pentests dashboard in browser
tracecli pentest findings list --pentest PT-3 --web

Flags for pentest list:

| Flag | Shorthand | Description | |------|-----------|-------------| | --limit <n> | -L | Max results (default: 30, max: 100) | | --output <format> | -o | Output format: table (default), json, tsv | | --web | -w | Open pentests dashboard in browser |

Flags for pentest findings list:

| Flag | Shorthand | Description | |------|-----------|-------------| | --pentest <id> | | Pentest display ID (e.g. PT-3) or UUID (required) | | --output <format> | -o | Output format: table (default), json, tsv | | --web | -w | Open pentests dashboard in browser |

Upgrades

tracecli checks for new versions in interactive sessions and shows a one-line upgrade prompt when an update is available.

# Check whether a newer version is available
tracecli upgrade --check

# Upgrade to the latest published CLI version
tracecli upgrade

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

# Alias
tracecli self-update

Flags:

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

Security Notes

• Access tokens are stored at ~/.trace/token.
• Refresh tokens are stored at ~/.trace/refresh-token and used for automatic access-token refresh.
• repo clone uses secure credential flow for GitHub clones when available.
• Credentials are not persisted in Git remote URLs after clone completes.

Links

• Website: https://securewithtrace.com