CLI reference

Note: The developer reference is for plugin authors, contributors, and engineers integrating Privateer into automated pipelines. It assumes familiarity with Go, gRPC, and CI/CD tooling. For end-user installation and quickstart, see the Getting started guide.

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

Global flags

pvtr run

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

pvtr run
pvtr run -c config.yml
pvtr run -c config.yml -s my-service        # single service
pvtr run --loglevel debug -w ./results

pvtr install

Downloads a vetted plugin from the Privateer plugin registry and places the binary in the configured binaries path. Takes exactly one argument.

pvtr install pvtr-github-repo-scanner
pvtr install pvtr-github-repo-scanner --binaries-path /opt/pvtr-plugins

For plugins not in the registry, place the binary manually and verify with pvtr list -a.

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 which plugins are referenced by the current config and whether each is present in the binaries path.

pvtr list         # only plugins in config
pvtr list -a      # all binaries in the binaries path

Use pvtr list -a after a manual binary install to confirm Core can discover it before running.

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/

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

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