Agent usage

The sureva CLI is designed for use in AI agents, pipelines, and scripts. All commands output JSON by default and expose a machine-readable command tree via --help --json.

JSON-first default

The default output format is JSON. You do not need to pass --output json explicitly — it is the default.

sureva apps list --org my-org
# Returns: [{ "id": "...", "name": "...", ... }]

sureva deploys status my-app-id deploy-123 --org my-org
# Returns: { "id": "...", "status": "success", ... }

Pass --output table only when displaying output to a human in a terminal.

Command tree introspection

Get the full machine-readable command tree to understand available commands, flags, and argument shapes:

sureva --help --json

This outputs a JSON document describing every command, subcommand, flag, and its type — useful for agents that need to discover CLI capabilities at runtime.

Scripting with —output json

Combine JSON output with standard tools:

# Get the status of the latest deployment
sureva deploys list my-app-id --org my-org | jq '.[0].status'

# Check if all env vars are set
sureva env get my-app-id --org my-org --reveal | jq 'keys'

# Trigger a deployment and capture the deploy ID
DEPLOY_ID=$(sureva deploys trigger my-app-id --org my-org --tag v1.2.3 | jq -r '.id')

Exit code patterns

Use exit codes to handle failures without parsing error text. The CLI always exits 0 on success and a non-zero code on failure.

Exit code	Condition	Suggested agent action
0	Success	Continue workflow
1	General / API error	Log the JSON error body; retry with backoff if transient
2	Auth error	Check SUREVA_TOKEN; surface auth failure to user
3	Not found	Stop; resource does not exist
4	Validation error	Stop; fix the input before retrying
5	Network error	Retry with exponential backoff

sureva deploys trigger my-app-id --org my-org --tag v1.2.3
EXIT_CODE=$?

case $EXIT_CODE in
  0) echo "Deployment triggered successfully" ;;
  2) echo "Authentication failed — check SUREVA_TOKEN" >&2; exit 1 ;;
  4) echo "Validation error — check --tag and --org" >&2; exit 1 ;;
  5) echo "Network error — retrying..." ;;
  *) echo "Unexpected error (exit $EXIT_CODE)" >&2; exit $EXIT_CODE ;;
esac

CI and automation setup

Set SUREVA_TOKEN as a secret in your CI environment:

# GitHub Actions example
steps:
  - name: Trigger deployment
    env:
      SUREVA_TOKEN: ${{ secrets.SUREVA_TOKEN }}
      SUREVA_ORG: my-org
    run: |
      sureva deploys trigger ${{ env.APP_ID }} --tag ${{ github.ref_name }}

Agent instruction template

Use the sureva CLI to manage Sureva Cloud resources.
Set SUREVA_TOKEN to a valid PAT (sapi_ prefix).
All commands output JSON by default — parse JSON output, do not scrape human text.
Use exit codes to detect failures: 0=success, 1=API error, 2=auth, 3=not-found, 4=validation, 5=network.
Run `sureva --help --json` to discover available commands and flags.
apps create and apps delete are available; deploys cancel is not yet implemented.
Use --wait on apps create and deploys trigger to block until the resource is ready in CI.