Skip to main content

Overview

The Cysmiq CLI lets you run policy checks in CI/CD pipelines, query vulnerabilities from scripts or coding agents, update vulnerability workflow state, and install official Cysmiq skills for supported coding agents.

Prerequisites

  • A Cysmiq workspace slug for workspace-scoped commands
  • A Cysmiq API token with access to the workspace
  • A repository connected to Cysmiq for repository-scoped checks, or an application for application-scoped checks
See API keys to generate an API token.

Installation

Install via Homebrew
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, trust the Cysmiq cask and rerun the upgrade:
Trust the Cysmiq cask
brew trust --cask cysmiq/tap/cysmiq
brew upgrade --cask cysmiq
To trust all entries from the Cysmiq tap on managed machines, trust the tap once:
Trust the Cysmiq tap
brew trust cysmiq/tap
Verify the installation:
Verify installation
cysmiq version

Configuration

The CLI reads configuration from these sources, in order of precedence:
  1. Command-line flags: --base-url, --tenant, --token
  2. Environment variables: CYSMIQ_BASE_URL, CYSMIQ_TENANT, CYSMIQ_TOKEN, and other CYSMIQ_ prefixed options
  3. Config file: ~/.cysmiq/config.yaml

Required settings

SettingFlagEnvironment variableDescription
Base URL--base-urlCYSMIQ_BASE_URLBase URL (e.g., https://app.cysmiq.com)
Tenant--tenantCYSMIQ_TENANTWorkspace slug
Token--tokenCYSMIQ_TOKENAPI token

Config file

Create ~/.cysmiq/config.yaml to avoid passing common flags repeatedly:
~/.cysmiq/config.yaml
base-url: https://app.cysmiq.com
tenant: my-workspace
# token: set via CYSMIQ_TOKEN for security
Use hyphenated option names in the config file:
~/.cysmiq/config.yaml
repo: my-org/my-repo
ref: main
poll-interval: 5s
wait-timeout: 15m
Avoid storing API tokens in the config file. Use CYSMIQ_TOKEN instead.

Commands

List Tenants, Repositories, and Applications

Use the resource list commands to find the workspace, repository, or application identifiers you need for automation.
List accessible workspaces
cysmiq tenants list
List repositories in a workspace
cysmiq repos list --tenant my-workspace
List applications in a workspace
cysmiq applications list --tenant my-workspace
tenants list is not workspace-scoped, so it requires only --base-url and --token. repos list and applications list require a workspace through --tenant or CYSMIQ_TENANT. Options:
CommandImportant flagsOutput
tenants list--limit, --cursortable, json
repos list--org, --source, --application, --limit, --cursortable, json
applications list--limit, --cursortable, json
Use --json or --output json when another script or coding agent will consume the result. These commands require the matching API key scopes: tenants:read for tenants list, repositories:read for repos list, and applications:read for applications list. Existing keys keep the scopes selected when they were created, so older keys may need to be recreated with the new scopes.

Run Checks

Use cysmiq check to run a policy check and set the exit code based on vulnerabilities found. Use this in CI/CD pipelines to gate deployments.
Basic check
cysmiq check --repo my-org/my-repo --ref main
The check command requires either a repository or an application. In repository mode, provide --ref for the latest known scan on a branch or tag, or --sha for a specific commit. When only --repo is available and inference cannot find a ref or SHA, the CLI uses the repository default branch. When --sha is provided in repository mode, check waits for the scan to reach a terminal state before evaluating the result. Use --poll-interval and --wait-timeout to control how often the CLI checks scan status and how long it waits. Application mode evaluates vulnerabilities across the application’s repositories and does not wait on one scan. Exit codes:
  • 0: Check passed
  • 2: Usage error, invalid flag value, missing required setting, or canceled command
  • 3: Conflict, such as a stale --status-version
  • 4: Unauthorized API token
  • 5: Forbidden API request or token without the required ability
  • 6: Resource not found
  • 7: Scan unavailable for the provided SHA
  • 8: API validation error
  • 9: API or transport error, including failed scan terminal states and wait timeouts after a scan was observed
  • 10: Policy failure because the configured threshold was exceeded
Exit code 1 is reserved for generic shell or runtime failures outside the CLI’s explicit error classes. Options:
FlagEnvironment variableDefaultDescription
--repoCYSMIQ_REPO-Repository identifier or name
--applicationCYSMIQ_APPLICATION-Application prefixed ID or name. Mutually exclusive with --repo
--refCYSMIQ_REF-Git ref, such as a branch or tag
--shaCYSMIQ_SHA-Git commit SHA. When set, check waits for scan completion before evaluating results
--fail-onCYSMIQ_FAIL_ONcritical,highSeverities that cause failure
--max-countCYSMIQ_MAX_COUNT-1Fail if total vulnerabilities exceeds this number. -1 disables the count gate
--poll-intervalCYSMIQ_POLL_INTERVAL5sPolling interval while waiting for a SHA scan to finish. Include a duration unit
--wait-timeoutCYSMIQ_WAIT_TIMEOUT15mMaximum time to wait for a SHA scan to reach a terminal state. Include a duration unit
--limitCYSMIQ_LIMIT50Max vulnerability items to fetch for policy evaluation (1-200)
--severityCYSMIQ_SEVERITYallFilter by severity: critical, high, medium, low
--typeCYSMIQ_TYPEallFilter by type: code, dependency, secret
--confirmedCYSMIQ_CONFIRMEDtrueOnly include confirmed vulnerabilities
--triagedCYSMIQ_TRIAGEDallFilter by triage status: yes or no
--stateCYSMIQ_STATEopenFilter by workflow state: open, fixed, accepted, ignored, rejected, or all
--outputCYSMIQ_OUTPUTsummaryOutput format: summary, table, json
--poll-interval and --wait-timeout must include a duration unit, such as 5s, 30s, 2m, or 15m. Examples:
Fail only on critical vulnerabilities
cysmiq check --repo my-org/my-repo --ref main --fail-on critical
Check a specific commit
cysmiq check --repo my-org/my-repo --sha abc123def456
Check an application
cysmiq check --application app_01hxyz
Check a commit with shorter polling
cysmiq check --repo my-org/my-repo --sha abc123def456 --poll-interval 10s --wait-timeout 5m
Fail if more than 10 vulnerabilities
cysmiq check --repo my-org/my-repo --ref main --max-count 10
JSON output for parsing
cysmiq check --repo my-org/my-repo --ref main --output json

List Vulnerabilities

Use cysmiq vulns list to list vulnerabilities for a repository or application. By default, the CLI returns open, confirmed vulnerabilities and renders them as cards.
List open vulnerabilities
cysmiq vulns list --repo my-org/my-repo
Options:
FlagDefaultDescription
--repo(auto-infer)Repository identifier
--applicationApplication prefixed ID or name. Mutually exclusive with --repo
--ref(auto-infer)Git ref (branch or tag)
--shaGit commit SHA
--severity(all)Filter by severity
--type(all)Filter by type
--confirmedtrueOnly include confirmed vulnerabilities
--triaged(all)Filter by triage status
--stateopenFilter by workflow state: open, fixed, accepted, ignored, rejected, or all
--assigneeFilter by assignee: me, unassigned, user ID, prefixed ID, or email
--limit50Max items per page (1-200)
--allfalseFetch all pages
--cursorPagination cursor
--outputcardsOutput format: summary, cards, table, json
--jsonOutput JSON with optional comma-separated field projection
--colorautoColor mode for human-readable output: auto, always, never
List critical vulnerabilities across all pages
cysmiq vulns list --repo my-org/my-repo --severity critical --all
List vulnerabilities for an application
cysmiq vulns list --application app_01hxyz --output table
List vulnerabilities assigned to you
cysmiq vulns list --repo my-org/my-repo --assignee me
Export as JSON
cysmiq vulns list --repo my-org/my-repo --output json > vulns.json
Export selected JSON fields
cysmiq vulns list --repo my-org/my-repo --json id,title,severity,state,assignee

Get Vulnerability Details

Use cysmiq vulns get to get details for one vulnerability.
Get vulnerability details
cysmiq vulns get VULN-123
Options:
FlagDefaultDescription
--includeInclude extra detail: locations, advisory, secret, call_hierarchies, impacts, human_escalations
--locations-limit50Max locations to fetch when --include locations is used
--outputsummaryOutput format: summary, json
--jsonOutput JSON with optional comma-separated field projection
--colorautoColor mode for summary output: auto, always, never
Get selected fields
cysmiq vulns get VULN-123 --json id,title,severity,state,status_version
Include locations and advisory details
cysmiq vulns get VULN-123 --include locations,advisory

List Vulnerability Locations

Use cysmiq vulns locations to list locations for one vulnerability.
List vulnerability locations
cysmiq vulns locations VULN-123
Options:
FlagDefaultDescription
--scopeallLocation scope: live for only unfixed locations, or all to include fixed locations
--limit50Max locations per page (1-200)
--cursorPagination cursor
--outputcardsOutput format: summary, cards, table, json
--jsonOutput JSON with optional comma-separated field projection
--colorautoColor mode for human-readable output: auto, always, never
List live locations as a table
cysmiq vulns locations VULN-123 --scope live --output table

Assign Vulnerabilities

Use cysmiq vulns assign to assign a vulnerability to a user.
Assign to yourself
cysmiq vulns assign VULN-123 --to me
Options:
FlagDefaultDescription
--toAssignee: me, user ID, prefixed ID, or email
--status-versionExpected vulnerability status version for conflict protection
--outputsummaryOutput format: summary, json
--jsonfalseOutput JSON

Clear Vulnerability Assignees

Use cysmiq vulns unassign to clear the assignee on a vulnerability.
Clear assignee
cysmiq vulns unassign VULN-123
Options:
FlagDefaultDescription
--status-versionExpected vulnerability status version for conflict protection
--outputsummaryOutput format: summary, json
--jsonfalseOutput JSON

Triage Vulnerabilities

Use cysmiq vulns triage to change vulnerability triage state.
Mark a vulnerability as accepted
cysmiq vulns triage VULN-123 --state accepted --reason "Mitigated upstream"
Use ignored when the finding is a false positive. Options:
FlagDefaultDescription
--stateTriage state: open, fixed, accepted, ignored
--reasonTriage reason or comment
--status-versionExpected vulnerability status version for conflict protection
--outputsummaryOutput format: summary, json
--jsonfalseOutput JSON

Summarize Vulnerabilities

Use cysmiq vulns summary to show a vulnerability count summary without listing individual items.
Show vulnerability summary
cysmiq vulns summary --repo my-org/my-repo
Show application vulnerability summary
cysmiq vulns summary --application app_01hxyz
FlagDefaultDescription
--repo(auto-infer)Repository identifier
--applicationApplication prefixed ID or name. Mutually exclusive with --repo
--ref(auto-infer)Git ref (branch or tag)
--shaGit commit SHA
--severity(all)Filter by severity
--type(all)Filter by type
--confirmedtrueOnly include confirmed vulnerabilities
--triaged(all)Filter by triage status
--stateopenFilter by workflow state: open, fixed, accepted, ignored, rejected, or all
--outputsummaryOutput format: summary, json
vulns summary supports the same vulnerability filter fields as vulns list, except pagination, assignee, color, and field projection.

Show Version

Use cysmiq version to print version information.
Show version
cysmiq version

Update CLI

Use cysmiq update to update the CLI to the latest version.
Update to latest
cysmiq update
FlagDescription
--checkCheck for updates without installing
--forceForce update even if installed through a package manager
Check for updates
cysmiq update --check

Agent Skills

Use cysmiq skills to install and manage official Cysmiq skills for coding agents. Skills are local files, so installs and updates preserve local edits unless you explicitly choose an overwrite option. Supported agent IDs:
Agent IDAgentProject install path
codexCodex.codex/skills/cysmiq
claudeClaude Code.claude/skills/cysmiq
agentsPortable agent layout.agents/skills/cysmiq
List the available skills bundle:
List available skills
cysmiq skills list
Install the Cysmiq skill for Codex in the current project:
Install for Codex
cysmiq skills install --agent codex --scope project
Install for every supported agent in the current project:
Install for all supported agents
cysmiq skills install --all-agents --scope project
Check what is installed and whether it is current:
Check installed skills
cysmiq skills status
Diagnose local skill setup:
Diagnose skill setup
cysmiq skills doctor
Update installed skills:
Update installed skills
cysmiq skills update
Remove installed Cysmiq skills:
Remove installed skills
cysmiq skills remove --agent codex --scope project
Scopes:
ScopeDescription
autoDefault for install. Uses project scope when a Git root or agent marker is detected, otherwise uses user scope.
projectInstalls into the current project root. If no project root is detected, the current working directory is used.
userInstalls into the user’s home directory. For Codex, CODEX_HOME is used when set.
Options:
FlagCommandsDescription
--agentinstall, status, update, removeAgent ID to target. Repeat the flag or pass comma-separated values.
--all-agentsinstall, status, update, removeTarget every supported agent.
--scopeinstall, status, update, removeInstall scope: auto, project, or user.
--jsonlist, install, status, doctor, update, removeEmit JSON output.
--sourcelist, install, status, doctor, updateOverride the metadata source with a URL or file:// path.
--versionlist, install, status, doctor, updatePin a specific skills bundle version.
--backupinstall, updateBack up modified files before overwriting them.
--forceinstall, update, removeOverwrite or remove locally modified Cysmiq-owned files.
--yesupdateSkip the update confirmation prompt.
skills update replaces official files that still match the installed version. Locally modified Cysmiq-owned files require --backup or --force. skills remove removes Cysmiq-owned files and leaves unrelated local files in place.

CI/CD Integration

The check, vulns list, and vulns summary commands can auto-infer repository, ref, and SHA from common CI environments. Explicit flags, environment variables, and config file values take precedence over inferred values.
Use --sha in CI/CD gates when you want the CLI to wait for the scan for the current commit before evaluating policy. Use --ref when you want to evaluate the latest scan for a branch or tag.

GitHub Actions

GitHub Actions workflow
name: Security Check

on: [push, pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Cysmiq CLI
        run: |
          curl -fsSL https://github.com/cysmiq/cli-releases/releases/latest/download/cysmiq_linux_amd64.tar.gz | tar -xz
          sudo mv cysmiq /usr/local/bin/

      - name: Run security check
        env:
          CYSMIQ_BASE_URL: https://app.cysmiq.com
          CYSMIQ_TENANT: ${{ vars.CYSMIQ_TENANT }}
          CYSMIQ_TOKEN: ${{ secrets.CYSMIQ_TOKEN }}
          CYSMIQ_REPO: ${{ github.repository }}
          CYSMIQ_SHA: ${{ github.sha }}
        run: cysmiq check

GitLab CI

GitLab CI configuration
security-check:
  image: alpine:latest
  before_script:
    - apk add --no-cache curl
    - curl -fsSL https://github.com/cysmiq/cli-releases/releases/latest/download/cysmiq_linux_amd64.tar.gz | tar -xz
    - mv cysmiq /usr/local/bin/
  script:
    - cysmiq check
  variables:
    CYSMIQ_BASE_URL: https://app.cysmiq.com
    CYSMIQ_TENANT: $CYSMIQ_TENANT
    CYSMIQ_TOKEN: $CYSMIQ_TOKEN
    CYSMIQ_REPO: $CI_PROJECT_PATH
    CYSMIQ_SHA: $CI_COMMIT_SHA

CircleCI

CircleCI configuration
version: 2.1

jobs:
  security-check:
    docker:
      - image: cimg/base:current
    steps:
      - checkout
      - run:
          name: Install Cysmiq CLI
          command: |
            curl -fsSL https://github.com/cysmiq/cli-releases/releases/latest/download/cysmiq_linux_amd64.tar.gz | tar -xz
            sudo mv cysmiq /usr/local/bin/
      - run:
          name: Run security check
          command: cysmiq check --repo "$CIRCLE_PROJECT_USERNAME/$CIRCLE_PROJECT_REPONAME" --sha "$CIRCLE_SHA1"
          environment:
            CYSMIQ_BASE_URL: https://app.cysmiq.com

workflows:
  main:
    jobs:
      - security-check:
          context: cysmiq

Global options

These options apply to all commands:
FlagEnvironment variableDescription
--base-urlCYSMIQ_BASE_URLAPI base URL
--tenantCYSMIQ_TENANTWorkspace slug
--tokenCYSMIQ_TOKENAPI token
--no-inferCYSMIQ_NO_INFERDisable auto-inference from CI environment, local git, and default branch fallback

Shared vulnerability filters

These options apply to check, vulns list, and vulns summary unless a command table states otherwise.
FlagEnvironment variableDescription
--repoCYSMIQ_REPORepository identifier or name
--applicationCYSMIQ_APPLICATIONApplication prefixed ID or name. Mutually exclusive with --repo
--refCYSMIQ_REFGit ref, such as a branch or tag
--shaCYSMIQ_SHAGit commit SHA
--confirmedCYSMIQ_CONFIRMEDOnly confirmed vulnerabilities
--triagedCYSMIQ_TRIAGEDFilter triaged status: yes or no
--stateCYSMIQ_STATEFilter workflow state: open, fixed, accepted, ignored, rejected, or all
--severityCYSMIQ_SEVERITYFilter by severities: critical, high, medium, low
--typeCYSMIQ_TYPEFilter by types: code, dependency, secret
--limitCYSMIQ_LIMITMax items to fetch on commands that expose --limit
When --state is omitted, the CLI sends open. Use --state all to request all workflow states. --ref and --sha require repository mode. Use --application when you want to evaluate or list vulnerabilities across all repositories in an application.