Home › CLI › Quickstart

CLI Quickstart

The Buddo CLI (buddo) is the fastest way to manage your operator apps, deployments, and ad campaigns from a terminal. This guide takes you from zero to a running deployment and active campaign in five steps.

1. Install

Download the pre-built binary for your platform from the Buddo releases page.

# 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 — amd64)
Invoke-WebRequest https://docs.buddocloud.com/cli/buddo-windows-amd64.exe -OutFile buddo.exe
# Add to a directory in your PATH, or invoke as .\buddo.exe

Verify the installation:

buddo version
# buddo version v2.0.0
Note: The CLI communicates with https://api.buddo.xyz by default. Override with --api-url if you run a self-hosted instance.

2. Authenticate

Run buddo login. The CLI opens your browser and completes an OAuth 2.0 PKCE flow — your password never touches the CLI. 

buddo login

Expected output:

Opening your browser for authentication…
If the browser did not open, visit:

  https://buddo.xyz/oauth/authorize?...

Waiting for authentication (timeout: 2 minutes)…
Exchanging authorization code for tokens…
Logged in as alice (alice@example.com)

Your token is saved to ~/.config/buddo/credentials.json (macOS/Linux) or %APPDATA%\buddo\credentials.json (Windows) and is refreshed automatically on each command.

CI/CD: For headless environments, use a pre-generated JWT directly: buddo login --token <JWT>. Obtain the JWT from POST /api/auth/login.

3. Deploy your first app

Create a buddo.json config file in your project directory, then run buddo deploy.

buddo.json

{
  "app": {
    "name": "my-app"
  },
  "deploy": {
    "image": "myregistry/my-app:latest",
    "port": 3000,
    "env": {
      "NODE_ENV": "production"
    }
  }
}
buddo deploy

You can skip the config file and pass flags directly:

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

The CLI confirms before deploying:

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

Proceed? [y/N] y

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

Check deployment status at any time:

buddo status

4. Create your first campaign

Ad campaigns drive user engagement. You fund a campaign with Buddo points; the platform pays users 10 points per impression by default. The platform takes a 10% rake on the total budget you pay. 

buddo campaigns create \
  --name "Summer Launch" \
  --budget 10000 \
  --surface banner

Expected output:

Creating campaign:
  Name:                  Summer Launch
  Surface:               banner
  Total payment:         10000 points
  Platform fee:          1000 points (10% rake)
  Campaign budget:       9000 points
  Payout rate:           10 points/impression

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

Surface types available: banner, video, rewarded

List all campaigns:

buddo campaigns list

5. Check your billing

buddo billing balance

Expected output:


  Balance      : 1,000,000 pts
  Daily burn   : 333 pts/day (estimated from last 30 transactions)
  Runway       : 3003 days

View your transaction history:

buddo billing history

View per-app billing status:

buddo billing apps

Next steps