Docs›Core›CLI reference

CLI reference

Every command the shipped binary accepts, and what it returns.

Commands

Some take a path, a few a subcommand of their own.

bash

pretense scan .
pretense scan ci

Set up

Command	What it does
`init`	Scan the codebase and write pretense.yaml
`quickstart`	init, git hooks and next steps in one go
`login`	Authenticate. Takes --key, or opens a browser
`logout`	Remove stored credentials
`auth`	login, logout, status, and licence for air-gap
`install`	Install the pre-commit and pre-push git hooks
`ignore`	Add patterns to .pretenseignore
`config`	list, get and set configuration values

Every day

Command	What it does
`scan`	Scan a file, a directory or a git range
`review`	Show the mutations that would be applied
`mutate`	Swap the secrets in 1 file for synthetics
`reverse`	Restore a mutated file from its map

The proxy

Command	What it does
`run`	Run an AI tool through the proxy. Alias: with
`start`	Start the proxy
`stop`	Stop the running proxy
`status`	Whether it is running, and on which port

You rarely start the proxy by hand. run starts one, points the tool at it, and stops the one it started.

Records and plan

Command	What it does
`audit`	Recent mutation entries, filterable by framework
`logs`	Recent audit log entries
`usage`	Plan usage against limits for the period
`credits`	Remaining mutation budget. Alias: tokens
`policy`	List and inspect compliance frameworks
`completion`	Print the tab-completion script for a shell
`version`	Print the version. Same as --version
`upgrade`	Compare plans and change your subscription

There is no self-update command

upgrade is about your subscription, not your binary. To move to a newer version, run the install command from the Quickstart again.

Flags

Flags belong to the command they follow. These are the ones you will reach for.

Flag	On	What it does
`--json`	scan, review, audit, logs, status, usage, credits	Machine-readable output
`--policy <preset>`	scan, init	Apply a compliance preset
`--severity <lvl>`	scan	Minimum severity to report
`-l, --limit <n>`	audit, logs	How many entries to show
`-p, --port <port>`	start, run	Preferred port. Default 9339
`--provider <name>`	run	Force anthropic, openai or google

Mutating a single file

-i writes the result back to the file instead of printing it. --map <path> chooses where the reversal map is written, and where reverse reads it from.

bash

pretense mutate -i src/config.ts
pretense reverse src/config.ts -i --map ~/.pretense/maps/<hash>.json

mutate prints the second line for you, with the real path filled in.

Keep the map

With no --map given, an in-place mutation writes one into ~/.pretense/maps/ and prints the exact command that restores the file. reverse asks for that map and will not run without it, which is what stops a mutated file becoming an unrecoverable one. See How it works.

Exit codes

The 2 scanning forms report findings with different codes. A gate that checks for the wrong one passes while secrets sit in the diff.

Command	Clean	Findings
`scan`	`0`	`1`
`scan ci`	`0`	`2`

Gate on the first. scan ci reads only what git tracks, so it exits 0 with an untracked secret still on disk — Automation has the detail.

Known limits

mutate takes a file, not a directory.
A directory scan skips .md files. Naming one directly does scan it, so a secret pasted into a README passes a repository scan and fails a scan of that file.

Was this page helpful?