CLI Commands Reference

Complete reference for every command, flag, and environment variable in henkaipan-cli. Companion to the CLI overview.

Global flags

These flags are available on every subcommand.

henkaipan scan run

Trigger a scan via POST /api/v1/scans/external.

Usage:
  henkaipan scan run [flags]

Flags:
      --repo-url string        Repository URL (auto-creates the project on first run)
      --project-id string      UUID of an existing project (mutually exclusive with --repo-url)
      --scanners string        Comma-separated scanners or pack (all, sast, sca, secrets, vuln, containers) (default "all")
      --branch string          Git branch to scan (defaults to the project's default branch)
      --auto-create-project    Auto-create the project from --repo-url when --project-id is empty (default true)
      --wait                   Block until all scans reach a terminal state
      --poll-interval int      Seconds between status polls when --wait is set (default 15)
      --fail-on string         Exit 1 if any finding meets or exceeds this severity

Behavior

• Exactly one of --repo-url or --project-id is required. They are mutually exclusive.
• When --project-id is empty and --auto-create-project is true (default), the project is created from the repo URL on first scan — mirrors henkaipan-action's auto-create-project input.
• --wait blocks until every triggered scan reaches completed or failed, then exits non-zero if --fail-on severity is met or any scan failed. Polling respects --poll-interval (default 15s) and times out at 20 minutes.

Examples

# Auto-create project from repo URL, default scanners
henkaipan scan run --repo-url https://github.com/owner/repo

# Specific project + scanners + branch, wait and fail on high
henkaipan scan run --project-id <uuid> --scanners semgrep,trivy --branch main \
    --wait --fail-on high

henkaipan scan status <scan-id>

Read GET /api/v1/scans/{id}/status (one-shot by default, or poll with --wait).

Usage:
  henkaipan scan status <scan-id> [flags]

Args:
  <scan-id>                   UUID of the scan to query

Flags:
      --wait               Block until the scan reaches a terminal state
      --poll-interval int  Seconds between status polls (default 15)
      --fail-on string     Exit 1 if any finding meets or exceeds this severity

Examples

henkaipan scan status <scan-id>
henkaipan scan status <scan-id> --wait --fail-on high

henkaipan findings list

Query GET /api/findings with filters and pagination.

Usage:
  henkaipan findings list [flags]

Flags:
      --severity string    Filter by severity (critical|high|medium|low)
      --status string      Filter by finding status (e.g. open, fixed)
      --scanner string     Filter by scanner name (semgrep, trivy, gitleaks, grype, nuclei)
      --project-id string  Scope to a project UUID
      --page int           Page number (default 1)
      --page-size int      Results per page (default 50)
      --fail-on string     Exit 1 if any finding meets or exceeds this severity

Examples

henkaipan findings list --severity high --project-id <uuid>
henkaipan findings list --scanner semgrep --page 2 --page-size 50
henkaipan findings list --fail-on critical

henkaipan findings export

Stream GET /api/findings/export to stdout or to a file.

Usage:
  henkaipan findings export [flags]

Flags:
      --format string      Export format: json or csv (default json)
      --severity string    Filter by severity
      --status string      Filter by finding status
      --scanner string     Filter by scanner name
      --project-id string  Scope to a project UUID
      --output string      Write to this file instead of stdout

Examples

henkaipan findings export --format json --severity critical
henkaipan findings export --format csv --project-id <uuid> --output findings.csv

Severity weights

--fail-on uses the same severity weights as henkaipan-action:

--fail-on high means "fail if any finding is high or critical" — it is not "fail if all findings are high". This matches gh, golangci-lint, and the action's contract.

Exit codes

The CLI does not yet emit distinct codes per failure mode — this is a known limitation tracked for the next minor release.