Connect to Cloud

The debugbundle connect command links your local project to DebugBundle Cloud, enabling team-wide incident visibility, webhooks, alerts, probes, and the web dashboard.

Prerequisites

• A DebugBundle account (sign up at app.debugbundle.com)
• CLI authenticated: debugbundle login
• An initialized local project: debugbundle setup

If you are not authenticated yet, debugbundle connect can now prompt you to log in first and then continue automatically.

Connect Flow

debugbundle connect

The connect command performs these steps automatically:

1. Reads your profile — extracts the project name from .debugbundle/profile.json
2. Prompts for login if needed — offers GitHub auto mode, GitHub device flow, or an existing member token when local auth is missing
3. Creates or selects a cloud project — uses the profile name to find an existing project or create a new one with a slugified name
4. Generates a project token — creates a write-only SDK token for event ingestion
5. Updates connection.json — switches mode to "connected" and enables cloud delivery for the production environment

Output

Connected DebugBundle project to cloud.
Created cloud project: my-app (proj_01HXYZ...)
Updated .debugbundle/local/connection.json with production cloud delivery defaults.
Local investigation artifacts remain available under .debugbundle/local/.
Project token:
dbundle_proj_a1b2c3d4...
Next steps:
- Set DEBUGBUNDLE_PROJECT_TOKEN=dbundle_proj_a1b2c3d4... in your production environment.
- Redeploy connected environments after updating their DebugBundle configuration.
- Use debugbundle incidents --source cloud after deployment to confirm hosted ingestion.

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" }
  }
}

Configuration Fields

Environment Delivery

Each environment independently controls whether events are delivered locally or to the cloud:

Default after connect:

• local, development, and staging → local-only (keep pre-production investigation local by default)
• production → cloud-enabled (team visibility where it matters)

You can change any environment's delivery mode by editing connection.json.

Verify Cloud Connection

After deploying with the project token, verify the connection:

debugbundle verify cloud --project-id proj_01HXYZ...

This checks:

• API is reachable
• Your member token is valid
• The cloud project exists and is accessible
• Recent events have been received within the verification window

To actively prove hosted incident creation, send a synthetic request event through the real ingestion path:

# Prove the standard 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

The 4xx proof succeeds only when the target project's capture policy promotes that status, for example with immediate_client_error_statuses containing 403.

To prove your real app-side SDK wiring instead of the synthetic path, trigger a known browser or backend SDK event and let the CLI wait for hosted visibility:

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

Use --trace-id or --request-id when you have a correlation hint from the app or browser network trace. That keeps the verification scoped to the event you intentionally triggered instead of any unrelated recent incident.

JSON Output

debugbundle verify cloud --project-id proj_01HXYZ... --json

{
  "status": "healthy",
  "checks": [
    { "name": "api_reachable", "status": "ok", "message": "API responded in 42ms" },
    { "name": "auth_valid", "status": "ok", "message": "Member token is valid" },
    { "name": "project_accessible", "status": "ok", "message": "Project proj_01HXYZ... is accessible" },
    { "name": "recent_events", "status": "ok", "message": "Last event received 3 minutes ago" }
  ],
  "warnings": [],
  "errors": [],
  "suggested_actions": [],
  "auto_fix_available": false
}

Merged Incident View

After connecting, you can view both local and cloud incidents together:

# Active incidents (both sources)
debugbundle incidents

# Cloud only
debugbundle incidents --source cloud

# Local only
debugbundle incidents --source local

Security

• Project tokens are write-only — they can only ingest events, not read data.
• Member tokens are used for CLI/API/MCP operations (read + manage).
• Tokens are hashed (SHA-256) before storage. Plaintext is shown once at creation.
• Cloud delivery uses HTTPS with TLS 1.2+.

Next Steps

• Project Setup — Setup overview
• Local-Only Mode — Return to local-only mode
• Capture Policy — Control event capture behavior
• CLI Cloud Workflow — Full cloud CLI workflow