> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cysmiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use the CLI in CI/CD

> Evaluate Cysmiq scan results in a pipeline and use the CLI exit code to pass or fail a job.

## Overview

Use `cysmiq check` in CI/CD to evaluate findings from a Cysmiq scan and fail the job when a severity or count threshold is exceeded.

The CLI queries scan results from Cysmiq. It does not replace the repository integration that triggers scans.

<Info>Availability depends on your Cysmiq plan.</Info>

## Prerequisites

* Connect the repository to Cysmiq and confirm that push or pull request scans run.
* Create an API key with `vulnerabilities:read` and `scans:read` scopes.
* Store the token in the CI provider's secret store.
* Know the Cysmiq workspace slug and repository path.

## Choose the revision

Use a commit SHA when the job must wait for and evaluate the scan of the exact revision:

```bash Check a commit theme={null}
cysmiq check --repo my-org/my-repo --sha "$COMMIT_SHA"
```

Use a ref when the job should evaluate the latest known scan for a branch or tag:

```bash Check a branch theme={null}
cysmiq check --repo my-org/my-repo --ref main
```

Application checks evaluate findings across all repositories in an application and do not wait for one repository scan:

```bash Check an application theme={null}
cysmiq check --application app_01hxyz
```

## Configure the policy gate

By default, `cysmiq check` fails when it finds a critical or high-severity vulnerability. Adjust the gate for the workflow:

```bash Fail only on critical vulnerabilities theme={null}
cysmiq check --repo my-org/my-repo --sha "$COMMIT_SHA" --fail-on critical
```

```bash Fail when more than ten findings match theme={null}
cysmiq check --repo my-org/my-repo --sha "$COMMIT_SHA" --max-count 10
```

Use `--severity`, `--type`, `--state`, and `--triaged` to focus the evaluation. See the [CLI reference](/reference/cli#run-checks) for every option.

## Add the CI job

<Tabs>
  <Tab title="GitHub Actions">
    ```yaml GitHub Actions workflow theme={null}
    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
    ```
  </Tab>

  <Tab title="GitLab CI">
    ```yaml GitLab CI configuration theme={null}
    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_REPO: $CI_PROJECT_PATH
        CYSMIQ_SHA: $CI_COMMIT_SHA
    ```
  </Tab>

  <Tab title="CircleCI">
    ```yaml CircleCI configuration theme={null}
    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
    ```
  </Tab>
</Tabs>

Configure `CYSMIQ_TENANT` and `CYSMIQ_TOKEN` as protected CI/CD variables or secrets in the provider. The examples inherit those values without writing them into the workflow file.

## Interpret the result

The most important exit codes for a pipeline are:

| Exit code | Meaning                                                            |
| --------- | ------------------------------------------------------------------ |
| `0`       | The check passed.                                                  |
| `4`       | The API token is invalid or expired.                               |
| `5`       | The token or workspace lacks access to the operation.              |
| `6`       | The workspace, repository, application, ref, or SHA was not found. |
| `7`       | A scan was not available for the requested SHA.                    |
| `9`       | An API, transport, terminal scan, or wait-timeout error occurred.  |
| `10`      | The configured vulnerability threshold was exceeded.               |

Use JSON output when the pipeline also needs the structured result:

```bash Emit JSON theme={null}
cysmiq check --repo my-org/my-repo --sha "$COMMIT_SHA" --output json
```

Keep exit code `10` distinct from authentication, configuration, and service failures when the pipeline reports the result.

## Related docs

* [CLI reference](/reference/cli)
* [Create and manage API keys](/guides/api-keys)
* [Connect a VCS](/guides/connect-vcs)
* [VCS status updates](/scanning/vcs-status-updates)