Reference/CLI reference

CLI reference

Edit on GitHub ↗

Every pvtr subcommand, its flags, and usage examples.

The Privateer CLI is the pvtr binary. Every subcommand accepts the global flags below, plus its own options.

Global flags

FlagShortDefaultDescription
--binaries-path-b$HOME/.privateer/binDirectory where plugins are installed and resolved
--config-c./config.yml, then ~/.privateer/config.ymlConfig file path (JSON or YAML)
--loglevel-lerrorVerbosity: trace, debug, info, warn, error, off
--autoinstallfalseBefore a run, install any plugin the config requests that is not yet installed
--hub-urlhttps://hub.grc.storegrc.store hub base URL; the registry host is discovered from it
--help-hShow help

pvtr run

Resolves each target’s plugin from the binaries path, launches it as a gRPC subprocess, collects results, and writes output. Registers handlers for SIGINT and SIGTERM; an interrupted run exits with the abort code, distinct from a validation failure.

pvtr run
pvtr run -c config.yml
pvtr run -c config.yml --target my-target   # single target
pvtr run --loglevel debug -w ./results -o json
FlagShortDefaultDescription
--target-s, --service(all targets)Run a single named target from the config. -s and --service are legacy aliases
--test-suites-tdefaultNamed test suite(s) to execute
--output-oyamlResults format; see output formats
--writetrueWrite result files to disk
--write-directory-wevaluation_resultsOutput directory for result files
--include-payloadfalseInclude the raw evaluated payload in the results (large; useful for tracing)
--concurrency1Plugins to run in parallel; 0 means one per CPU
--silentfalseSuppress all non-essential terminal output

Output formats

ValueResults fileContents
yaml (default)<target>.yamlPrivateer results with one Gemara Evaluation Log per suite
json<target>.jsonSame as yaml, as JSON
sarif<target>.sarifSARIF 2.1.0, for the GitHub Security tab
gemara<target>.yamlA list of native Gemara Evaluation Logs

File locations and structure are in the output schema.

Exit codes

CodeMeaning
0Everything passed
1The run completed and at least one suite is Failed, Needs Review or Unknown
2Aborted (signal)
3Internal error in pvtr or the plugin, including a plugin that rejects its config (for example a missing variable or policy)
4Bad config or flags, including a policy catalog the plugin does not provide
5No assessments ran, for example a config that requests no plugins

A run over several plugins exits with the most severe code among them. An applicability value the plugin does not recognise is not caught: every requirement is Not Applicable and the run exits 0 (see policy). 1 is a successful run from the plugin’s point of view; read the log, not just the code.

pvtr install

Pulls a plugin from grc.store as a signed OCI artifact, verifies its signature, signer identity and digests, and only then writes it to the binaries path. Takes the plugin’s <namespace>/<plugin_id> coordinate, optionally pinned with @<version> (default: latest). A bare name without a namespace is rejected. The coordinate is also the value of plugin in the config.

pvtr install openssf/github-repo
pvtr install openssf/[email protected]
pvtr install openssf/github-repo --binaries-path /opt/pvtr-plugins
pvtr install --local ./my-plugin       # installs as local/my-plugin
pvtr install --from-config -c config.yml
FlagDescription
--local <path>Install a local plugin binary. It is installed as local/<binary name>
--from-configInstall every plugin the active config references that is not yet installed

openssf/github-repo is the GitHub repo scanner’s coordinate; ossf/pvtr-github-repo-scanner is its source repository, not something pvtr install accepts.

A plugin that declares its control catalogs as grc.store coordinates (via AddCatalogs in the SDK) has each catalog fetched, signature-verified, and cached under the binaries path at install time, at <binaries-path>/catalogs/<namespace>/<id>/<version>.yaml. pvtr run reads that cache and never contacts grc.store, so once a plugin is installed no further network access to grc.store is required. A published catalog version is immutable, so a cached file is never re-fetched. Plugins may instead continue to vendor their catalogs in the binary (via AddReferenceCatalogs); those need no catalog cache at all.

pvtr list

Reports plugins, whether each is installed, and whether the current config requests it.

pvtr list                # installed, plus any requested by the config
pvtr list --installed    # installed only, with versions
pvtr list -a             # also plugins published on grc.store
pvtr list --installable  # published on grc.store and not yet installed

-a/--all, --installed and --installable are mutually exclusive. Run pvtr list --installed after pvtr install --local to confirm Core can discover the plugin.

pvtr env

Prints a full snapshot of the runtime environment. Useful for debugging environment mismatches in CI.

pvtr env    # also accessible as: pvtr info

Output includes: binary path, config file path and whether it was found, plugins directory, discovered plugin names, version, commit hash, build time, Go version, and OS/architecture.

pvtr version

pvtr version            # prints version string only, e.g. 0.1.0
pvtr version --verbose  # adds git commit hash and build timestamp

A version of edge means the binary was built from source without a release tag. Do not use edge builds in production pipelines.

pvtr generate-plugin

Generates a plugin scaffold from a Gemara Layer 2 YAML control catalog. The output is a compilable Go module with placeholder implementations for data collection, evaluation plans, and assessment steps.

pvtr generate-plugin \
  --source-path ~/path/to/catalog.yaml \
  --service-name "MyService" \
  --organization "my-github-org" \
  --output-dir my-plugin/
FlagShortDefaultDescription
--source-path-pPath to the Gemara Layer 2 catalog YAML
--service-name-nService name used in generated identifiers
--organization-gGitHub organization for the plugin module path
--output-dir-ogenerated-plugin/Output directory
--local-templatesUse a local templates directory instead of fetching latest

The generated plugin compiles as emitted, with every requirement bound to a NotImplemented placeholder step. See Build your first plugin.

Generated layout

my-plugin/
  main.go                          # orchestrator wiring; Publisher and License are set here
  go.mod                           # pins privateer-sdk and go-gemara; no go.sum, so run go mod tidy first
  data/
    data_collection.go             # Payload and Loader
    catalogs/catalog_<id>_<ver>.yaml  # the source catalog, vendored in the binary
  evaluation_plans/
    evaluation_plans.go            # TypedStep, and Suite_<id>: requirement id -> step chain
    reusable_steps/steps.go        # NotImplemented placeholder
  example-config.yml
  Makefile
  README.md
  TESTING.md
  .gitignore
  .goreleaser.yaml                 # release build; pvtr publish reads its dist directory
  .github/workflows/               # build, lint, CodeQL, release, and grc.store publish workflows

Running generate-plugin over an existing plugin overwrites every file.

pvtr benchmark

Runs a compiled plugin once with timing instrumentation and prints where the time went: payload retrieval (the loader) separately from each assessment step.

go build -o my-plugin .
pvtr benchmark ./my-plugin --target my-target -c config.yml
pvtr benchmark ./my-plugin --target my-target --payload-only
pvtr benchmark ./my-plugin --target my-target --json > bench.json

Takes the path to a plugin binary, not an installed coordinate. The target must exist in the config so the plugin has its vars and policy.

FlagShortDefaultDescription
--target-s, --serviceTarget from the config to evaluate (required). -s and --service are legacy aliases
--payload-onlyfalseTime only the loader and skip the assessment steps
--jsonfalsePrint the report as JSON, for comparing runs in CI
--write-directory-wa temporary directoryDirectory for the run’s results and report

pvtr publish

Publishes a plugin to grc.store. It reads a GoReleaser dist directory, checks that every binary is a Privateer plugin, assembles a multi-platform OCI index, pushes it to the registry the hub advertises, signs it with Sigstore keyless signing, and asks the hub to ingest and verify it.

goreleaser build --clean
pvtr login
pvtr publish

The coordinate, license and catalogs come from the built binary, not from flags: the coordinate is <Publisher>/<PluginName> from the plugin’s orchestrator, and License must be a valid SPDX expression. Publishing to the hub requires ownership of the namespace.

Two identities are involved. The push uses the grc.store token from pvtr login, or PVTR_TOKEN in CI. The signature uses a separate OIDC identity trusted by public Sigstore: the GitHub Actions OIDC token in CI, or a second browser sign-in on a workstation. Build your first plugin walks through both.

FlagDefaultDescription
--distdistGoReleaser dist directory (holds artifacts.json and metadata.json)
--registryPush to another registry for testing, with scheme (for example http://localhost:5000). Anonymous; skips signing and the hub sync
--no-syncfalsePush only: skip signing and the hub sync

pvtr login and pvtr logout

pvtr login signs in to grc.store so pvtr publish can push. It runs an OAuth 2.0 device-authorization flow against the sign-in server the hub advertises: it prints a URL and a code to enter in a browser. The hub is the global --hub-url, or PVTR_HUB_URL. Credentials are stored in ${XDG_DATA_HOME:-~/.local/share}/pvtr/credentials.json.

pvtr logout forgets the stored credentials.

pvtr login
pvtr logout

In CI, do not log in; set PVTR_TOKEN instead. Installing plugins needs no login.

pvtr completion

Generates shell autocompletion scripts.

pvtr completion bash
pvtr completion zsh
pvtr completion fish
pvtr completion powershell
pvtr completion --help    # shell-specific install instructions