Command-line reference

Synopsis

swiftproof init [--repo PATH] [--language go|typescript|javascript|python]
swiftproof lint [--base main] [--head HEAD] [--ci] [flags]
swiftproof review [--base main] [--reviewer=false] [--ci] [flags]
swiftproof review [flags] BASE..HEAD
swiftproof report [--input .swiftproof/confidence-report.json] [--out DIR]
swiftproof version

• lint analyzes a change statically. It never executes repository code and never calls an AI provider.
• review adds sandboxed checks in Docker and, when a model is configured, an AI investigation.
• Only committed files are analyzed; uncommitted edits and untracked files are ignored.
• Reports are written to .swiftproof/ in the repository by default. Console output stays short.
• Flags accept one or two dashes (-ci or --ci). Booleans are set with --ci or --ci=true and cleared with --checks=false. A value is given as --base main or --base=main.
• Run swiftproof <command> --help for the flags of a command.

Choosing revisions

Both sides of a comparison resolve to immutable commit IDs, recorded in the report. Renames, deletions, binary files and file type changes are handled.

A range may appear before or after the flags: swiftproof review main..HEAD --ci and swiftproof review --ci main..HEAD are equivalent. At most one range is accepted. Any revision Git understands works: branches, tags, origin/main, HEAD~3 or a commit ID. CI jobs need enough history to resolve the base (for example fetch-depth: 0).

The trusted policy is always read from the base branch, never from the change under review, so a pull request cannot loosen its own rules.

swiftproof lint

Static analysis of a change: Git comparison, risk signals and a report. No Docker, no provider call, no execution of repository code. Safe to run on untrusted branches.

swiftproof lint HEAD~1..HEAD                 # the last commit
swiftproof lint --base origin/main --ci      # this branch as a pull request, for CI
swiftproof lint --base main --format json    # JSON report only

swiftproof review

Everything lint does, plus the policy's test, typecheck, build and coverage commands in disposable Docker containers, plus an AI investigation when a model is configured. Requires Docker with Linux containers and a preloaded sandbox.image.

swiftproof review --base main --ci                        # typical pull request run
swiftproof review HEAD~1..HEAD --reviewer=false           # checks only, no provider
swiftproof review --base main --checks=false --reviewer=false   # static only, like lint
swiftproof review --base main --intent-file PR.md         # give acceptance criteria

Checks run in the order test, typecheck, build, then coverage. Each container is non-root, has a read-only root and source mount, no added capabilities, no network by default, and the CPU, memory, PID and time limits of the sandbox policy. The Docker socket, your working checkout and API keys are never mounted. If Docker or the image is missing, the run ends with exit 4; nothing ever falls back to your host.

swiftproof init

Write a starter .swiftproof.json for the project. It refuses to overwrite an existing file. Review the commands and image, then commit the file to your base branch.

swiftproof report

Re-render a saved JSON report, for example to regenerate Markdown in CI. Nothing is re-run, and re-rendering does not authenticate the evidence it contains.

swiftproof version and help

Exit codes

No code means "approved". A 0 says that nothing was reproduced, not that the change is correct.

Environment variables

The AI provider belongs to the deployment rather than to the repository, so these settings can come from the environment. Nothing else can: the image, commands, budgets and sensitive paths are always decided by the trusted policy.

A blank variable counts as unset. Key files are read whole with surrounding whitespace stripped, bounded to 8 KiB and must hold a single line. When the reviewer runs, the log names where each value came from, never the value itself. Whoever controls this environment chooses where redacted source is sent: keep it out of jobs that run untrusted fork code.

Output files

Add .swiftproof/ to .gitignore. The console prints one summary: files and lines changed, number of signals and reproduced issues, the focused review surface and changed-line execution.

Risk signals

Signals are reasons to look, not confirmed defects. Go files get syntax-aware analysis; other languages use labelled text heuristics. Signals on the same lines are merged into one review range in the report.

Policy file: .swiftproof.json

The policy decides which commands run, in which image, with which limits, and whether an AI provider is used. It is read from .swiftproof.json on the base branch, or from --config PATH. When there is none, built-in defaults for the detected language apply. Keys you omit take the default values shown below.

The file must be a single JSON object of at most 1 MiB. Unknown keys, unknown command names and duplicate keys are rejected with exit 3, so an older binary rejects a key it does not know.

{
  "version": 1,
  "language": "go",
  "commands": {
    "test": ["go", "test", "./..."],
    "typecheck": ["go", "vet", "./..."],
    "build": ["go", "build", "./..."],
    "generated_test": ["go", "test", "{package}"],
    "coverage": ["go", "test", "-covermode=count", "-coverprofile={coverage_out}", "./..."]
  },
  "sandbox": { "image": "golang:1.26-bookworm", "network": false, "timeout_seconds": 120,
               "max_runtime_seconds": 600, "max_output_bytes": 65536, "memory_mb": 1024, "cpus": 2 },
  "reviewer": { "endpoint": "https://api.openai.com/v1/chat/completions", "model": "",
                "api_key_env": "SWIFTPROOF_API_KEY", "max_iterations": 20, "max_generated_tests": 10,
                "timeout_seconds": 600, "max_input_bytes": 131072 },
  "sensitive_paths": ["**/auth/**", "**/payment*/**", "**/migrations/**", ".github/workflows/**", ".swiftproof.json"]
}

commands

Each command is an argv array, not a shell string: ["npm", "test"], never "npm test". At most 128 arguments; configure only the checks your project provides.

sandbox

reviewer

sensitive_paths

Globs of paths that always raise a high sensitive_path signal when changed. Paths are relative to the repository root with forward slashes; * matches within a path segment and ** across segments. Absolute paths, backslashes and .. are rejected.

Language defaults

Written by swiftproof init, and used when the base branch has no policy. Stock Node.js and Python images do not contain your dependencies: build an image that does and adapt the commands.

AI reviewer

Optional. When a model is configured, review lets it investigate the change with bounded tools: reading redacted files and diffs, searching source, running existing checks, and creating and running temporary tests on base and candidate. It has no shell and no URL fetcher. Its claims stay hypotheses until a test reproduces a difference.

{
  "reviewer": {
    "endpoint": "https://your-provider.example/v1",
    "model": "your-tool-capable-model",
    "api_key_env": "SWIFTPROOF_API_KEY"
  }
}

export SWIFTPROOF_API_KEY=…                       # from your shell or CI secret store
swiftproof review --base main --config .swiftproof.json   # try it before committing
swiftproof review --base main --reviewer=false            # turn it off for one run

• Only the trusted policy, --config or the deployment environment can enable the reviewer; a pull request cannot.
• Bounded, redacted source context is sent to the provider. Masking of secrets is best effort; use a local provider (for example http://127.0.0.1:1234/v1) if source must stay local.
• API keys never enter test containers. lint never calls a provider.
• Provider failures and exhausted budgets keep the deterministic results and mark the investigation incomplete; with --ci that requires human review.