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
Installation
- macOS (Homebrew)
- macOS (Manual)
- Linux (Manual)
- Linux (Package)
Install via Homebrew
cysmiq/tap/cysmiq is from an untrusted tap, trust the Cysmiq cask and rerun the upgrade:Trust the Cysmiq cask
Trust the Cysmiq tap
Verify installation
Configuration
The CLI reads configuration from these sources, in order of precedence:- Command-line flags:
--base-url,--tenant,--token - Environment variables:
CYSMIQ_BASE_URL,CYSMIQ_TENANT,CYSMIQ_TOKEN, and otherCYSMIQ_prefixed options - Config file:
~/.cysmiq/config.yaml
Required settings
| Setting | Flag | Environment variable | Description |
|---|---|---|---|
| Base URL | --base-url | CYSMIQ_BASE_URL | Base URL (e.g., https://app.cysmiq.com) |
| Tenant | --tenant | CYSMIQ_TENANT | Workspace slug |
| Token | --token | CYSMIQ_TOKEN | API token |
Config file
Create~/.cysmiq/config.yaml to avoid passing common flags repeatedly:
~/.cysmiq/config.yaml
~/.cysmiq/config.yaml
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
List repositories in a workspace
List applications in a 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:
| Command | Important flags | Output |
|---|---|---|
tenants list | --limit, --cursor | table, json |
repos list | --org, --source, --application, --limit, --cursor | table, json |
applications list | --limit, --cursor | table, json |
--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
Usecysmiq 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
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 passed2: Usage error, invalid flag value, missing required setting, or canceled command3: Conflict, such as a stale--status-version4: Unauthorized API token5: Forbidden API request or token without the required ability6: Resource not found7: Scan unavailable for the provided SHA8: API validation error9: API or transport error, including failed scan terminal states and wait timeouts after a scan was observed10: Policy failure because the configured threshold was exceeded
1 is reserved for generic shell or runtime failures outside the CLI’s explicit error classes.
Options:
| Flag | Environment variable | Default | Description |
|---|---|---|---|
--repo | CYSMIQ_REPO | - | Repository identifier or name |
--application | CYSMIQ_APPLICATION | - | Application prefixed ID or name. Mutually exclusive with --repo |
--ref | CYSMIQ_REF | - | Git ref, such as a branch or tag |
--sha | CYSMIQ_SHA | - | Git commit SHA. When set, check waits for scan completion before evaluating results |
--fail-on | CYSMIQ_FAIL_ON | critical,high | Severities that cause failure |
--max-count | CYSMIQ_MAX_COUNT | -1 | Fail if total vulnerabilities exceeds this number. -1 disables the count gate |
--poll-interval | CYSMIQ_POLL_INTERVAL | 5s | Polling interval while waiting for a SHA scan to finish. Include a duration unit |
--wait-timeout | CYSMIQ_WAIT_TIMEOUT | 15m | Maximum time to wait for a SHA scan to reach a terminal state. Include a duration unit |
--limit | CYSMIQ_LIMIT | 50 | Max vulnerability items to fetch for policy evaluation (1-200) |
--severity | CYSMIQ_SEVERITY | all | Filter by severity: critical, high, medium, low |
--type | CYSMIQ_TYPE | all | Filter by type: code, dependency, secret |
--confirmed | CYSMIQ_CONFIRMED | true | Only include confirmed vulnerabilities |
--triaged | CYSMIQ_TRIAGED | all | Filter by triage status: yes or no |
--state | CYSMIQ_STATE | open | Filter by workflow state: open, fixed, accepted, ignored, rejected, or all |
--output | CYSMIQ_OUTPUT | summary | Output 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
Check a specific commit
Check an application
Check a commit with shorter polling
Fail if more than 10 vulnerabilities
JSON output for parsing
List Vulnerabilities
Usecysmiq 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
| Flag | Default | Description |
|---|---|---|
--repo | (auto-infer) | Repository identifier |
--application | Application prefixed ID or name. Mutually exclusive with --repo | |
--ref | (auto-infer) | Git ref (branch or tag) |
--sha | Git commit SHA | |
--severity | (all) | Filter by severity |
--type | (all) | Filter by type |
--confirmed | true | Only include confirmed vulnerabilities |
--triaged | (all) | Filter by triage status |
--state | open | Filter by workflow state: open, fixed, accepted, ignored, rejected, or all |
--assignee | Filter by assignee: me, unassigned, user ID, prefixed ID, or email | |
--limit | 50 | Max items per page (1-200) |
--all | false | Fetch all pages |
--cursor | Pagination cursor | |
--output | cards | Output format: summary, cards, table, json |
--json | Output JSON with optional comma-separated field projection | |
--color | auto | Color mode for human-readable output: auto, always, never |
List critical vulnerabilities across all pages
List vulnerabilities for an application
List vulnerabilities assigned to you
Export as JSON
Export selected JSON fields
Get Vulnerability Details
Usecysmiq vulns get to get details for one vulnerability.
Get vulnerability details
| Flag | Default | Description |
|---|---|---|
--include | Include extra detail: locations, advisory, secret, call_hierarchies, impacts, human_escalations | |
--locations-limit | 50 | Max locations to fetch when --include locations is used |
--output | summary | Output format: summary, json |
--json | Output JSON with optional comma-separated field projection | |
--color | auto | Color mode for summary output: auto, always, never |
Get selected fields
Include locations and advisory details
List Vulnerability Locations
Usecysmiq vulns locations to list locations for one vulnerability.
List vulnerability locations
| Flag | Default | Description |
|---|---|---|
--scope | all | Location scope: live for only unfixed locations, or all to include fixed locations |
--limit | 50 | Max locations per page (1-200) |
--cursor | Pagination cursor | |
--output | cards | Output format: summary, cards, table, json |
--json | Output JSON with optional comma-separated field projection | |
--color | auto | Color mode for human-readable output: auto, always, never |
List live locations as a table
Assign Vulnerabilities
Usecysmiq vulns assign to assign a vulnerability to a user.
Assign to yourself
| Flag | Default | Description |
|---|---|---|
--to | Assignee: me, user ID, prefixed ID, or email | |
--status-version | Expected vulnerability status version for conflict protection | |
--output | summary | Output format: summary, json |
--json | false | Output JSON |
Clear Vulnerability Assignees
Usecysmiq vulns unassign to clear the assignee on a vulnerability.
Clear assignee
| Flag | Default | Description |
|---|---|---|
--status-version | Expected vulnerability status version for conflict protection | |
--output | summary | Output format: summary, json |
--json | false | Output JSON |
Triage Vulnerabilities
Usecysmiq vulns triage to change vulnerability triage state.
Mark a vulnerability as accepted
ignored when the finding is a false positive.
Options:
| Flag | Default | Description |
|---|---|---|
--state | Triage state: open, fixed, accepted, ignored | |
--reason | Triage reason or comment | |
--status-version | Expected vulnerability status version for conflict protection | |
--output | summary | Output format: summary, json |
--json | false | Output JSON |
Summarize Vulnerabilities
Usecysmiq vulns summary to show a vulnerability count summary without listing individual items.
Show vulnerability summary
Show application vulnerability summary
| Flag | Default | Description |
|---|---|---|
--repo | (auto-infer) | Repository identifier |
--application | Application prefixed ID or name. Mutually exclusive with --repo | |
--ref | (auto-infer) | Git ref (branch or tag) |
--sha | Git commit SHA | |
--severity | (all) | Filter by severity |
--type | (all) | Filter by type |
--confirmed | true | Only include confirmed vulnerabilities |
--triaged | (all) | Filter by triage status |
--state | open | Filter by workflow state: open, fixed, accepted, ignored, rejected, or all |
--output | summary | Output format: summary, json |
vulns summary supports the same vulnerability filter fields as vulns list, except pagination, assignee, color, and field projection.
Show Version
Usecysmiq version to print version information.
Show version
Update CLI
Usecysmiq update to update the CLI to the latest version.
Update to latest
| Flag | Description |
|---|---|
--check | Check for updates without installing |
--force | Force update even if installed through a package manager |
Check for updates
Agent Skills
Usecysmiq 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 ID | Agent | Project install path |
|---|---|---|
codex | Codex | .codex/skills/cysmiq |
claude | Claude Code | .claude/skills/cysmiq |
agents | Portable agent layout | .agents/skills/cysmiq |
List available skills
Install for Codex
Install for all supported agents
Check installed skills
Diagnose skill setup
Update installed skills
Remove installed skills
| Scope | Description |
|---|---|
auto | Default for install. Uses project scope when a Git root or agent marker is detected, otherwise uses user scope. |
project | Installs into the current project root. If no project root is detected, the current working directory is used. |
user | Installs into the user’s home directory. For Codex, CODEX_HOME is used when set. |
| Flag | Commands | Description |
|---|---|---|
--agent | install, status, update, remove | Agent ID to target. Repeat the flag or pass comma-separated values. |
--all-agents | install, status, update, remove | Target every supported agent. |
--scope | install, status, update, remove | Install scope: auto, project, or user. |
--json | list, install, status, doctor, update, remove | Emit JSON output. |
--source | list, install, status, doctor, update | Override the metadata source with a URL or file:// path. |
--version | list, install, status, doctor, update | Pin a specific skills bundle version. |
--backup | install, update | Back up modified files before overwriting them. |
--force | install, update, remove | Overwrite or remove locally modified Cysmiq-owned files. |
--yes | update | Skip 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
Thecheck, 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
GitLab CI
GitLab CI configuration
CircleCI
CircleCI configuration
Global options
These options apply to all commands:| Flag | Environment variable | Description |
|---|---|---|
--base-url | CYSMIQ_BASE_URL | API base URL |
--tenant | CYSMIQ_TENANT | Workspace slug |
--token | CYSMIQ_TOKEN | API token |
--no-infer | CYSMIQ_NO_INFER | Disable auto-inference from CI environment, local git, and default branch fallback |
Shared vulnerability filters
These options apply tocheck, vulns list, and vulns summary unless a command table states otherwise.
| Flag | Environment variable | Description |
|---|---|---|
--repo | CYSMIQ_REPO | Repository identifier or name |
--application | CYSMIQ_APPLICATION | Application prefixed ID or name. Mutually exclusive with --repo |
--ref | CYSMIQ_REF | Git ref, such as a branch or tag |
--sha | CYSMIQ_SHA | Git commit SHA |
--confirmed | CYSMIQ_CONFIRMED | Only confirmed vulnerabilities |
--triaged | CYSMIQ_TRIAGED | Filter triaged status: yes or no |
--state | CYSMIQ_STATE | Filter workflow state: open, fixed, accepted, ignored, rejected, or all |
--severity | CYSMIQ_SEVERITY | Filter by severities: critical, high, medium, low |
--type | CYSMIQ_TYPE | Filter by types: code, dependency, secret |
--limit | CYSMIQ_LIMIT | Max items to fetch on commands that expose --limit |
--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.
Related docs
- API keys: Generate tokens for CLI authentication
- Vulnerability lifecycle: Understand vulnerability statuses and triage states