Structured JSON output, CI/CD automation patterns, and machine-readable CLI interfaces.

Agent mode turns the ivybloom CLI into a machine-readable interface, wrapping every response in a structured JSON envelope for reliable parsing. Reach for it when you're scripting the CLI or wiring it into CI/CD pipelines, where you need predictable output, exit codes, and error codes rather than human-formatted tables. It runs against the same backend and job history as interactive use, so automated runs share state with your terminal and web work. For the full command set, see the CLI overview.

Difficulty

intermediate

Agent & Automation Mode

Structured JSON output, CI/CD automation patterns, and machine-readable CLI interfaces.

Overview

The ivybloom CLI provides three automation modes for machine consumption:

Mode	Flag	Description
Agent	`--agent`	Full JSON envelope with metadata
Script	`--script` / `-p` / `--simple`	Stripped output, no TUI elements
JSON	`--json`	Pretty JSON without envelope wrapper

Agent Mode

Agent mode wraps every CLI response in a standardized JSON envelope for reliable parsing.

ivybloom jobs list --agent

Success Envelope

{
  "success": true,
  "data": {
    "jobs": [
      {"id": "job_abc123", "tool": "esmfold", "status": "completed"},
      {"id": "job_def456", "tool": "admet", "status": "running"}
    ],
    "total": 2
  },
  "meta": {
    "envelope_version": "1.2.0",
    "timestamp": "2026-03-08T12:00:00Z",
    "cli_version": "0.8.10",
    "duration_ms": 1234,
    "command": "jobs list",
    "exit_code": 0
  }
}

meta also carries request_id and trace_id when they are set.

Error Envelope

{
  "success": false,
  "error": {
    "code": "ERR_INVALID_INPUT",
    "message": "Invalid protein sequence",
    "hint": "Check the sequence for non-amino-acid characters",
    "http_status": 400,
    "server_code": "INVALID_SEQUENCE",
    "retryable": false
  },
  "meta": {
    "envelope_version": "1.2.0",
    "timestamp": "2026-03-08T12:00:01Z",
    "cli_version": "0.8.10",
    "duration_ms": 45,
    "command": "run",
    "exit_code": 2
  }
}

Envelope 1.2.0 additions (present only when the failure came from an HTTP response):

error.http_status: HTTP status code from the server (e.g., 400, 401, 429, 502)
error.server_code: Server's own error code (e.g., INSUFFICIENT_CREDITS, JOB_TYPE_RETIRED)
error.retry_after: Seconds to wait before retrying (on 429, 503, 504)
meta.exit_code: Process exit code (see exit codes table below)

Test .success rather than checking a status string. --json prints the same data object without the envelope.

Error Codes Reference

All error codes are prefixed with ERR_. Common codes:

Code	Exit Code	Description	Recovery
`ERR_INVALID_INPUT`	2	Bad parameters or validation failure	Check the input and options
`ERR_NOT_FOUND`	3	Resource not found	Verify ID with `ivybloom jobs list`
`ERR_UNAUTHORIZED`	11	No token or token invalid	Run `ivybloom auth login`
`ERR_FORBIDDEN`	12	Insufficient permissions	Contact support for access
`ERR_NOT_SUPPORTED`	22	Endpoint or job type retired	List current tools with `ivybloom tools list`
`ERR_JOB_NOT_FOUND`	20	Job ID not found	Check with `ivybloom jobs list`
`ERR_TOOL_NOT_FOUND`	21	Tool not available	List tools with `ivybloom tools list`
`ERR_JOB_TYPE_RETIRED`	22	Job type was retired	Check `ivybloom tools list` for alternatives
`ERR_API_RATE_LIMIT`	31	Too many requests	Wait and retry; check `retry_after`
`ERR_INSUFFICIENT_CREDITS`	40	Account out of credits	Run `ivybloom credits summary`
`ERR_UPSTREAM_UNAVAILABLE`	32	Service temporarily down	Retry after checking `ivybloom jobs list`
`ERR_API_CONNECTION`	30	Network connectivity issue	Check your connection with `ivybloom health`
`ERR_AUTH_REQUIRED`	11	Authentication needed	Run `ivybloom auth login`
`ERR_AUTH_EXPIRED`	11	Auth token expired	Run `ivybloom auth login`
`ERR_CONFIG_NOT_FOUND`	10	Config file missing	Run `ivybloom auth login`

See go/internal/errors/errors.go in the CLI repo for the complete list.

Script Mode

Script mode strips all interactive elements (spinners, colors, progress bars) for clean piping:

ivybloom jobs list --script --format json

Equivalent environment variable:

export IVYBLOOM_SCRIPT_MODE=1
ivybloom jobs list

Output Formats

Control output format with --format or --output-format:

Format	Flag	Description
Table	`--format table`	Human-readable columns (default)
JSON	`--format json`	Pretty-printed JSON
JSON Compact	`--format json-compact`	Minified JSON (one line)
CSV	`--format csv`	Comma-separated values
YAML	`--format yaml`	YAML format

Dry-Run Modes

Validate jobs before submitting:

# Syntax validation only (fastest)
ivybloom run esmfold protein_sequence=MKLVFF --dry-run --dry-run-mode syntax

# Quick validation (checks parameter types)
ivybloom run esmfold protein_sequence=MKLVFF --dry-run --dry-run-mode quick

# Full validation (includes API checks)
ivybloom run esmfold protein_sequence=MKLVFF --dry-run --dry-run-mode full

Global Automation Flags

Flag	Description
`--agent`	JSON envelope output
`--script` / `-p` / `--simple`	Non-interactive output
`--json`	JSON output (no envelope)
`--format FORMAT`	Output format (table/json/csv/yaml)
`--force` / `-f`	Skip confirmation prompts
`--no-color`	Disable color output
`--trace-id ID`	Attach correlation ID for request tracking
`--timeout DURATION`	Override default timeout

Environment Variables

Variable	Description
`IVYBLOOM_AGENT_MODE=1`	Enable agent mode globally
`IVYBLOOM_SCRIPT_MODE=1`	Enable script mode globally
`NO_COLOR=1`	Disable color output
`IVYBLOOM_TRACE_ID`	Request correlation ID
`IVYBLOOM_API_KEY`	API key for authentication
`IVYBLOOM_DEBUG=1`	Enable debug output

Exit Codes

Every error returns a non-zero exit code that indicates the class of failure:

Code	Meaning	Example
`0`	Success	Job submitted or completed
`1`	Generic error or server error (unhealthy)	Internal server error or 500
`2`	Invalid input (caller's fault)	Bad flag, missing required parameter
`3`	Not found	Job ID or tool doesn't exist
`10`	Config or file missing	Auth config file missing
`11`	Authentication failed	No token, expired token, login required
`12`	Permission denied	Authenticated but user lacks access (403)
`13`	Session error	Session not found, create failed, expired
`14`	Campaign error	Campaign not found, required but missing
`15`	Message error	Message send or stream failed
`20`	Job not found	Job ID doesn't exist
`21`	Tool not found	Tool name not in registry
`22`	Not supported or retired	Job type was retired (410), endpoint doesn't exist (501)
`30`	Network error	Connection failed, DNS failed, timeout
`31`	Rate limited	Server returned 429; wait and retry (see `retry_after`)
`32`	Upstream unavailable	Gateway error (502, 503, 504)
`40`	Insufficient credits	Account balance cannot cover the cost (402)

Note: Submit failures (e.g., idempotent resubmission of a failed job) never exit 0. Check the error envelope's success field.

Job Submission & Idempotency

Every job submit request carries an Idempotency-Key header (a uuid v4, one per submit, reused on retries). This prevents duplicate submissions if the network fails after the server processes the request.

Retry Policy

Automatic retries: Only after 429 (rate limit) or 503 (service unavailable) responses that carry a Retry-After header
Not retried: 502 (Bad Gateway) and 504 (Gateway Timeout) are never retried automatically
Idempotent replay: If a submit fails, check ivybloom jobs list first to confirm whether the job was created, then resubmit. The server will recognize the same Idempotency-Key and return the original job (with Idempotent-Replayed: true header)
Never exit 0 on failure: Submit failures always exit non-zero, even if the job was created but the response was lost

CI/CD Patterns

GitHub Actions

name: Run Analysis

on: push

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

      - name: Install ivybloom CLI
        run: |
          curl -fsSL https://www.ivybiosciences.com/install | bash

      - name: Submit and Wait
        env:
          IVYBLOOM_API_KEY: ${{ secrets.IVYBLOOM_API_KEY }}
        run: |
          # Submit with agent mode, wait for completion
          RESULT=$(ivybloom run esmfold protein_sequence=MKLVFF --agent --wait)
          JOB_ID=$(echo "$RESULT" | jq -r '.data.job_id')
          STATUS=$(echo "$RESULT" | jq -r '.data.status')

          if [ "$STATUS" != "completed" ]; then
            echo "Job failed: $JOB_ID"
            exit 1
          fi

          # Download results
          ivybloom jobs download "$JOB_ID" --output ./results

Batch Pipeline

      - name: Batch Screen
        env:
          IVYBLOOM_API_KEY: ${{ secrets.IVYBLOOM_API_KEY }}
        run: |
          ivybloom batch submit screen.yaml --agent --wait
          ivybloom batch collect BATCH_ID --format csv --output results.csv

Parsing Agent Output with jq

# Extract job ID from submission
JOB_ID=$(ivybloom run esmfold protein_sequence=MK --agent | jq -r '.data.job_id')

# Check job status
STATUS=$(ivybloom jobs status "$JOB_ID" --agent | jq -r '.data.status')

# List completed jobs
ivybloom jobs list --status completed --agent | jq -r '.data.jobs[].id'

# Get credit balance
BALANCE=$(ivybloom credits summary --agent | jq -r '.data.credits.balance')

Agent & Automation Mode

Difficulty

Agent & Automation Mode

Overview

Agent Mode

Success Envelope

Error Envelope

Error Codes Reference

Script Mode

Output Formats

Dry-Run Modes

Global Automation Flags

Environment Variables

Exit Codes

Job Submission & Idempotency

Retry Policy

CI/CD Patterns

GitHub Actions

Batch Pipeline

Parsing Agent Output with jq

Read next

On this page