Pipelines

The VertaaUX CLI is designed for Unix composability. Commands read from stdin and write structured output to stdout, enabling powerful pipeline workflows.

How Piping Works

The CLI separates data from diagnostics:

stdout -- Structured data (JSON, markdown, SARIF) for piping to other commands
stderr -- Spinners, progress bars, banners, and error messages

This means you can safely pipe output between commands without diagnostic noise corrupting the data stream.

# stdout: JSON audit data | stdin: explain reads it
vertaa audit https://example.com --json | vertaa explain

The --json Flag

Most commands support --format json (or the --json shorthand on audit). When piping between commands, always use JSON format for the source command:

# Correct: JSON output piped to next command
vertaa audit https://example.com --json | vertaa triage

# Also correct: explicit format flag
vertaa audit https://example.com --format json | vertaa triage

Machine Mode

For CI environments where you need strict output control, use --machine:

# Machine mode wraps output in an envelope with metadata
vertaa audit https://example.com --machine | jq '.data.scores'

AI commands automatically unwrap the envelope format when reading piped input, so you can pipe --machine output directly.

Common Pipelines

Audit and Explain

Get an AI-powered summary of your audit findings.

# Quick summary
vertaa audit https://example.com --json | vertaa explain

# Detailed summary with per-issue evidence
vertaa audit https://example.com --json | vertaa explain --verbose

Audit, Triage, and Fix Plan

Full remediation workflow from audit to actionable plan.

# Step 1: See what needs attention and in what order
vertaa audit https://example.com --json | vertaa triage --verbose

# Step 2: Get a structured fix plan
vertaa audit https://example.com --json | vertaa fix-plan

# Or save the audit and reuse it
vertaa audit https://example.com --json > audit.json
vertaa triage --file audit.json --verbose
vertaa fix-plan --file audit.json --json | jq '.data.items[] | select(.effort == "trivial")'

PR Diff Safety Review

Check if a pull request's changes are safe relative to known audit findings.

# GitHub CLI integration
gh pr diff 123 | vertaa patch-review --job <audit-job-id>

# Git diff
git diff HEAD~1 | vertaa patch-review --job <audit-job-id>

# From a patch file
vertaa patch-review --diff-file fix.patch --findings audit.json

Changelog Generation

Generate release notes from the diff between two audit runs.

# Pipe diff output to release-notes
vertaa diff --job-a baseline-job --job-b current-job --json | vertaa release-notes

# Or use job IDs directly
vertaa release-notes --job-a baseline-job --job-b current-job

# Save to file
vertaa diff --job-a abc --job-b def --json | vertaa release-notes > RELEASE_NOTES.md

Team Knowledge Base

Generate a playbook document from recurring findings.

# Generate playbook for a specific team
vertaa audit https://example.com --json | vertaa doc --team "Frontend"

# Save to file for team wiki
vertaa doc --job abc123 --team "Design System" > playbook.md

Regression Detection

Compare audit snapshots to detect regressions.

# Save baseline
vertaa audit https://example.com --json > baseline.json

# After changes, compare
vertaa audit https://example.com --json > current.json
vertaa compare --before baseline.json --after current.json --verbose

Intent to Execution

Convert a natural language request to a CLI command and run it.

# See what command to run
vertaa suggest "deep audit with CI gating"

# Output: vertaa audit https://example.com --mode deep --fail-on error

CI/CD Pipelines

GitHub Actions: Audit and Triage

name: UX Audit
on: [pull_request]

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

      - name: Run audit
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
        run: |
          npx @vertaaux/cli audit https://staging.example.com \
            --json --wait > audit.json

      - name: Triage findings
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
        run: |
          npx @vertaaux/cli triage --file audit.json --verbose

      - name: Generate fix plan
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
        run: |
          npx @vertaaux/cli fix-plan --file audit.json

GitHub Actions: PR Patch Review

name: Patch Safety
on: [pull_request]

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

      - name: Review patch
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
          GH_TOKEN: ${{ github.token }}
        run: |
          gh pr diff ${{ github.event.pull_request.number }} \
            | npx @vertaaux/cli patch-review \
              --job ${{ vars.BASELINE_AUDIT_JOB }} \
              --format json \
            | jq -e '.data.verdict != "UNSAFE"'

GitHub Actions: Release Notes

name: Release Notes
on:
  push:
    tags: ['v*']

jobs:
  notes:
    runs-on: ubuntu-latest
    steps:
      - name: Generate release notes
        env:
          VERTAAUX_API_KEY: ${{ secrets.VERTAAUX_API_KEY }}
        run: |
          npx @vertaaux/cli release-notes \
            --job-a ${{ vars.PREVIOUS_AUDIT_JOB }} \
            --job-b ${{ vars.CURRENT_AUDIT_JOB }} \
            > release-notes.md

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: release-notes
          path: release-notes.md

Error Handling in Pipelines

Exit Codes

The CLI uses standard exit codes for pipeline control:

Code	Meaning
`0`	Success
`1`	Issues found / Quality gate failed
`2`	Command error (invalid input, network error, auth failure)
`3`	Score below threshold

Pipefail

Always use set -eo pipefail in shell scripts to catch failures in piped commands:

#!/bin/bash
set -eo pipefail

# If audit fails, the entire pipeline exits
vertaa audit https://example.com --json | vertaa triage

Without pipefail, a failure in the first command (e.g., network error) would be silently ignored, and triage would receive empty input.

Error Propagation

When an AI command receives invalid or empty input, it exits with code 2 and prints an error to stderr:

# This will fail gracefully if no audit data is piped
echo '{}' | vertaa triage
# stderr: Error: No issues found in audit data.
# exit code: 2

Timeout Handling

AI commands have a built-in timeout (default: 30 seconds). If the LLM takes too long, the command exits with code 2:

# The timeout is automatic -- no special handling needed
vertaa audit https://example.com --json | vertaa explain
# If LLM times out: "LLM request timed out (try again)"

Dry Run

Use --dry-run to preview what a command would do without making API calls:

gh pr diff 123 | vertaa patch-review --job abc123 --dry-run
# [dry-run] Would analyze diff against findings
#   Diff size: 1234 characters
#   Findings: 8
#   Job ID: abc123