Use the CLI in CI/CD

Last updated: August 9, 2026

Use this article when you want a CI/CD job to evaluate Cysmiq scan results and pass or fail based on vulnerability policy.

What to set up first

  • Connect the repository: Cysmiq must already have access to the repository and scan results.

  • Create an API key: use a personal or workspace API key with the scopes needed to read scans, vulnerabilities, applications, or tenants for your workflow.

  • Install the CLI in CI: install cysmiq in the job before running checks.

  • Store secrets safely: put the API token in your CI secret store and expose it as CYSMIQ_TOKEN.

Install and update with Homebrew

On macOS, install the official CLI with brew install --cask cysmiq/tap/cysmiq.

Homebrew 6 may require explicit trust for existing installations from non-official taps during upgrades. If Homebrew reports that cysmiq/tap/cysmiq is from an untrusted tap, run:

brew trust --cask cysmiq/tap/cysmiq
brew upgrade --cask cysmiq

For managed machines where the whole Cysmiq tap should be trusted, run brew trust cysmiq/tap.

Recommended CI flow

  • Set CYSMIQ_BASE_URL, CYSMIQ_TENANT, and CYSMIQ_TOKEN.

  • For repository checks, set CYSMIQ_REPO. Use CYSMIQ_SHA to wait for the current commit scan, or CYSMIQ_REF to evaluate a branch or tag.

  • For application checks, set CYSMIQ_APPLICATION. Application checks evaluate vulnerabilities across repositories in the application and do not wait on one scan.

  • Run cysmiq check and let the exit code control the CI result.

Useful commands

  • cysmiq version: verify the installed CLI.

  • cysmiq check --repo my-org/my-repo --ref main: evaluate the latest known scan for a branch or tag.

  • cysmiq check --repo my-org/my-repo --sha abc123def456: wait for a specific commit scan and evaluate it.

  • cysmiq check --application app_01hxyz: evaluate vulnerabilities across repositories in an application.

  • cysmiq check --repo my-org/my-repo --ref main --fail-on critical: fail only on critical vulnerabilities.

  • cysmiq check --repo my-org/my-repo --ref main --max-count 10: fail if more than 10 matching vulnerabilities are found.

  • cysmiq check --repo my-org/my-repo --ref main --output json: emit JSON for pipeline parsing.

  • Existing API keys keep their original scopes. Recreate older keys when a workflow needs newly added scopes such as applications:read or tenants:read.

Exit codes to know

  • 0: check passed.

  • 10: policy failure because the configured threshold was exceeded.

  • 4 or 5: authentication or authorization problem.

  • 6 or 7: repository, ref, SHA, or scan was not available.

  • 9: API, transport, failed terminal scan, or wait-timeout problem.

Canonical docs

For the maintained workflow and command reference, see Use the CLI in CI/CD, CLI reference, API keys, and Connect a VCS.

Contact support if

  • Homebrew refuses to install or upgrade the CLI because the Cysmiq tap is untrusted.

  • The CLI cannot authenticate even though the token is active.

  • A CI check cannot find the expected repository, ref, SHA, or scan.

  • cysmiq check fails but the Cysmiq UI result is unclear or appears different.

  • You need help choosing the right token type, scopes, command, or CI configuration.