CI/CD & AI Agent Guide

The Volr CLI is designed to work with AI coding agents and CI/CD pipelines. Every interactive step has a non-interactive equivalent.

AI Agent Flow (Claude Code, Cursor, Codex)

Step 1: Authenticate

Send OTP to the developer's email:

npx create-volr auth login --email dev@company.com --json
# → { "ok": true, "message": "OTP sent to dev@company.com" }

The agent asks the developer for the OTP code, then verifies:

npx create-volr auth verify --email dev@company.com --otp 482913 --json
# → { "ok": true, "email": "dev@company.com" }

Step 2: Connect Wallet

If no wallet is connected, the init wizard outputs a URL for the developer to visit:

npx create-volr --skip-auth --json
# → Opens wallet connection URL, polls until connected

The agent shows the URL to the developer and waits for polling to complete.

Step 3: Discover Available Tokens

npx create-volr checkout tokens list --json
# → { "ok": true, "data": [{ "symbol": "USDC", "chain": "Base", ... }] }

The agent can present these options to the developer.

Step 4: Create Project & Configure

npx create-volr --project-name "my-app" --tokens "USDC:base" --skip-auth --json
# → { "ok": true, "projectId": "xxx", "serverKey": "volr_server_..." }

This creates the project, saves volr.json and VOLR_SERVER_KEY to .env.

One-Command Setup (with piped OTP)

If the developer provides the OTP upfront:

echo "482913" | npx create-volr --email dev@company.com --project-name "my-app" --tokens "USDC:base" --json

CI/CD Pipeline

For automated environments where authentication is pre-configured:

# Use existing auth token
npx create-volr auth login --token $VOLR_AUTH_TOKEN

# Run setup
npx create-volr --project-name "$PROJECT_NAME" --tokens "USDC:base" --skip-auth --json

# Verify
npx create-volr checkout doctor --json

JSON Output Format

All commands with --json return:

Success:

{ "ok": true, "data": { ... } }

Error:

{ "ok": false, "error": { "code": "ERROR_CODE", "message": "Human-readable message" } }