CLI overview¶

Primary command:

trustcheck inspect <project>

Core flags¶

--version: inspect a specific release instead of the latest project version
--expected-repo: require repository evidence to match an expected GitHub or GitLab repository
--format text|json: choose human-readable text or machine-readable JSON
--verbose: include per-file provenance, digest, publisher, and note fields in text output
--with-deps: inspect direct runtime dependencies and summarize the highest-risk dependency
--with-transitive-deps: inspect direct and transitive runtime dependencies recursively
--strict: apply the built-in strict policy
--policy default|strict|internal-metadata: evaluate a built-in policy profile
--policy-file PATH: load policy settings from a JSON file

Policy override flags¶

--require-verified-provenance none|all
--allow-metadata-only
--disallow-metadata-only
--require-expected-repo-match
--fail-on-vulnerability ignore|any
--fail-on-risk-severity none|medium|high

Network and diagnostics flags¶

--config-file PATH: load network settings from a JSON config file
--timeout FLOAT: set request timeout in seconds
--retries INT: set transient retry count
--backoff FLOAT: set retry backoff factor
--cache-dir PATH: persist cached PyPI responses for repeated runs
--offline: use cached responses only
--debug: emit structured debug logs and print tracebacks for operational failures
--log-format text|json: choose debug log format for --debug

Examples¶

Inspect a package:

trustcheck inspect requests

Run with strict policy:

trustcheck inspect sampleproject --version 4.0.0 --strict

Inspect the package and its direct dependency set:

trustcheck inspect sampleproject --version 4.0.0 --with-deps

Inspect the full transitive dependency tree:

trustcheck inspect sampleproject --version 4.0.0 --with-transitive-deps

When dependency inspection is enabled, trustcheck reads requires_dist metadata, resolves compatible dependency versions from PyPI, and adds a dependency summary to the report. --with-deps stops at the immediate dependencies of the inspected package. --with-transitive-deps continues recursively through nested dependencies. The top-level result can be escalated if an inspected dependency is review-required or high-risk.

For top-level package analysis, a complete absence of published provenance is typically surfaced as review-required. Stronger negative evidence such as failed verification, inconsistent provenance, or known vulnerabilities still drives high-risk outcomes.

Use a custom policy file:

trustcheck inspect sampleproject --version 4.0.0 --policy-file ./policy.json

Use cached responses only:

trustcheck inspect sampleproject --version 4.0.0 --cache-dir .trustcheck-cache --offline