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

# Automate Security Checks in CI/CD Pipelines with Tolmo

> Run Tolmo CLI commands in GitHub Actions, GitLab CI, and other pipelines using environment variables for token-based, non-interactive authentication.

You can use Tolmo in any CI/CD pipeline without interactive login by setting environment variables. This guide shows how to install the CLI, authenticate with a token, and run commands in automated workflows.

## Prerequisites

Before setting up Tolmo in a pipeline, make sure you have:

* A Tolmo API token (from your organization settings)
* Your organization slug (shown by `tolmo org list`)

## Install in CI

Add the following one-liner to your pipeline's setup step to install the Tolmo CLI:

```bash theme={null}
curl -fsSL https://tolmo.com/install.sh | sh
```

The install script places the binary in a writable user directory. If `~/.local/bin` is not already on your `PATH`, add it explicitly before invoking `tolmo`:

```bash theme={null}
export PATH="$HOME/.local/bin:$PATH"
```

## Authenticate with Environment Variables

Instead of running `tolmo auth login` interactively, set two environment variables and the CLI will authenticate automatically:

| Variable          | Description                                          |
| ----------------- | ---------------------------------------------------- |
| `TOLMO_API_TOKEN` | Your API token — skips interactive login             |
| `TOLMO_ORG_SLUG`  | Your organization slug — required when using a token |

Export them in your shell or inject them through your CI provider's secrets mechanism:

```bash theme={null}
export TOLMO_API_TOKEN="your-api-token"
export TOLMO_ORG_SLUG="your-org-slug"
```

<Warning>
  Store `TOLMO_API_TOKEN` in your CI provider's secrets vault — never hardcode it directly in workflow files or commit it to source control.
</Warning>

## GitHub Actions Example

The workflow below installs the CLI, adds it to the runner's `PATH` via `$GITHUB_PATH`, and queries open critical findings on every push and pull request.

```yaml .github/workflows/security.yml theme={null}
name: Security Check
on: [push, pull_request]
jobs:
  tolmo-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install Tolmo CLI
        run: |
          curl -fsSL https://tolmo.com/install.sh | sh
          echo "$HOME/.local/bin" >> $GITHUB_PATH
      - name: Check for critical findings
        env:
          TOLMO_API_TOKEN: ${{ secrets.TOLMO_API_TOKEN }}
          TOLMO_ORG_SLUG: ${{ secrets.TOLMO_ORG_SLUG }}
        run: |
          tolmo findings list --status open --severity critical --json
```

Add `TOLMO_API_TOKEN` and `TOLMO_ORG_SLUG` as repository or organization secrets in your GitHub settings before running this workflow.

## GitLab CI Example

The job below runs the same check inside an Ubuntu image. Variables defined in the `variables` block are populated from your GitLab CI/CD variable settings.

```yaml .gitlab-ci.yml theme={null}
security-check:
  image: ubuntu:latest
  script:
    - curl -fsSL https://tolmo.com/install.sh | sh
    - export PATH="$HOME/.local/bin:$PATH"
    - tolmo findings list --status open --severity critical --json
  variables:
    TOLMO_API_TOKEN: $TOLMO_API_TOKEN
    TOLMO_ORG_SLUG: $TOLMO_ORG_SLUG
```

Set `TOLMO_API_TOKEN` and `TOLMO_ORG_SLUG` in your GitLab project's **Settings → CI/CD → Variables** panel and mark them as masked.

## Automation Rules

Follow these rules when running Tolmo commands in automated scripts and pipelines:

* Always use `--json` for machine-readable output when you need to parse results programmatically.
* Use `--org <slug>` to override the active organization on a per-command basis without changing global state.
* Use `TOLMO_API_TOKEN` and `TOLMO_ORG_SLUG` instead of interactive login — profiles are not available in headless environments.
* For `tolmo query -- gh` and `tolmo query -- aws`, the `--` separator is mandatory. Without it, flags like `--region` and `--repo` are stripped before they reach the underlying CLI.