Trace CLI Reference

The Trace CLI (tracecli) lets you authenticate, list and clone repositories, and inspect vulnerabilities from your terminal.

Install

npm install -g securewithtrace

Verify the installation:

tracecli --help

Command overview

tracecli
├── auth
│   ├── login
│   ├── logout
│   └── status
├── repo
│   ├── list
│   └── clone <repository> [directory]
├── vulnerabilities
│   └── list
└── completion

Global help and version

tracecli --help
tracecli --version

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

tracecli auth status

Shows current login status, expiry details (when available), and whether a refresh token is present.

tracecli auth logout

Removes local auth token files from ~/.trace/.

repo commands

Manage repositories connected to your Trace organization.

tracecli repo list

List repositories in your organization:

tracecli repo list

tracecli repo clone <repository> [directory]

Clone a repository by URL or shorthand.

Supported <repository> formats:

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

Options:

• --branch <branch>: clone a specific branch
• --depth <depth>: shallow clone depth

Examples:

# 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

vulnerabilities commands

tracecli vulnerabilities list

List vulnerabilities for your organization with optional filtering.

Options:

• --repo <repo>: filter by repository (URL, owner/repo, or bare repo name if unambiguous)
• --severity <severity>: CRITICAL, HIGH, MEDIUM, LOW
• --status <status>: OPEN, IN_PROGRESS, FIXED, IGNORED, FALSE_POSITIVE
• --page-size <size>: results per page (default 25, max 200)
• --json: output JSON and fetch all pages without interactive prompts

Examples:

# Interactive list
tracecli vulnerabilities list

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

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

# JSON output for automation
tracecli vulnerabilities list --json

completion command

Generate shell completion scripts:

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

If --shell is omitted, tracecli will try to detect it from the SHELL environment variable.

Generated files are written under ~/.trace/:

• Bash: ~/.trace/tracecli-completion.bash
• Zsh: ~/.trace/_tracecli
• Fish: ~/.trace/tracecli-completion.fish