CLI Command Reference

Authenticate with the Buddo platform via OAuth 2.0 PKCE. Opens your browser; your password never touches the CLI. Token is saved to ~/.config/buddo/credentials.json and auto-refreshed.

Usage:

buddo login [--token <JWT>]

Example (browser flow):

$ buddo login
Opening your browser for authentication…
Waiting for authentication (timeout: 2 minutes)…
Exchanging authorization code for tokens…
Logged in as alice (alice@example.com)

Example (token flow):

$ buddo login --token eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Verifying token…
Logged in as alice (alice@example.com)

List all operator apps registered to your account.

buddo apps list [--json]

Example:

$ buddo apps list
ID                                    Name            Status    Scopes
ae82729e-c708-448c-8361-cde45318a5be  my-app          approved  profile:read, points:read
da45057c-0d6d-44ae-be5f-6b6e2adf6a0c  slots-sidecar   approved  points:spend, points:read

Register a new OAuth application with the Buddo platform.

buddo apps create --name <name> [--scopes <scopes>] [--redirect-uris <uris>] [--json]

Available scopes:

• profile:read — Read user profile
• points:read — Read user point balance
• points:spend — Spend user points
• points:transfer — Transfer points between users
• deploy:manage — Deploy and manage hosted apps
• app:balance:read — Read the operator app point balance
• campaigns:manage — Manage operator ad campaigns

Example:

$ buddo apps create --name "My Store" --scopes "profile:read,points:spend,deploy:manage"

App created successfully!
------------------------------------------------------------
  App Name:            My Store
  Client ID:           f47ac10b-58cc-4372-a567-0e02b2c3d479
  Client Secret:       s3cr3t...  (copy now — not shown again)
  Scopes:              profile:read, points:spend, deploy:manage
  Redirect URIs:       http://localhost:3000/callback
  Status:              approved
------------------------------------------------------------

Deploy a containerised app to buddocloud. Reads buddo.json in the current directory; flags override config file values.

buddo deploy [--config <path>] [--name <name>] [--image <image>] [--port <port>]

buddo.json schema:

{
  "app": {
    "name": "my-app"
  },
  "deploy": {
    "image": "myregistry/my-app:latest",
    "port": 3000,
    "env": {
      "KEY": "value"
    }
  }
}

Example:

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

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

Stop a running deployment. The container is terminated but the app record is preserved (use buddo deploy restart to restart it). Prompts for confirmation unless --force is passed.

buddo deploy stop <app-id> [--force]

Example:

$ buddo deploy stop d8f3a1c2
Stop deployment "d8f3a1c2"? This will terminate the running container. [y/N] y
Stopping d8f3a1c2 ...
Deployment d8f3a1c2 stopped.

Restart a running or stopped deployment.

buddo deploy restart <app-id>

Example:

$ buddo deploy restart d8f3a1c2
Restarting d8f3a1c2 ...
Deployment d8f3a1c2 restarting.
  Status: running

Fetch log output for a deployment.

buddo deploy logs <app-id> [--follow]

Example:

$ buddo deploy logs d8f3a1c2
[2026-06-01 12:00:01] Server listening on :3000
[2026-06-01 12:00:03] Database connected
[2026-06-01 12:01:15] GET /health 200 1ms

Permanently remove a deployment and all its resources. Unlike stop, destroy cannot be undone. Prompts for confirmation unless --force.

buddo deploy destroy <app-id> [--force]

Example:

$ buddo deploy destroy d8f3a1c2
Permanently destroy deployment "d8f3a1c2"? This cannot be undone. [y/N] y
Destroying d8f3a1c2 ...
Deployment d8f3a1c2 destroyed.

List all ad campaigns for your operator account.

buddo campaigns list [--json]

Example:

$ buddo campaigns list
ID                                    Name              Status    Surface     Budget        Spent
550e8400-e29b-41d4-a716-446655440000  Summer Launch     active    banner      9000          3200
a716c400-e29b-550e-41d4-446655441111  Winter Promo      paused    video       18000         8100

Create a new ad campaign. The --budget is the total points you pay (gross); the platform takes a 10% rake, so your effective campaign budget is 90% of this value.

buddo campaigns create --name <name> --budget <points> --surface <type> [--payout-rate <pts>] [--json]

Example:

$ buddo campaigns create --name "Holiday Promo" --budget 50000 --surface rewarded --payout-rate 20

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

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

Pause an active campaign. The campaign stops serving ads until resumed. Only active campaigns can be paused.

buddo campaigns pause <campaign-id> [--json]

Example:

$ buddo campaigns pause 550e8400-e29b-41d4-a716-446655440000
Campaign paused.
  ID:     550e8400-e29b-41d4-a716-446655440000
  Name:   Holiday Promo
  Status: paused

Resume a paused campaign. Only paused campaigns can be resumed.

buddo campaigns resume <campaign-id> [--json]

Example:

$ buddo campaigns resume 550e8400-e29b-41d4-a716-446655440000
Campaign resumed.
  ID:     550e8400-e29b-41d4-a716-446655440000
  Name:   Holiday Promo
  Status: active

Cancel a campaign. Unspent budget is refunded to your app account. The platform rake (10%) is non-refundable.

buddo campaigns cancel <campaign-id> [--json]

Example:

$ buddo campaigns cancel 550e8400-e29b-41d4-a716-446655440000
Campaign cancelled.
  ID:     550e8400-e29b-41d4-a716-446655440000
  Name:   Holiday Promo
  Status: cancelled
  Refund: 31800 points returned to your app account.

Show ad impression data. The server returns operator-level 30-day aggregates; per-campaign impression breakdowns are not yet exposed by the API.

buddo analytics impressions [<campaign-id>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--json]

Example:

$ buddo analytics impressions --since 2026-05-01 --until 2026-05-31
Analytics — Impressions
Window requested: 2026-05-01 to 2026-05-31
────────────────────────────────────────────────────────────
  Total Users (last 30d):            142
  Total Spend Events (last 30d):     3841
  Total Award Events (last 30d):     3841

  Note: Per-campaign impression counts are not yet exposed by the API.
  Showing operator-level 30-day totals from GET /api/operator/analytics.

Show ad click data. Returns operator-level 30-day aggregates.

buddo analytics clicks [<campaign-id>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--json]

Example:

$ buddo analytics clicks
Analytics — Clicks
Window requested: 2026-05-26 to 2026-06-02
────────────────────────────────────────────────────────────
  Total Users (last 30d):            142
  Total Spend Events (last 30d):     3841
  Total Award Events (last 30d):     3841

Show campaign budget and spend data. Derived from campaign records (budget, spent, rake). Pass a campaign ID to see a single campaign; omit to see all campaigns.

buddo analytics spend [<campaign-id>] [--since YYYY-MM-DD] [--until YYYY-MM-DD] [--json]

Example:

$ buddo analytics spend
Analytics — Spend
Window: 2026-05-26 to 2026-06-02
──────────────────────────────────────────────────────────────────────────────────────────
  Campaign ID                           Surface              Budget              Spent           Rake
  --------------------------------------------------------------------------------------------------
  550e8400-e29b-41d4-a716-446655440000  rewarded              45,000             13,200          5,000
  a716c400-e29b-550e-41d4-446655441111  banner                18,000              8,100          2,000
──────────────────────────────────────────────────────────────────────────────────────────
  TOTAL (2 campaigns)                                         63,000             21,300          7,000

Show the current Buddo point balance for your operator app, plus a runway estimate derived from your last 30 billing transactions.

buddo billing balance [--json]

Runway calculation: runway_days = balance / daily_burn. Zero or no burn rate returns unlimited; negative balance returns overdue.

Example:

$ buddo billing balance

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

JSON output:

$ buddo billing balance --json
{
  "balance_points": 1000000,
  "daily_burn_points": 333,
  "runway_days": "3003"
}

List recent billing transactions for your operator app.

buddo billing history [--limit <n>] [--json]

Example:

$ buddo billing history --limit 5

  Showing 5 of 48 transactions

  Date                  Amount (pts)    Type                Description
  ------------------------------------------------------------------------------------------
  2026-06-01 12:00      -10,000         campaign_debit      Campaign: Holiday Promo
  2026-05-31 09:15      +500,000        top_up              Manual top-up
  2026-05-30 14:22      -5,000          campaign_debit      Campaign: Summer Launch
  2026-05-29 11:08      -1,000          hosting_fee         Hosting: my-app (monthly)
  2026-05-28 10:00      -3,000          campaign_debit      Campaign: Summer Launch

  Running balance (this page): 481,000 pts

List all deployed apps with their current billing status.

buddo billing apps [--json]

Billing status values:

• active — App is running and billing normally
• billing-paused — App is stopped; billing is not accruing
• billing-failed — App was stopped automatically due to insufficient balance
• pending — App is being provisioned
• error — App is in an error state

Example:

$ buddo billing apps

  App Name                        Billing Status    Deploy Status   URL
  ----------------------------------------------------------------------------------------------------
  my-app                          [+] active         running         https://my-app.apps.buddocloud.com
  old-store                       [-] billing-paused stopped         https://old-store.apps.buddocloud.com

Show your operator app registration status and all deployed apps.

buddo status [--json]

Example:

$ buddo status
Operator App
────────────────────────────────────────────────────────────
  Client ID:         ae82729e-c708-448c-8361-cde45318a5be
  Status:            approved
  Scopes:            profile:read, points:read, deploy:manage
  Total Users:       142

Deployments
────────────────────────────────────────────────────────────
  App Name                  ID                    Status      URL                             Last Deploy
  ----------------------------------------------------------------------------------------------------
  my-app                    d8f3a1c2...           running     https://my-app.apps.budd...     2026-06-01 12:00 UTC

Print the CLI version.

buddo version [--json]

Example:

$ buddo version
buddo version v2.0.0

$ buddo version --json
{
  "version": "v2.0.0"
}