CLI reference

Every command.A clear next move.

This is the practical reference for repyy. Start with a local scan, save JSON when you need to process results later, and use the exit code to automate a review gate.

Read-only Targets are treated as dataOffline Local scans need no networkExplicit Remote fetch and intelligence updates are opt in

Check the installed interface

repyy help prints the top-level command summary. repyy version prints the scanner and ruleset versions, which you need when selecting a matching Docker image.

Command shape

repyy scan [options] <path-or-git-url>...
repyy report [options] <report.json|->
repyy rules validate <rules.yaml>
repyy rules check
repyy rules list [--format terminal|json]
repyy rules explain <rule-id> [--format terminal|json]
repyy intel status [--format terminal|json]
repyy intel update
repyy intel rollback
repyy version

Flags can appear before or after targets. A value flag accepts either a space or an equals sign, for example --format html and--format=html. Boolean flags such as --include-dependencies do not take a value.

Run a first scan

Run this from the directory that contains your checkout. Replace the path with a folder you are allowed to inspect. repyy does not import, build, test, or execute target code.

Local folder

repyy scan ./project

The default report is terminal output. Use an absolute path when the target is elsewhere, and quote paths containing spaces:

Path with spaces

repyy scan '/Users/me/Code/Take home assignment'

Remote targets are Git URLs. Host mode needs Git; HTTPS private remotes use the matching provider token in the process environment. Keep credentials out of URLs.

Remote repository

repyy scan https://github.com/org/repo

Targets and target files

Pass one or more local directories and Git URLs. Command-line targets are processed first. Add --file to append a UTF-8 text list, one path or URL per line; blank lines and lines whose first non-whitespace character is # are ignored.

# Review queue
./assignment-a
https://github.com/org/assignment-b

Several targets

repyy scan ./repo-a ./repo-b --file targets.txt --jobs 4

--jobs controls concurrent repositories, from 1 through 128, with a default of 4. Docker uses no more than four effective workers. Remote history is shallow by default: use --history 20 or --history all when earlier commits matter.

Inspect history

repyy scan https://github.com/org/repo --history 20

Host-mode remote checkouts are temporary and removed after the scan. Add--keep-workdir to retain one for follow-up review. This option is rejected with Docker.

All `scan` flags

Defaults apply when a flag is omitted. A hit limit or read error produces incomplete coverage; do not treat an incomplete result as clean.

--file PATHAppend targets from a text file. One path or URL per line; blank and # comment lines are skipped.--format FORMATterminal (default), json, sarif, or html.--output PATHWrite the selected report to a file instead of stdout. Example: --output review.html.--jobs NConcurrent repositories, 1–128; default 4. Docker caps effective concurrency at 4.--config PATHLoad a reviewed version-1 YAML file with custom rules and suppressions. See configuration.--include-dependenciesInclude dependency and cache trees such as node_modules, .venv, vendor, target, andPods, which are skipped by default.--history N|allRemote Git history depth; default 1. all requests full history.--keep-workdirKeep a host-mode remote checkout. Unsupported with --sandbox docker.--sandbox host|dockerhost is default. Docker requires a running daemon and the verified release-matched image. vm and auto are unavailable.--fail-on LEVELExit 1 at or above low, medium, high, or critical; default high.--timeout DURATIONPer-repository limit; default 10m. Use positive durations such as 30s, 20m, or 1h.--max-files NMaximum files per repository; default 100000. --max-file-size BYTESMaximum bytes read from one file; default 52428800 (50 MiB). --detail MODEsummary, review (default), or all controls displayed detail. --progress MODEauto (default), plain, or quiet. JSON and SARIF default to quiet progress.--color MODEauto (default), always, or never. NO_COLOR is honored in auto mode.--min-severity LEVELDisplay low, medium, high, or critical and above; default low. Presentation only.--min-confidence LEVELDisplay low, medium, or high confidence and above; default low. Presentation only.--group-by FIELDGroup terminal output by severity (default), file, or rule.

Display filters do not hide findings from the verdict or change the exit policy. Use--fail-on for policy.

Copyable scan recipes

01 · HTML

Save a private review

Self-contained and easy to open locally.

repyy scan ./checkout --format html --output review.html

02 · JSON

Archive structured evidence

Keep stable identifiers and coverage for later rendering.

repyy scan ./checkout --format json --output scan.json

03 · CI

Write SARIF quietly

Fail at medium and keep logs readable.

repyy scan . --format sarif --output repyy.sarif --fail-on medium --progress quiet --color never

04 · Docker

Use the sandbox

Pull and verify the matching release image first.

repyy scan ./repo --sandbox docker --format html --output report.html

05 · Broad review

Include dependencies

Show every finding grouped by file.

repyy scan . --include-dependencies --detail all --group-by file

Choose a report format

terminalPrioritized human review--format terminal

jsonAutomation and archival input--format json

sarifCode-scanning integrations--format sarif

htmlSelf-contained offline review--format html

Without --output, the selected report goes to stdout. HTML and JSON are most useful as saved files. SARIF is a portable interchange format for code-scanning tools.

Reports from v0.5.1 record scan_mode (host or docker) per repository. HTML shows unknown for legacy reports without recorded mode, or uses an existing Docker isolation record. Local scans do not invoke Git to discover a commit; their commit is marked unavailable. Remote reports retain the fetched revision.

Report privacy

Reports redact matched source lines, but paths and behavior can still reveal repository structure. Keep report files private. HTML needs no server and can be opened directly in a current browser.

Render a saved JSON report

repyy report reads a repyy JSON scan without rescanning source. Its input is one JSON file or - for standard input. The default output is HTML; it also accepts terminal and SARIF. It does not produce JSON because the input is already JSON.

Render HTML

repyy report scan.json --format html --output review.html

Render from stdin

cat scan.json | repyy report - --format sarif --output results.sarif

Report options are --format terminal|html|sarif, --output PATH, --detail summary|review|all,--color auto|always|never, --min-severity, --min-confidence, and --group-by severity|file|rule. Filters affect presentation only. Input must be valid repyy JSON no larger than 64 MiB; repyy rejects a verdict that conflicts with findings or coverage. Rendering returns code 2 for incomplete coverage, 1 for a high or critical finding, and0 otherwise. Invalid input returns 3.

Only render JSON from a scan you trust. Verdict validation catches contradictions inside a report, but JSON is not signed and cannot reveal findings removed before someone shares it.

Rules commands

repyy rules validate FILEValidate trusted YAML, custom rules, regexes, and suppressions without scanning.

repyy rules checkShow built-in ruleset and intelligence snapshot status offline.

repyy rules listList active indicators; add --format json for machine-readable output.

repyy rules catalogList built-in behavioral rules; add --format json for the versioned catalog. Browse the reference.

repyy rules explain RULE-IDShow rationale, scope, legitimate-use context, and review guidance; supports --format json.

Explain a finding rule

repyy rules explain EXEC-001

Intelligence commands

The scanner ships with an offline intelligence snapshot. Scans never update it automatically.

repyy intel statusShow active snapshot version, age, and source; supports --format json.

repyy intel updateExplicitly download and verify a signed public snapshot.

repyy intel rollbackRestore the previous verified cached snapshot.

Inspect then update

repyy intel status repyy intel update

Exit codes and verdicts

Use the process exit code in scripts, then inspect the report for evidence. A zero exit is not proof that a repository is safe.

0No finding reached --fail-on and no runtime scan error occurred. Lower-severity findings may still exist.

1A finding reached the configured --fail-on threshold.

2A target was not fully scanned or another runtime error occurred. In a mixed scan, this takes priority over code 1.

3The command, flag, report input, or configuration was invalid; Docker preflight errors stop before scanning.

In a multi-target run, successful targets remain visible when another target is incomplete. Treat SCAN INCOMPLETE as unresolved coverage. repyy report uses the default high threshold when rendering saved scans.

Troubleshooting

Command not foundOpen a new terminal after installation. Check command -v repyy or where.exe repyy.

Remote URL failsCheck git --version, the URL, and the matching provider token. Never put credentials in the URL.

Docker preflight failsStart Docker, pull the digest from the matching release, and verify its signature. repyy does not fall back to host mode.

Incomplete scanRead the target error and check permissions, timeout, file/archive limits, and sandbox mounts before rerunning.

Need trusted rules or suppressions? Follow theconfiguration walkthrough ↗. For installation and sandbox setup, return to thedocumentation home ↗.

Status and build identity

Human reports use conservative decision wording while schema-1 verdict values remain compatible. Version output now includes commit, builder, source, Go version and build date. Checkout cleanup failures preserve findings and select incomplete status.Read the status mapping andbuild identity guide.