CLI Reference

Pretense CLI

Every command, flag, and example. Grouped by category: Core scanning, Setup, Authentication, and Utility.

Core Setup Auth Utility Global flags Exit codes

Command overview

Command	Description	Group
`pretense scan`	Scan files or directories for secrets and high-risk identifiers.	Core
`pretense scan ci`	Full repository scan designed for CI pipelines.	Core
`pretense review`	AI-powered code review that checks for security issues, mutation coverage gaps, and best practices.	Core
`pretense init`	Initialize Pretense in the current repository.	Setup
`pretense install`	Install Pretense git hooks into the current repository.	Setup
`pretense config list`	Print the current resolved configuration as a table.	Setup
`pretense auth login`	Authenticate with Pretense Cloud.	Auth
`pretense auth logout`	Remove stored credentials from ~/.	Auth
`pretense auth status`	Show current authentication status: logged-in user, team, plan tier, and credential expiry.	Auth
`pretense start`	Start the Pretense proxy server.	Utility
`pretense status`	Check whether the proxy is running, which port it is on, mutation count for the current session, and uptime.	Utility
`pretense update`	Upgrade the Pretense CLI to the latest version.	Utility
`pretense logs`	Stream or view the proxy request log.	Utility

Core

The primary scanning and review commands. These are the tools you use every day.

pretense scan

Scan files or directories for secrets and high-risk identifiers. Outputs a severity-sorted report. Does not mutate or modify any files.

Usage

pretense scan [path] [options]

Example

pretense scan ./src --severity high

Options

--format <fmt>Output format: text (default), json, csv, sarif

--severity <lvl>Minimum severity: low, medium, high, critical

--output <file>Write results to file instead of stdout

--no-colorDisable colored terminal output

pretense scan ci

Full repository scan designed for CI pipelines. Scans all tracked files and produces machine-readable output.

Usage

pretense scan ci [options]

Example

pretense scan ci --format sarif --output results.sarif --exit-code

Options

--format <fmt>Output format: text, json, sarif, csv

--output <file>Write results to file

--severity <lvl>Minimum severity threshold

--exit-codeExit with code 2 if findings match threshold

--baseline <file>Ignore findings present in a baseline SARIF file

pretense review

AI-powered code review that checks for security issues, mutation coverage gaps, and best practices.

Usage

pretense review [path] [options]

Example

pretense review ./src/auth.ts --json

Options

--plainPlain text output

--jsonStructured JSON output for automation

--agentRun in agent mode for interactive review sessions

Setup

Commands for initializing projects, installing hooks, and managing configuration.

pretense init

Initialize Pretense in the current repository. Creates .pretense/ with config, scans the codebase, and builds an initial mutation profile.

Usage

pretense init [options]

Example

cd my-project && pretense init

Options

--forceOverwrite existing .pretense/ config if present

--skip-scanSkip the initial codebase scan

pretense install

Install Pretense git hooks into the current repository. Sets up automatic scanning on every commit or push.

Usage

pretense install --mode <pre-commit|pre-push>

Example

pretense install --mode pre-commit

Options

--mode <mode>Hook type: pre-commit (recommended) or pre-push

pretense config list

Print the current resolved configuration as a table.

Usage

pretense config list

Example

pretense config list

Auth

Commands for authenticating with Pretense Cloud (team dashboard, audit sync, remote policies).

pretense auth login

Authenticate with Pretense Cloud. Opens a browser for OAuth or accepts an API key via --key.

Usage

pretense auth login [options]

Example

pretense auth login

Options

--key <api-key>Authenticate with an API key instead of browser OAuth

pretense auth logout

Remove stored credentials from ~/.pretense/credentials.json.

Usage

pretense auth logout

Example

pretense auth logout

pretense auth status

Show current authentication status: logged-in user, team, plan tier, and credential expiry.

Usage

pretense auth status

Example

pretense auth status

Utility

Maintenance and informational commands.

pretense start

Start the Pretense proxy server. Routes LLM API traffic through the mutation engine.

Usage

pretense start [options]

Example

pretense start --port 9339

Options

--port <n>Port to listen on (default: 9339)

--backgroundRun proxy as a background daemon

--watchReload config on .pretense.yaml changes

pretense status

Check whether the proxy is running, which port it is on, mutation count for the current session, and uptime.

Usage

pretense status

Example

pretense status

pretense update

Upgrade the Pretense CLI to the latest version. Preserves your configuration and audit database.

Usage

pretense update [options]

Example

pretense update

pretense logs

Stream or view the proxy request log.

Usage

pretense logs [options]

Example

pretense logs --tail 50

Options

--tail <n>Show last N log entries (default: 100)

--followStream new log entries in real-time

--format <fmt>Output format: text (default), json, ndjson

Global flags

These flags work with every command and must be placed before the subcommand name.

Flag	Short	Description
`--verbose`	`-v`	Enable verbose logging.
`--config <path>`	`-c`	Path to a config file other than .pretense.yaml.
`--api-key <key>`	`-k`	Pretense API key. Can also be set via PRETENSE_API_KEY env var.
`--json`	`-j`	Output all command results as machine-readable JSON.
`--no-color`	`--`	Disable colored terminal output.

Exit codes

All commands follow standard Unix exit code conventions.

Code	Meaning
`0`	Success — command completed without errors
`1`	General error — see stderr for details
`2`	Secrets detected — scan found findings above threshold
`3`	Config error — .pretense.yaml is missing or invalid
`4`	Proxy already running — pretense start called while proxy is active
`5`	Auth error — invalid or missing API key for cloud features