Skip to main content

ZPA CLI

ZPA CLI is the standalone way to analyze PL/SQL and Oracle SQL from a terminal or CI pipeline. It scans project sources, loads the configured checks, and writes findings to the console, JSON, or SonarQube’s Generic Issue Data format.

Download​

Latest release

3.2.0

Full changelog

Usage​

The CLI uses a flat set of options:

  • --sources: [required] Root folder containing the project source files.
  • --files: Optional analysis targets. Multiple values can follow one option or be provided with repeated --files options. Relative paths use --sources as their base. Absolute paths must identify discovered files inside that tree.
  • --syntax-only: Run only ZPA's parser diagnostic check; normal coding rules and project preparation are skipped.
  • --fail-on: Validation threshold: none, any, info, minor, major, critical, blocker, or syntax.
  • --stdin-filename: Virtual source path required when --files includes -.
  • --forms-metadata: Path to the Oracle Forms metadata file.
  • --extensions: Comma-separated extensions to discover. The default is sql,pkg,pks,pkb,fun,pcd,tgg,prc,tpb,trg,typ,tab,tps.
  • --output-format: console (default), json, or sq-generic-issue-import.
  • --output-file: Write JSON or Sonar generic issue output to this path. JSON goes to stdout when omitted.
  • --config: Path to the configuration file. The file format must comply with the provided JSON schema. You can refer to the example zpa-config-example.json for guidance. If the configuration file is not provided, only the rules marked as "activated by default" will be executed.

--sources defines project context. --files optionally restricts the files scanned for diagnostics and included in reports. ZPA prepares semantic declarations from every supported file discovered under --sources, then scans only the selected targets.

# Analyze the full project
zpa-cli --sources .

# Focus analysis on selected files while keeping full project context
zpa-cli --sources . --files src/packages/customer.pkb

# Emit machine-readable results
zpa-cli --sources . --files src/packages/customer.pkb --output-format json

# Return exit code 1 when any diagnostic is found
zpa-cli --sources . --files src/packages/customer.pkb --output-format json --fail-on any

# Report parser diagnostics only
zpa-cli --sources . --files src/packages/customer.pkb --syntax-only

JSON is UTF-8 with schemaVersion: 1, a status (completed or validation_failed), and sorted diagnostics. Each diagnostic includes kind (rule or typed parser syntax), project-relative file, range, rule, severity, and message. Lines are one-based; columns are zero-based; end positions are exclusive. Coordinates unavailable from ZPA are null. Structured output on stdout contains only JSON; operational messages go to stderr.

Exit codes are 0 when analysis completes without meeting the selected threshold, 1 when the validation threshold is met, and 2 for invalid invocation/configuration or an internal execution error. The default --fail-on is none, preserving success for existing batch runs that find issues. --syntax-only defaults to --fail-on syntax; an explicit --fail-on overrides that default.

Stdin is supported with --files - and a virtual --stdin-filename inside the source tree. Its extension must be included in --extensions. It can be combined with distinct filesystem targets. Stdin content is analyzed under that filename, while project preparation uses disk files only. Stdin does not replace a matching file in project context; project overlays are not supported.

The sq-generic-issue-import format continues to generate a file in Sonar's Generic Issue Data format for SonarCloud or SonarQube (as an alternative to the dedicated ZPA Plugin for SonarQube).

Example​

Run an analysis and write SonarQube Generic Issue Data:

./zpa-cli/bin/zpa-cli --sources . --output-file zpa-issues.json --output-format sq-generic-issue-import