CLI Reference

Primary focus: The CLI is designed for PR reviews and quality gates in CI/CD pipelines. While it supports triggering scans and exporting results, the core use case is integrating CodeStax security checks into your automated workflows — blocking merges that introduce critical vulnerabilities and triggering PR-level reviews for configured pull-request workflows.

The CodeStax CLI lets you interact with the platform from your terminal or CI/CD pipeline.

Installation

The CLI is a self-contained Python 3 script (cli/main.py) with no third-party dependencies. Clone the repository and run it directly with Python:

# Run from a clone of the repository
python3 cli/main.py <command>
 
# Show available commands
python3 cli/main.py --help

Authentication

Set your API key as an environment variable:

export CODESTAX_API_KEY="your-api-key-here"
export CODESTAX_API_URL="https://codestax.co/api"  # optional, defaults to production

Generate an API key from Settings → API Keys in the dashboard.

Commands

codestax trigger

Trigger a PR review for a repository.

codestax trigger 42 1337 --wait

codestax gate

Read the immutable quality-gate snapshot published for a review.

codestax gate 1337

The CLI does not accept a threshold override. A gate result is evaluated by the review worker using the effective organization/repository policy and then stored as an immutable, versioned snapshot. Configure the organization policy under Settings → Policies and use a repository policy override for repositories that need different limits. Changing policy later does not rewrite an existing review’s decision.

codestax list

List PR reviews, optionally filtered by repository and status.

codestax list --repo-id 42 --limit 10

codestax issues

List issues for a specific review.

codestax issues 1337

codestax dora

Retrieve DORA metrics, optionally scoped to a repository.

codestax dora --days 30 --repo-id 42

codestax export

Export a review report.

codestax export 1337 --format json --output results.json
codestax export 1337 --format csv --output results.csv

The CLI validates the response media type before decoding it. JSON exports require application/json; CSV exports require text/csv and are written as exact UTF-8 text (including the server’s original line endings). A mismatch is an operational error rather than a best-effort format guess.

codestax review

All-in-one for CI/CD: trigger a PR review, wait for it to complete, then read the immutable quality-gate snapshot. The exit code distinguishes policy failure, inconclusive analysis, active work, review failure, timeout, and operational errors.

codestax review 42 1337

CI/CD Usage

GitHub Actions

name: CodeStax Security Gate
on: [pull_request]
 
jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'
 
      - name: Check out CodeStax CLI
        uses: actions/checkout@v4
        with:
          repository: codestax/codestax-platform
          path: codestax
 
      - name: Trigger PR review and enforce quality gate
        env:
          CODESTAX_API_KEY: ${{ secrets.CODESTAX_API_KEY }}
        run: python3 codestax/cli/main.py review ${{ vars.CODESTAX_REPO_ID }} ${{ github.event.pull_request.number }}

GitLab CI

codestax-gate:
  image: python:3.11-alpine
  stage: test
  before_script:
    - git clone https://github.com/codestax/codestax-platform.git codestax
  script:
    - python3 codestax/cli/main.py review $CODESTAX_REPO_ID $CI_MERGE_REQUEST_IID
  variables:
    CODESTAX_API_KEY: $CODESTAX_API_KEY

Exit Codes

These values are the stable public CLI contract for CI automation. Only exit code 0 should be treated as permission to continue a protected pipeline. In particular, 3 means inconclusive, not passed or failed.