Command Line¶

The PostQ CLI is the authoritative command interface for repeatable workstation and automated scans. This page contains both the operating guidance and complete public option reference for version 0.1.0-beta.

The CLI prints scan progress, OpenGrep diagnostics, finding statistics, operation-group details, and generated artifact locations. Use it for local evaluation, scripts, managed build agents, and troubleshooting outside an IDE.

Before you begin¶

Complete the Native CLI Quick Start.
Install Java and OpenGrep and confirm that both commands are available.
Obtain the CLI release archive and an issued postq.lic.
Keep the source, report output, and license in separate approved locations.

Use absolute project, output, OpenGrep, Java, and license paths in automation. This prevents a changed working directory from selecting the wrong source or writing reports to an unexpected path.

Command syntax¶

postq-code-scanner-cli [OPTIONS]

Run postq-code-scanner-cli --help to display the options packaged with the installed build. The installed help output is authoritative if it differs from this beta manual.

Run a project scan¶

postq-code-scanner-cli \
  --project /work/source \
  --output /work/reports \
  --name payments-service \
  --version 3.1.0 \
  --language java \
  --license-file /secure/postq.lic

--version identifies the scanned application version. It does not select or print the PostQ CLI version.

Scan options¶

Option	Purpose	Default or guidance
`--project`, `-p <path>`	Source file or project directory to scan	Always set an explicit path for customer scans
`--language`, `-l <lang>`	Programming-language hint	Automatic or current configuration
`--results`, `-r <path>`	Existing OpenGrep results JSON to process	`output/opengrep-results/opengrep-results.json`
`--output`, `-o <path>`	Generated report directory	`output`
`--name`, `-n <name>`	Project name stored in reports	`scanned-application`
`--version`, `-v <version>`	Project version stored in reports	`1.0.0`
`--java-path <command>`	Java executable command or absolute path	`POSTQ_JAVA_PATH`, then `java` on `PATH`
`--opengrep-path <command>`	OpenGrep command or absolute executable path	`POSTQ_OPENGREP_PATH`, then `opengrep` on `PATH`
`--help`, `-h`	Print installed CLI usage and exit	Not applicable

The Java and OpenGrep path options also accept --java-path=<command> and --opengrep-path=<command>.

License options¶

Option	Purpose
`--license-file <path>`	Use an offline `postq.lic` file for activation
`--license-status`	Validate activation and print status without scanning
`--license-content <json>`	Pass license content from an approved host integration; interactive users and scripts should prefer `--license-file`

When --license-file is not set, the scanner checks POSTQ_LICENSE_PATH, then postq.lic in the working directory or beside the installed scanner JAR. An explicit protected path is recommended. Do not place license JSON directly in shell history, logs, source control, or report artifacts.

Check activation without scanning:

postq-code-scanner-cli \
  --license-file /secure/postq.lic \
  --license-status

Select a language¶

Language selection is a hint for a source tree that contains a specific language:

postq-code-scanner-cli \
  --project /work/source/backend \
  --language java \
  --license-file /secure/postq.lic

Supported values are java, c, cpp, csharp, go, python, javascript, and typescript. Review Supported Languages for qualified language and library coverage before using results for program decisions.

Reprocess an existing OpenGrep result¶

--results runs the deterministic PostQ report pipeline against a previously generated OpenGrep JSON file:

postq-code-scanner-cli \
  --project /work/source \
  --results /work/evidence/opengrep-results.json \
  --output /work/reports/reprocessed \
  --name payments-service-reprocessed \
  --license-file /secure/postq.lic

Keep the original source and raw result together. Reprocessing old evidence does not make it equivalent to a new source scan and cannot discover source changes made after that evidence was generated.

Generated reports¶

A successful scan writes the deterministic report set to --output:

Artifact	Primary purpose
`manifest.json`	Scan identity, inputs, artifacts, and warnings
`opengrep-results/opengrep-results.json`	Raw OpenGrep evidence
`findings.json`	Normalized scanner evidence
`crypto-functions.json`	Crypto API and parameter review
`operation-groups.json`	Grouped crypto lifecycles
`crypto-finding-assessment.json`	Repository-level readiness assessment
`cbom.json`	Cryptographic inventory interoperability output
`results.sarif`	Security-tool interoperability output

Do not use a source directory as the report directory. See Report Artifact Reference for report contracts and intended consumers.

Automation and exit behavior¶

Exit code	Meaning
`0`	Configuration, scanning, and report generation succeeded
`1`	Scanner execution failed
`2`	Command configuration is invalid
`3`	License validation failed

OpenGrep uses its own exit 1 to indicate findings. PostQ treats that engine result as a successful scan and continues report generation. A PostQ finding does not cause a nonzero process exit by itself; apply organizational acceptance policy to deterministic report fields in a separate step.

See Exit Codes before defining CI failure policy.

Common command issues¶

Symptom	Action
Java or OpenGrep is not found	Confirm `PATH`, or set `--java-path` and `--opengrep-path` explicitly
License validation fails	Run `--license-status` with the same protected license path
The wrong project is scanned	Set an absolute `--project` path and verify `manifest.json`
Reports appear in the wrong location	Set an absolute `--output` path outside the source tree
Findings differ from an earlier scan	Confirm source revision, PostQ version, language, and rule inputs

For deployment-specific behavior, see Container Runner and CI/CD.