Pretense is a local AI proxy that protects your code before it ever reaches an LLM. It intercepts API calls, mutates proprietary identifiers (variables, functions, classes) into safe synthetics, forwards the mutated code to the model, then reverses the mutation in the response. Your real code never leaves your machine.

How does rate limiting work?

Tokens are only burned when you send a prompt to the LLM. Each mutation counts against your 7-day rolling period quota: 1,000 mutations for Free, 100,000 for Pro, unlimited for Enterprise. The counter resets every 7 days from your first mutation, not on a calendar date.

Does Pretense use any cloud LLMs?

No. Pretense runs 100% locally on your machine. It acts as a transparent proxy between your editor (Claude Code, Cursor, Copilot, or any OpenAI-compatible CLI) and the upstream LLM API. The mutation and reversal happen in-process before any network request leaves your device.

Where is the data stored?

All data stays local. SQLite database on your machine stores the mutation map (original to mutated identifier pairs) so responses can be reversed byte-exactly. No telemetry, no cloud sync, no phoning home. Your mutation history is yours.

How do I roll this out across my team?

Pretense runs as a background proxy on port 9339. Point each developer's editor to localhost:9339 instead of the upstream API. Enterprise plans include team management with per-member audit logs, invite flows, and role-based access. See the /docs/deploy page for install scripts.

How do I install Pretense?

One line, any platform: curl -fsSL https://pretense.ai/install | sh. Works on macOS, Linux, and Windows (WSL). The installer drops a single binary, starts the proxy on port 9339, and prints the config snippet for your editor.

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

Installation

Recommended

curl -fsSL https://pretense.ai/install.sh | sh

See the full install guide for system requirements and uninstall instructions.

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 scan commit-range`	Scan only files changed between two commits.	Core
`pretense scan pre-commit`	Scan only git-staged files.	Core
`pretense scan pre-push`	Scan all commits in the push range.	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 config get`	Get the value of a single config field.	Setup
`pretense config set`	Update a single config value in .	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 usage`	Show usage statistics: total mutations, scans, blocked secrets, and audit log size for the current project.	Utility
`pretense logs`	Stream or view the proxy request log.	Utility
`pretense ignore`	Add a file, directory, or pattern to .	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 to report: 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. Use --exit-code to fail the build on findings.

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 (default: text)

--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 scan commit-range

Scan only files changed between two commits. Useful for incremental CI on pull requests.

Usage

pretense scan commit-range <from>..<to> [options]

Example

pretense scan commit-range origin/main..HEAD --exit-code

Options

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

--exit-codeExit with code 2 if secrets found in changed files

pretense scan pre-commit

Scan only git-staged files. Called automatically by the pre-commit hook. Fast because it only checks files you are about to commit.

Usage

pretense scan pre-commit

Example

pretense scan pre-commit

pretense scan pre-push

Scan all commits in the push range. Called automatically by the pre-push hook.

Usage

pretense scan pre-push

Example

pretense scan pre-push

pretense review

AI-powered code review that checks for security issues, mutation coverage gaps, and best practices. Can output structured results for automation.

Usage

pretense review [path] [options]

Example

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

Options

--plainPlain text output (no colors or formatting)

--jsonStructured JSON output for automation

--agentRun in agent mode for interactive review sessions

--prompt-onlyPrint the review prompt without executing it

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. Shows the merged result of .pretense.yaml, environment variable overrides, and built-in defaults.

Usage

pretense config list

Example

pretense config list

pretense config get

Get the value of a single config field. Accepts dot-notation keys.

Usage

pretense config get <key>

Example

pretense config get proxy.port

pretense config set

Update a single config value in .pretense.yaml. The proxy picks up the change on the next request.

Usage

pretense config set <key> <value>

Example

pretense config set proxy.port 9340

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. Stores credentials in ~/.pretense/credentials.json.

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. Does not revoke the API key on the server.

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

Options

--version <v>Install a specific version (e.g., --version 0.6.2)

pretense usage

Show usage statistics: total mutations, scans, blocked secrets, and audit log size for the current project.

Usage

pretense usage

Example

pretense usage

pretense logs

Stream or view the proxy request log. Shows every intercepted request with timestamp, provider, mutation count, and latency.

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

pretense ignore

Add a file, directory, or pattern to .pretenseignore. Ignored paths are skipped during scans.

Usage

pretense ignore <pattern>

Example

pretense ignore "*.test.ts"

Global flags

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

Flag	Short	Description
`--verbose`	`-v`	Enable verbose logging. Shows every intercepted token, hash computation, and proxy decision.
`--config <path>`	`-c`	Path to a config file other than .pretense.yaml. Useful for testing alternate configurations.
`--api-key <key>`	`-k`	Pretense API key for cloud features (audit sync, team dashboard). Can also be set via PRETENSE_API_KEY env var.
`--json`	`-j`	Output all command results as machine-readable JSON. Useful for scripting and CI pipelines.
`--no-color`	`--`	Disable colored terminal output. Automatically detected when stdout is not a TTY.

Exit codes

All commands follow standard Unix exit code conventions. Use these in shell scripts and CI pipelines.

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