Agent Automation Guide

Download the buddo binary for your platform.

macOS (arm64 / Apple Silicon):

curl -L https://docs.buddocloud.com/cli/buddo-darwin-arm64 -o buddo
chmod +x buddo
sudo mv buddo /usr/local/bin/

macOS (amd64 / Intel):

curl -L https://docs.buddocloud.com/cli/buddo-darwin-amd64 -o buddo
chmod +x buddo
sudo mv buddo /usr/local/bin/

Linux (amd64):

curl -L https://docs.buddocloud.com/cli/buddo-linux-amd64 -o buddo
chmod +x buddo
sudo mv buddo /usr/local/bin/

Windows (PowerShell):

Invoke-WebRequest https://docs.buddocloud.com/cli/buddo-windows-amd64.exe -OutFile buddo.exe
# Move buddo.exe to a directory in your PATH

Verify installation:

buddo version

Run buddo login. The CLI opens your default browser and completes an OAuth 2.0 PKCE flow. Your credentials are saved locally and automatically refreshed on each subsequent command.

buddo login

The browser will show the Buddo login page. Sign in with your Buddo account (or create one at buddo.xyz). After successful login the browser shows "Authentication successful" and the terminal prints:

Logged in as alice (alice@example.com)

For CI/headless environments:

Obtain a JWT by calling POST /api/auth/login directly, then:

# Obtain JWT
JWT=$(curl -s -X POST https://api.buddo.xyz/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"alice@example.com","password":"yourpassword"}' \
  | jq -r '.token')

# Authenticate CLI with the JWT
buddo login --token "$JWT"

Verify authentication status:

buddo status

This shows your operator app (if any) and current deployments, confirming that credentials are valid and the API is reachable.

An operator app is your identity on the platform. It holds a point balance (funded by you), tracks your users, and is the entity that owns your deployments and campaigns.

buddo apps create --name "My Business" \
  --scopes "profile:read,points:read,points:spend,deploy:manage,campaigns:manage,app:balance:read"

The CLI prints your client_id and (if applicable) your client_secret. Save both immediately:

App created successfully!
------------------------------------------------------------
  App Name:            My Business
  Client ID:           f47ac10b-58cc-4372-a567-0e02b2c3d479
  Client Secret:       s3cr3t...
  Scopes:              profile:read, points:read, ...
  Status:              approved
------------------------------------------------------------

Confirm registration:

buddo apps list --json | jq '.[].name'

Scope reference — choose what your app needs:

Deploy a Docker container to the buddocloud platform. The container is assigned a *.apps.buddocloud.com subdomain with automatic TLS.

Option A — Using buddo.json (recommended):

Create buddo.json in your project directory:

{
  "app": {
    "name": "my-business"
  },
  "deploy": {
    "image": "myregistry/my-business:latest",
    "port": 3000,
    "env": {
      "NODE_ENV": "production",
      "BUDDO_CLIENT_ID": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "BUDDO_CLIENT_SECRET": "s3cr3t..."
    }
  }
}

buddo deploy

Option B — Inline flags (good for scripts):

buddo deploy \
  --name my-business \
  --image myregistry/my-business:latest \
  --port 3000

Confirm the prompt when shown:

Deploying "my-business" ...
  Image : myregistry/my-business:latest
  Port  : 3000

Proceed? [y/N] y

Deployment started!
  ID     : d8f3a1c2
  Status : running
  URL    : https://my-business.apps.buddocloud.com

Save the app ID — you will need it for stop/restart/destroy:

APP_ID="d8f3a1c2"

Check deployment status:

buddo status
# Or for JSON output suitable for scripting:
buddo status --json | jq '.deployed_apps[] | {name, status, url}'

Ad campaigns drive users to your app. You fund them with Buddo points; the platform distributes those points to users as impression rewards. The platform takes a 10% rake on the total budget you pay.

Before creating a campaign, ensure your app account has sufficient Buddo points. Check your balance:

buddo billing balance

Create a campaign:

buddo campaigns create \
  --name "Launch Campaign" \
  --budget 50000 \
  --surface banner \
  --payout-rate 10

The CLI shows a preview before creating:

Creating campaign:
  Name:                  Launch Campaign
  Surface:               banner
  Total payment:         50000 points
  Platform fee:          5000 points (10% rake)
  Campaign budget:       45000 points
  Payout rate:           10 points/impression

Campaign created successfully!
------------------------------------------------------------
  ID:                    550e8400-e29b-41d4-a716-446655440000
  Name:                  Launch Campaign
  Surface:               banner
  Status:                active
  Campaign budget:       45000 points
  Platform rake:         5000 points
  Total paid:            50000 points
  Payout rate:           10 points/impression
------------------------------------------------------------

Save the campaign ID:

CAMPAIGN_ID="550e8400-e29b-41d4-a716-446655440000"

Surface type guidance:

Budget sizing guidance:

• At 10 pts/impression with a 10,000 pt budget (after rake): ~900 impressions
• At 20 pts/impression with a 10,000 pt budget (after rake): ~450 impressions
• Higher payout rates attract more users but burn budget faster

Monitor your campaigns and platform engagement with the analytics commands. Run these on a schedule (e.g., every hour) to track spend.

Spend breakdown across all campaigns:

buddo analytics spend

Spend for a specific campaign:

buddo analytics spend $CAMPAIGN_ID

Platform engagement (impressions & user counts):

buddo analytics impressions
buddo analytics clicks

Scripting: detect when a campaign is exhausted

# Returns 0 if campaign is active, 1 if exhausted or cancelled
buddo analytics spend $CAMPAIGN_ID --json | jq '
  .campaigns[0] |
  if .status == "active" then
    "active: spent \(.spent) of \(.budget)"
  else
    "inactive: \(.status)"
  end
'

Date-windowed spend check:

buddo analytics spend \
  --since 2026-06-01 \
  --until 2026-06-30 \
  --json | jq '.totals'

Control your deployments and campaigns at any point using lifecycle commands. All commands are idempotent and safe to call from scripts.

Campaign lifecycle

# Pause a campaign (stops serving ads, budget preserved)
buddo campaigns pause $CAMPAIGN_ID

# Resume a paused campaign
buddo campaigns resume $CAMPAIGN_ID

# Cancel a campaign (unspent budget refunded; 10% rake is non-refundable)
buddo campaigns cancel $CAMPAIGN_ID

# List all campaigns with current status
buddo campaigns list

Deployment lifecycle

# Stop a running deployment (container terminated, record preserved)
buddo deploy stop $APP_ID

# Restart a deployment (start a stopped container, or cycle a running one)
buddo deploy restart $APP_ID

# Permanently destroy a deployment (irreversible)
buddo deploy destroy $APP_ID

# Check current status of all deployments
buddo status

State machine — campaigns:

State machine — deployments:

Scripting: automated campaign rotation

Example shell script that pauses campaigns when spend reaches 80% of budget:

#!/bin/bash
# Monitor spend and pause near-exhausted campaigns

CAMPAIGNS=$(buddo campaigns list --json | jq -r '.campaigns[].id')

for CAMPAIGN_ID in $CAMPAIGNS; do
  DATA=$(buddo analytics spend "$CAMPAIGN_ID" --json)
  BUDGET=$(echo "$DATA" | jq '.campaigns[0].budget')
  SPENT=$(echo "$DATA" | jq '.campaigns[0].spent')
  STATUS=$(echo "$DATA" | jq -r '.campaigns[0].status')

  if [ "$STATUS" = "active" ] && [ "$BUDGET" -gt 0 ]; then
    PCT=$(echo "scale=0; $SPENT * 100 / $BUDGET" | bc)
    echo "Campaign $CAMPAIGN_ID: ${PCT}% spent"

    if [ "$PCT" -ge 80 ]; then
      echo "  → Pausing (80% threshold reached)"
      buddo campaigns pause "$CAMPAIGN_ID" --json
    fi
  fi
done

Run a billing health check regularly to ensure your app account has sufficient runway. If balance runs out, active deployments may be stopped automatically.

Check current balance and runway:

buddo billing balance

  Balance      : 950,000 pts
  Daily burn   : 1,666 pts/day (estimated from last 30 transactions)
  Runway       : 570 days

Parse runway for alerting:

RUNWAY=$(buddo billing balance --json | jq -r '.runway_days')
echo "Runway: $RUNWAY days"

# Alert if under 30 days
if [ "$RUNWAY" != "unlimited" ] && [ "$RUNWAY" -lt 30 ] 2>/dev/null; then
  echo "WARNING: less than 30 days runway — top up your app account"
fi

Runway values:

View full transaction history:

buddo billing history --limit 50

Per-app billing status (check for billing-failed):

buddo billing apps --json | jq '.[] | select(.billing_status == "billing-failed") | .name'