CLI Reference

The CRA Evidence CLI integrates SBOM uploads, vulnerability scanning, and CRA compliance workflows into your terminal and CI/CD pipelines.

---

1. Getting Started

Installation

# PyPI
pip install craevidence

# Docker (includes Syft for SBOM generation from images)
docker pull craevidence/cli:latest

Authentication

Generate an API key at Settings > API Keys in the app. The CLI resolves credentials in this order: --api-key flag > environment variable > config file.

# Recommended: environment variable (works in terminals and CI/CD)
export CRA_EVIDENCE_API_KEY=cra_your_key_here

# Optional: override the default API URL
export CRA_EVIDENCE_URL=https://app.craevidence.com   # this is the default

# Or persist to ~/.cra-evidence/config.yaml
api_key: cra_your_key_here
url: https://app.craevidence.com
timeout: 60

---

2. Upload Your First SBOM

# Upload an existing SBOM file (product and version are auto-created if absent)
craevidence upload-sbom --product my-app --version 1.0.0 --file sbom.json

# Generate an SBOM from a Docker image and upload in one step
craevidence upload-sbom --product my-app --version 1.0.0 --image nginx:latest

# Generate an SBOM from source code
craevidence upload-sbom --product my-app --version 1.0.0 --source ./src

# Upload, scan, and fail the pipeline if high or critical vulnerabilities are found
craevidence upload-sbom --product my-app --version 1.0.0 --file sbom.json \
  --scan --fail-on high

Key flags: --file, --image, or --source (mutually exclusive). Default SBOM format is cyclonedx. Use --format spdx for SPDX. Products and versions are auto-created by default; pass --no-create-product or --no-create-version to prevent this.

---

3. CI/CD Pipeline Setup

The CLI auto-detects GitHub Actions, GitLab CI, and other common CI environments and attaches commit SHA, branch, pipeline ID, and repository to uploads. Override with --commit, --branch, --pipeline-id, --repository, or disable with --no-ci-detect.

GitHub Actions example

name: CRA Evidence

on:
  push:
    branches: [main]
  release:
    types: [published]

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

      - name: Install CLI
        run: pip install craevidence

      - name: Upload SBOM
        env:
          CRA_EVIDENCE_API_KEY: ${{ secrets.CRA_EVIDENCE_API_KEY }}
        run: |
          craevidence upload-sbom \
            --product ${{ github.event.repository.name }} \
            --version ${{ github.ref_name }} \
            --file sbom.json \
            --scan \
            --fail-on high

      - name: Wait for CRA readiness
        env:
          CRA_EVIDENCE_API_KEY: ${{ secrets.CRA_EVIDENCE_API_KEY }}
        run: |
          craevidence wait-ready \
            --product ${{ github.event.repository.name }} \
            --version ${{ github.ref_name }} \
            --timeout 300

      - name: Mark as released
        if: github.event_name == 'release'
        env:
          CRA_EVIDENCE_API_KEY: ${{ secrets.CRA_EVIDENCE_API_KEY }}
        run: |
          craevidence release \
            --product ${{ github.event.repository.name }} \
            --version ${{ github.ref_name }} \
            --state released

---

4. Monitoring CRA Status

Check status once

craevidence status --product my-app --version 1.0.0

# Machine-readable output
craevidence --output json status --product my-app --version 1.0.0

The status command shows CRA readiness (ready or incomplete), SBOM quality score, vulnerability counts by severity, and the CRA documents checklist. Pass --fail-on critical|high|medium|low to exit with code 20 (CRANonCompliantError) when cra_status != "ready". Without --fail-on, or with --fail-on none, the command always exits 0 on success.

Block until ready

# Poll every 10s, timeout after 5 minutes (defaults)
craevidence wait-ready --product my-app --version 1.0.0

# Custom interval and timeout
craevidence wait-ready --product my-app --version 1.0.0 --timeout 120 --interval 15

wait-ready exits 0 when CRA status is ready, exits 1 on timeout.

---

5. Common Commands Quick Reference

Global flags (before the subcommand): --api-key, --url, --output text|json, -v/--verbose.

Release states: draft, pending_review, approved, released, deprecated, end_of_life (enforced in order server-side).

---

6. Exit Codes

---

7. Troubleshooting

• "Authentication failed" (exit 2): Verify CRA_EVIDENCE_API_KEY is set and the key has not been revoked. Run craevidence --api-key cra_xxx status --product test --version 0 to isolate.
• Upload succeeds but CRA status stays incomplete: Required documents are missing. Run craevidence status to see the documents checklist and upload the missing items with upload-document.
• wait-ready times out: Increase --timeout. Check scan state in status output — if scan is stuck, re-trigger with craevidence scan --product ... --version ....