Command Line¶

Use the PostQ CLI for repeatable workstation and automated scans. This page explains how to run a scan and configure the command options in 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.

Without a license, the CLI supports source-file scans only:

postq-code-scanner-cli --file /work/source/src/App.java --output /work/reports

Repeat --file for up to five unique regular files in one invocation. Folder and project scans require a beta license.

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
`--file`, `-f <path>`	Source file to scan; repeatable up to five unique files without a license	Use for no-license evaluation
`--language`, `-l <lang>`	Programming-language hint	Automatic or current configuration
`--skip-folder <folder>`	Project-relative folder to exclude from OpenGrep scanning; repeatable	Use for generated report, build, dependency, or vendor folders inside the scanned tree
`--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 supported OS-specific names on `PATH`
`-about`, `--about`	Print product, build, beta validity, and safe license information, then exit	Does not scan or generate reports
`--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>.

--skip-folder also accepts --skip-folder=<folder>. Values are normalized as folders inside the scanned project and must not traverse outside it. Use this when reports or generated build output must live under the source tree:

postq-code-scanner-cli \
  --project /work/source \
  --output /work/source/reports/postq/scans/latest \
  --skip-folder reports \
  --skip-folder build

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

Show the installed product/build version and current license applicability:

postq-code-scanner-cli -about --license-file /secure/postq.lic

About is read-only. It reports valid; not activated when the license is eligible but no prior status check or scan has started the trial.

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, typescript, and rust. Review Languages and Libraries Supported for qualified language and library coverage before using results for program decisions.

Generated reports¶

A successful scan writes the 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`	Supporting findings and parameter 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`	CycloneDX 1.7 cryptographic inventory interoperability output
`results.sarif`	Security-tool interoperability output

Do not use a source directory as the report directory. See Report File Reference to choose the right file for review or integration.

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.