Cloud Workflow

The cloud workflow extends your local DebugBundle setup with cloud-hosted incident management. Events are delivered to the DebugBundle API, processed by cloud workers, and accessible to your entire team via CLI, API, MCP, or the web dashboard.

Prerequisites

Before connecting to the cloud, ensure you have:

1. A local project set up with debugbundle setup (see CLI Setup)
2. A DebugBundle account — sign up at debugbundle.com
3. The CLI installed and authenticated

Authenticate

The CLI stores a normal member token in ~/.debugbundle/auth.json. You can bootstrap that state in three ways:

# Interactive chooser
debugbundle login

# Direct member token
debugbundle login dbundle_mem_xxxxxxxxxxxx

# Auto mode: try `gh auth token` first, then fall back to GitHub device flow
debugbundle login --github

# Explicit modes
debugbundle login --github-cli
debugbundle login --github-device

The CLI and local MCP server both reuse this stored auth state for cloud operations. In a normal terminal, debugbundle login with no flags prompts you to choose one of these bootstrap paths.

Connect to Cloud

Link your local project to a cloud project:

debugbundle connect

If local member auth is missing, debugbundle connect now prompts for login first and then resumes automatically after authentication completes.

The connect command:

1. Reads your local profile from .debugbundle/profile.json
2. Creates or selects a matching cloud project
3. Generates a project token (shown once — copy it immediately)
4. Updates .debugbundle/local/connection.json with the cloud configuration

Connection Configuration

After connecting, your .debugbundle/local/connection.json looks like:

{
  "mode": "connected",
  "cloud_project_id": "proj_01HXYZ...",
  "cloud_base_url": "https://api.debugbundle.com",
  "environments": {
    "local": { "delivery": "local-only" },
    "development": { "delivery": "local-only" },
    "staging": { "delivery": "local-only" },
    "production": { "delivery": "cloud-enabled" }
  }
}

Environment Delivery Policy

Each environment can independently choose its delivery mode:

By default, production uses cloud delivery and everything else stays local. Edit .debugbundle/local/connection.json to customize.

Verify Cloud Connection

Confirm that events are reaching the cloud:

debugbundle verify cloud \
  --project-id proj_01HXYZ... \
  --service api-server \
  --environment production

The verify command polls for recent incidents from the specified project, service, and environment. It reports:

• Healthy — Recent events found within the time window
• Warning — No events found, but connection appears valid
• Error — Authentication or connectivity issues detected

For an active end-to-end proof, have the CLI create a temporary project token, send a synthetic request event through hosted ingestion, poll for the incident and bundle, then revoke the temporary token:

# Prove the standard 5xx request-failure path
debugbundle verify cloud --project-id proj_01HXYZ... --trigger-5xx

# Prove a configured client-error incident path
debugbundle verify cloud --project-id proj_01HXYZ... --trigger-4xx 403

--trigger-4xx accepts an integer status from 400 through 499 and succeeds only when the project capture policy promotes that status, such as 403 in immediate_client_error_statuses. It cannot be combined with --trigger-5xx.

When you want to prove the real application path instead of the synthetic CLI-generated event, trigger a known SDK event in your app and run:

debugbundle verify cloud \
  --project-id proj_01HXYZ... \
  --expect-app-event \
  --service api-server \
  --environment production \
  --trace-id trace_123

--expect-app-event waits for a recent hosted incident from the requested app surface. Add --trace-id or --request-id when you have them so the CLI can match the resulting bundle deterministically instead of relying on timing alone.

Options

Cloud Incident Management

Once connected, all incident commands work with both local and cloud data:

List Incidents (Merged View)

debugbundle incidents

By default, this shows active incidents from all sources (local + cloud). Active means open or regressed. Use --source to filter, or --status all to include resolved incidents:

# Cloud incidents only
debugbundle incidents --source cloud

# Local incidents only
debugbundle incidents --source local

You can also filter for incidents that first opened or regressed after a specific time:

debugbundle incidents --attention-after 2026-06-19T00:00:00.000Z

Inspect a Cloud Incident

debugbundle inspect inc_01HXYZ...

Works identically for local and cloud incidents. The CLI detects the source automatically based on the incident ID format.

Resolve / Reopen

debugbundle resolve inc_01HXYZ...
debugbundle reopen inc_01HXYZ...

You can pass multiple incident ids to resolve or reopen a selected set in one hosted bulk request:

debugbundle resolve inc_01HXYZ... inc_01HABC...
debugbundle reopen inc_01HXYZ... inc_01HABC...

Resolving or reopening cloud incidents updates the status in the cloud database, visible to all team members.

Cloud Log Watching

Send log events directly to the cloud:

debugbundle watch --cloud \
  --log /var/log/myapp/error.log \
  --format php-error

The --cloud flag sends parsed events to the ingestion API instead of writing them locally. Requires:

• connection.json with mode: "connected"
• DEBUGBUNDLE_PROJECT_TOKEN environment variable set

See Log Ingestion for format details.

SDK Configuration for Cloud

Set the project token in your SDK initialization:

const debugbundle = require('@debugbundle/sdk-node');

debugbundle.init({
  projectToken: process.env.DEBUGBUNDLE_PROJECT_TOKEN,
  environment: 'production',
});

The SDK automatically detects the transport mode from the environment. When projectToken is set and the environment allows cloud delivery, events go to the ingestion API.

Project Management

Manage projects from the CLI:

# List all projects
debugbundle project list

# Create a new project
debugbundle project create --name "Backend API" --slug backend-api

# Update a project
debugbundle project update proj_01HXYZ... --name "Backend API v2"

# Delete a project
debugbundle project delete proj_01HXYZ...

Probe Management

Activate debug probes to collect additional diagnostic data from SDKs without redeployment:

# Activate a probe
debugbundle probe activate \
  --project-id proj_01HXYZ... \
  --label-pattern "auth.*" \
  --service api-gateway \
  --ttl 3600

# List active probes
debugbundle probe list --project-id proj_01HXYZ...

# Deactivate a probe
debugbundle probe deactivate --project-id proj_01HXYZ... --activation-id prb_01H9KL...

After a downgrade to Free, probe list remains readable and probe deactivate still works as cleanup for preserved activations. New remote probe activation stays paused until the project returns to Solo or Team.

These commands have equivalent MCP tools: activate_probe, list_active_probes, deactivate_probe.

Health Check Management

Create hosted availability checks for public endpoints that should open normal DebugBundle incidents when they stay unreachable:

# List saved checks and plan limits
debugbundle health checks list --project-id proj_01HXYZ... --json

# Test a target without creating incidents or retained history
debugbundle health checks test \
  --project-id proj_01HXYZ... \
  --url https://app.example.com/health \
  --method GET \
  --json

# Create a saved hosted health check
debugbundle health checks create \
  --project-id proj_01HXYZ... \
  --name "Primary app" \
  --url https://app.example.com/health \
  --interval-seconds 60 \
  --failure-threshold 3 \
  --recovery-threshold 2 \
  --environment production \
  --service web \
  --json

Use health checks results <check-id> for recent raw executions and health checks daily-rollups <check-id> for retained per-day status history. Disable a saved check with health checks update <check-id> --enabled false when you want the configuration to remain visible but stop executing.

Free projects can keep 1 check at a minimum 300-second interval, Solo projects can keep 5 checks at a minimum 60-second interval, and Team projects can keep 25 checks at a minimum 30-second interval. After downgrade, saved checks remain readable, but checks beyond the current count or interval limits pause until the project becomes eligible again.

These commands have equivalent MCP tools: list_health_checks, test_health_check, create_health_check, update_health_check, list_health_check_results, and list_health_check_daily_rollups.

Project Member Management

Manage collaborator access for a specific project:

# List project members
debugbundle project members list --project-id proj_01HXYZ...

# List pending project invitations
debugbundle project members invites --project-id proj_01HXYZ...

# Invite a collaborator
debugbundle project members invite --project-id proj_01HXYZ... --email dev@example.com --role member

# Cancel a pending project invitation
debugbundle project members cancel-invite --project-id proj_01HXYZ... inv_01HXYZ...

# Update a project member's role
debugbundle project members update-role --project-id proj_01HXYZ... usr_01HXYZ... --role admin

# Remove a project member
debugbundle project members remove --project-id proj_01HXYZ... usr_01HXYZ...

Troubleshooting

Next Steps

• Token Management — Create and manage project and member tokens
• Webhook Management — Set up webhook notifications for incidents
• Alert Management — Configure alert channels for your team
• Availability Checks — Monitor public endpoints from DebugBundle infrastructure
• API Overview — Full API reference for cloud operations