HenKaiPan CLI (henkaipan-cli)

The henkaipan CLI is the standalone, client-agnostic companion to the dyallab/henkaipan-action GitHub Action. It is a single static Go binary that talks to the same HenKaiPan REST API under the same X-API-Key authentication — but you can run it from any shell, script, CI step, or agent prompt that can execute a binary.

Use this guide if you want to drive HenKaiPan from a context where the GitHub Action is not a good fit: arbitrary CI runners, cron jobs, local terminal sessions, ad-hoc security audits, or scripted bulk operations.

When to use the CLI vs the action

Use the GitHub Action Use the CLI
on: pull_request with auto PR comments GitLab CI, Jenkins, CircleCI, Drone, Buildkite, or any runner that can install a binary
$GITHUB_STEP_SUMMARY rendering Cron / scheduled scans from a server with no GitHub context
Pin to a published Docker image Local terminal exploration and debugging
One-click reuse of GITHUB_TOKEN Long-running scripts that need API access from arbitrary hosts
Piping findings into jq, custom dashboards, or downstream tools

The CLI is intentionally a thin orchestration layer over the same REST endpoints the action calls. There is no parallel implementation to drift.

Install

# Recommended: install via Go
go install github.com/dyallab/henkaipan-cli/cmd/henkaipan@latest

# Or pin to a tag
go install github.com/dyallab/henkaipan-cli/cmd/henkaipan@v0.1.0

Or grab a prebuilt binary from the Releases page. Binaries are published for linux / darwin / windows × amd64 / arm64.

Verify the install:

henkaipan version
# henkaipan-cli/0.1.0

Configuration

Configuration resolves in this order (highest priority first):

  1. CLI flags (--api-url, --api-key, ...)
  2. Environment variables (HENKAIPAN_*)
  3. Built-in defaults
Flag Env var Default
--api-url HENKAIPAN_API_URL https://henkaipan.dyallab.com.ar
--api-key HENKAIPAN_API_KEY (none — required)
--cf-access-client-id HENKAIPAN_CF_ACCESS_CLIENT_ID (none)
--cf-access-client-secret HENKAIPAN_CF_ACCESS_CLIENT_SECRET (none)
--output HENKAIPAN_OUTPUT table
--timeout HENKAIPAN_TIMEOUT 60

Security: the API key is wrapped in a typed value that masks itself on every format verb (%s, %v, String()). If you ever see *** in debug output, that is by design.

Quickstart

export HENKAIPAN_API_URL=https://henkaipan.dyallab.com.ar
export HENKAIPAN_API_KEY=hkp_xxxxxxxxxxxxxxxxxxxx

# Trigger a scan and wait, failing on high+ findings
henkaipan scan run \
  --repo-url https://github.com/owner/repo \
  --scanners all \
  --branch main \
  --wait \
  --fail-on high

# Query a scan in flight
henkaipan scan status <scan-id> --wait

# List findings
henkaipan findings list --severity high --project-id <uuid>

# Export for an external tool
henkaipan findings export --format json --severity critical --output findings.json

For the full command reference, see the CLI Commands reference.

CI integration examples

Generic Linux runner

- name: Run HenKaiPan security scan
  env:
    HENKAIPAN_API_URL: ${{ secrets.HENKAIPAN_API_URL }}
    HENKAIPAN_API_KEY: ${{ secrets.HENKAIPAN_API_KEY }}
  run: |
    henkaipan scan run \
      --repo-url "$CI_REPOSITORY_URL" \
      --branch  "$CI_COMMIT_REF_NAME" \
      --wait \
      --fail-on high

Behind Cloudflare Access

- name: Run HenKaiPan security scan
  env:
    HENKAIPAN_API_URL: ${{ secrets.HENKAIPAN_API_URL }}
    HENKAIPAN_API_KEY: ${{ secrets.HENKAIPAN_API_KEY }}
    HENKAIPAN_CF_ACCESS_CLIENT_ID: ${{ secrets.CF_CLIENT_ID }}
    HENKAIPAN_CF_ACCESS_CLIENT_SECRET: ${{ secrets.CF_CLIENT_SECRET }}
  run: henkaipan scan run --repo-url "$CI_REPOSITORY_URL" --wait --fail-on high

Troubleshooting

Symptom Cause Fix
received HTML (HTTP 403) ... likely a proxy/firewall challenge Reverse proxy (often Cloudflare) is returning a challenge page Add a WAF skip rule for /api/v1/*, or pass --cf-access-client-id / --cf-access-client-secret for Cloudflare Access
api: HTTP 401 from <url> Missing or invalid API key Confirm HENKAIPAN_API_KEY is set and the token has not been revoked
api: HTTP 403 ... token is not scoped to this project Project-scoped token used against a different project Generate a new unscoped token, or scope it to the correct project
Scan times out at 20 minutes Default max wait reached Use --scanners semgrep,trivy (smaller set), or scale up the HenKaiPan worker pool

Related