CLI Reference

CLI Reference

Run commands from an audit-repo checkout or replace scripts/... with the absolute path to the installed Skill.

Collect repository signals

python scripts/collect_repo_signals.py [path] [options]

path defaults to the current directory.

Option	Default	Meaning
--format markdown|json	markdown	Select human-readable or structured output.
--scan-mode filesystem|git-visible|tracked	filesystem	Choose broad filesystem discovery or a Git-derived file set.
--include-path GLOB	none	Include matching root-relative paths; repeat for multiple globs.
--exclude-path GLOB	none	Exclude matching root-relative paths; repeat for multiple globs. Exclusions win.
--scope-id ID	none	Record a project-qualified logical scope assertion for equivalent checkouts at different roots.
--max-files N	50000	Stop after scanning N files; must be positive.
--exclude-dir NAME	none	Ignore this single directory name anywhere in the tree, case-insensitively. Repeat for multiple names.
--large-file-mib MIB	5	Set the positive, finite large-file threshold; files equal to the threshold count.
--output PATH	stdout	Create or overwrite a UTF-8 output file.

Examples:

# Human-readable inventory
python scripts/collect_repo_signals.py /path/to/repo --format markdown

# Stable, package-scoped JSON snapshot for CI
python scripts/collect_repo_signals.py /path/to/repo \
  --scan-mode tracked \
  --include-path "packages/api/*" \
  --exclude-path "packages/api/generated/*" \
  --scope-id acme/monorepo:api-package \
  --format json \
  --exclude-dir fixtures-large \
  --large-file-mib 10 \
  --output snapshot.json

Scan modes

Mode	Files considered	Best suited to
filesystem	Reachable files present below the root, including ignored and untracked files, subject to exclusions.	Broad local discovery, especially accidentally created sensitive-looking files.
git-visible	Tracked files plus non-ignored untracked files reported by Git.	Working-tree review without build artifacts and other ignored files.
tracked	Tracked files only, including ignored files that were explicitly force-added to Git.	Stable CI baselines and repeatable release comparisons.

git-visible and tracked require a Git working tree. git-visible follows the checkout's effective Git ignore rules, including repository and configured ignore sources; it does not merely parse one .gitignore file. tracked deliberately omits every untracked file, even when it looks sensitive.

Every mode applies the built-in directory exclusions listed below and skips file and directory symlinks plus Windows reparse points, including NTFS junctions. An inclusion does not override a built-in or explicit exclusion.

Path and directory scope

--include-path and --exclude-path use case-sensitive Python fnmatchcase semantics against each complete, root-relative POSIX path. In particular, * can match /; quote globs so the shell does not expand them. Exclusions win when a path matches both lists. Patterns must be non-empty relative POSIX globs: absolute paths, drive prefixes, backslashes, NUL/control characters, and .. path segments are rejected.

--scope-id is a 1-200-character logical name with non-whitespace content and no control characters. It is unset by default and does not change which files are scanned. Use the same project-qualified ID only when two different absolute checkout roots truly represent the same repository and logical scope. Do not reuse IDs across projects or packages. The legacy implicit value repository is treated as unset and cannot authorize a cross-root comparison.

When a valid option value itself begins with -, join it to the option with = so the command-line parser cannot reinterpret it as another option. For example, use --scope-id=-release, '--include-path=-generated/*', or --exclude-dir=--cache. Quote glob tokens so the shell does not expand them. For a positional repository path beginning with -, terminate option parsing first, for example python scripts/collect_repo_signals.py --format=json -- -repository. v1.10.1 introduced joined --option=value forwarding in the runner and composite Action and placed the positional repository path after --; v1.10.2 through v1.10.7 retain that behavior.

The composite Action's include-paths, exclude-paths, and exclude-dirs inputs accept either LF- or CRLF-separated values. The Action removes exactly one terminal CR from each line before forwarding joined arguments. It does not strip embedded CR or other control characters; the shared collection preflight still rejects those values before output side effects.

The collector reports:

• Git branch or detached commit and tracked-file count when bounded local Git metadata is available. Worktree cleanliness is intentionally unknown; the collector does not invoke git status.
• Scan completeness, including scan_incomplete_reasons when enumeration fails, a path becomes unavailable during analysis, or a Git-enumerated path is missing from the working tree.
• Language counts, canonically cased manifests and lockfiles (including Python/Pipenv, JavaScript/Bun, .NET/NuGet, SwiftPM, JVM, Go, Rust, Ruby, and PHP), documentation, licenses, Django-style tests.py, case-accurate .NET *Tests.cs, canonical CI entry points, action references, dependency-update configuration, containers, and environment examples. GitHub Action uses extraction ignores script/description block contents and accepts only unambiguous workflow values.
• Configured tools, package scripts, Make targets, contribution/security policies, and CODEOWNERS.
• Comment-style work markers, up to 20 largest files above the threshold, and sensitive-looking filenames.

Default directory exclusions are .git, .hg, .svn, .cache, .idea, .next, .tox, .venv, .vscode, __pycache__, build, coverage, dist, node_modules, target, vendor, and venv. They apply in all scan modes.

--exclude-dir is a case-insensitive directory-name match, not a glob or relative path. Each value must be one non-empty name. Whitespace-only values, /, \, the exact dot segments . and .., and control characters are rejected. For example, --exclude-dir generated skips every directory named generated below the scan root, while the valid leading-hyphen name --cache must be passed as --exclude-dir=--cache.

Reporting uses bounded heuristics: language totals are file counts rather than lines of code; work markers are counted only in non-test, non-sensitive files with known text suffixes and size at most 1,000,000 bytes; Markdown large-file output contains at most the 20 largest matches while JSON retains the complete scanned inventory; and example lists may be capped. Treat absence from a capped human-readable list as uncertainty, not proof of absence.

Collector exit codes:

Code	Meaning
0	Collection completed.
2	Invalid path/option, unavailable required Git working tree, or output write failure.

Run collection and comparison together

python scripts/check_repo.py [path] [options]

The runner defaults to --scan-mode tracked and --output-dir audit-repo-results. It accepts the collector's scope, filter, limit, exclusion, and large-file options. Without a baseline it creates snapshot.json and report.md. With --baseline BASELINE it also creates comparison.json and comparison.sarif; add --baseline-sha256 EXPECTED, --fail-on-attention, and --require-comparable for an exact-byte content pin plus CI gates. Either gate without a baseline, or a digest without a baseline, is invalid configuration and returns 2 before managed outputs change.

Option	Default
path	Current directory
--output-dir	audit-repo-results
--baseline	None
--baseline-sha256	None; optional exact-byte SHA-256 for --baseline
--scan-mode	tracked
--scope-id	Unset
--include-path, --exclude-path, --exclude-dir	None; repeatable
--max-files	50000
--large-file-mib	5
--fail-on-attention, --require-comparable	Off

python scripts/check_repo.py /path/to/repo \
  --scan-mode tracked \
  --scope-id acme/widget:whole-repository \
  --baseline /trusted/approved.json \
  --baseline-sha256 "$EXPECTED_BASELINE_SHA256" \
  --output-dir /outside/repo/audit-results \
  --fail-on-attention \
  --require-comparable

--baseline-sha256 accepts exactly 64 hexadecimal characters, with uppercase or lowercase allowed and no prefix, surrounding whitespace, or checksum filename. It hashes the raw file bytes, so JSON formatting, byte-order marks, trailing newlines, and LF/CRLF conversion affect the value. External comparison snapshots and runner baselines must resolve to regular files no larger than 64 MiB; a symbolic link is accepted when its opened target is an in-limit regular file. The reader opens each input once, validates the opened target with fstat, and reads at most 64 MiB plus one detection byte through the same file descriptor. The runner applies the optional digest and strict UTF-8 JSON parser to that same captured byte sequence, with unique object keys required at every nesting level. A matching digest pins the bytes but cannot remove duplicate-key ambiguity. Obtain the expected digest independently from maintainer-controlled configuration or a separately verified artifact; calculating it from the same untrusted baseline immediately before the run adds no trust.

The runner preflights its four managed output paths before a run. It never recursively removes a directory occupying one of those paths and does not partially delete sibling artifacts when a collision exists. A malformed digest, digest mismatch, unreadable baseline, or invalid baseline returns 2 before an output directory is created, managed output is cleared, or Action output is appended. It rejects baseline or GitHub-output aliases and rejects output paths that traverse a symbolic link or Windows reparse point anywhere inside the scanned root or its entire containing Git worktree, including monorepo siblings.

v1.10.1 introduced shared collection-option and target validation in the runner and collector. A non-positive file limit, non-finite/non-positive or overflowing large-file threshold, invalid include/exclude glob, invalid scope ID, missing scan root, or Git-based scan of a non-Git directory returns 2 before the runner allocates its default Action temporary directory, creates or clears managed output, or appends GitHub Action output.

v1.10.2 extends that same side-effect-free preflight to excluded directory names. The collector also rejects an invalid name before overwriting its requested output file. Prior reports and Action state therefore survive these preflight rejections. This guarantee is intentionally limited to preflight: a later collector or output failure can occur after stale managed files have been cleared.

v1.10.3 rejects duplicate JSON object keys at every nesting level. Standalone comparison inputs, runner baselines, and captured collector stdout all use the same strict parser. A duplicate-key runner baseline returns 2 before output creation or cleanup, default temporary-directory allocation, or GitHub Action output. A matching baseline digest does not bypass this validation.

v1.10.4 applies the regular-file and 64 MiB bound before any external snapshot is parsed. For runner baselines, opened-target validation, bounded capture, optional digest verification, and strict parsing all complete before output creation or cleanup, default temporary-directory allocation, or GitHub Action output. Diagnostic context derived from untrusted snapshot paths, scan roots, and managed-output paths is ASCII-escaped onto one line and limited to 500 characters.

After successful preflight and managed-output cleanup, the runner captures the collector's JSON stdout as bytes, validates those exact bytes as a supported strict UTF-8 snapshot, and writes the same bytes to snapshot.json. Because collector stdout is parsed after cleanup, a duplicate-key or other invalid collector result is a later collector failure and is outside the prior-output preservation guarantee. A nonzero collector status is normalized to runner exit code 2, distinct from exit code 1 policy-gate results. Exit code 0 means requested gates passed, 1 means attention or comparability failed a requested gate, and 2 means invalid input or execution/output failure. The digest added in v1.10.0 remains optional; valid, unchanged baselines retain the same comparison semantics and results when it is omitted, and the baseline is still read and frozen before collection.

v1.10.2 keeps snapshot schema 1 and scan semantics 3. Cross-version comparison remains valid only when both snapshots record identical settings that v1.10.2 still accepts; review and replace any newly rejected legacy directory exclusion before collecting a new approved baseline and current snapshot with the same accepted setting.

v1.10.3 also keeps snapshot schema 1 and scan semantics 3. Unambiguous snapshots remain compatible under those accepted settings-and-scope rules. Any stored snapshot containing duplicate object keys is invalid and must be regenerated from a reviewed, trusted source before comparison.

v1.10.4 keeps snapshot schema 1 and scan semantics 3. Previously valid, unambiguous regular-file snapshots no larger than 64 MiB remain compatible under the same accepted settings-and-scope rules; larger or non-regular stored inputs must be replaced before comparison.

v1.10.5 keeps snapshot schema 1 and scan semantics 3. LF/CRLF Action input normalization and repository-contract hardening do not change valid snapshot signals, so compatibility remains governed by the same accepted settings-and-scope rules and the v1.10.4 external-file boundary.

v1.10.6 also keeps snapshot schema 1 and scan semantics 3. Its YAML anchor, alias, and tag hardening changes repository contract validation rather than collection signals, so existing snapshots remain compatible when their recorded settings and logical scopes match.

v1.10.7 keeps snapshot schema 1 and scan semantics 3. Its additional fail-closed handling for a flow-style explicit mapping key that resolves to uses, together with immutable Release enforcement, changes repository and release contracts rather than collected signals; snapshot compatibility remains governed by matching recorded settings and logical scopes.

Compare JSON snapshots

python scripts/compare_repo_signals.py before.json after.json [options]

Option	Default	Meaning
--format markdown|json|sarif	markdown	Select human-readable, structured, or SARIF 2.1.0 output.
--output PATH	stdout	Create or overwrite a UTF-8 output file.
--fail-on-attention	off	Return exit code 1 when high-confidence attention items exist.
--require-comparable	off	Return exit code 1 when the snapshots have comparison limitations.

Exit codes:

Code	Meaning
0	Comparison completed; this remains the default even when attention items exist.
1	A requested gate failed: attention items exist with --fail-on-attention, or limitations exist with --require-comparable.
2	A snapshot is missing, malformed, unsupported, or output cannot be written.

See Snapshot Comparison for comparability rules and attention conditions.

SARIF output maps high-confidence attention items to warning results and comparison limitations to note results. These entries are repository-change signals that require verification, not confirmed vulnerabilities. The comparer still accepts JSON collector snapshots only; SARIF is an output format, not a snapshot input format.

Build a release archive

This maintainer command packages only runtime files and writes a matching SHA-256 file:

python scripts/package_skill.py --version v1.10.7 --output-dir dist

The version must resemble v1.2.3 or 1.2.3. GitHub Releases verify exact tag/default-branch provenance before running repository code, then test Python 3.10 and 3.14 on Linux, Windows, and macOS before packaging. Publishing fails closed on an existing draft, accepts only the exact archive and checksum assets, downloads and compares both assets, and rechecks provenance. Regular CI additionally covers every Python minor version from 3.10 through 3.14.

Safety boundaries

• Collection is read-only except for a path explicitly supplied with --output.
• Comparison reads only the two supplied JSON files and optionally writes --output.
• Put generated snapshots outside the scan root (for example, in $RUNNER_TEMP) so they do not affect filesystem inventory. Git worktree cleanliness remains deliberately unknown.
• Sensitive-looking file contents are skipped entirely.
• Sensitive-path detection covers common environment files, credentials, private keys, key stores, cloud and developer CLI credential locations, and Terraform state; these are inventory signals rather than automatic vulnerabilities.
• Ordinary UTF-8-compatible text files up to 1 MB may be read for comment-style work markers.
• Project dependencies are not installed and project commands are not run by the standalone collector.
• Git-aware modes choose an absolute Git executable outside both the lexical and resolved checkout boundaries, verify containment by filesystem identity, disable hooks and filesystem monitors, clear inherited GIT_* targeting/configuration variables, and suppress prompts and pagers.
• Run collection against a quiescent checkout. The scan uses multiple filesystem operations and is not an atomic snapshot; a concurrent writer can replace a path after an earlier identity, link, or size check. Use an isolated checkout when concurrent untrusted writers cannot be excluded.