Zeabur

Zeabur Assistant

Tool Priority

When both CLI and GraphQL API (or MCP) can accomplish a task, prefer CLI (npx zeabur). Fall back to GraphQL API when:

• CLI command forces interactive selection that cannot be bypassed (e.g., project delete, service ls without working context)
• The operation requires custom query fields not available via CLI output
• CLI command fails or returns insufficient information

Priority order: CLI > GraphQL API > MCP

CLI interactive limitation: Many CLI commands ignore --id/--name flags and force interactive project/service selection, which fails in non-interactive environments. When this happens, fall back to GraphQL API immediately — do not retry the same CLI command.

Core Concepts

Project, Service, Environment, and Deployment follow standard cloud platform semantics. Key platform-specific concepts:

Deployment Decision Tree

User wants to deploy →
├─ Has GitHub repo?
│  └─ Yes → GitHub integration (auto CI/CD on push)
├─ Has Dockerfile or Docker image?
│  ├─ Image on registry → Docker image deploy
│  └─ Dockerfile in repo → Dockerfile deploy (auto-detected)
├─ Local source code only?
│  └─ `npx zeabur deploy` (interactive) or Dashboard drag-drop
├─ Multi-service stack (app + db + cache)?
│  └─ Template YAML (define all services in one spec)
└─ Simple function (single endpoint)?
   └─ Functions (serverless JS/Python)

Authentication

Always check auth status first with npx zeabur auth status.

If not logged in, ask the user which method to use:

1. API Token — User provides a token (from Dashboard > Settings > API Keys). Login via npx zeabur auth login --token <TOKEN>. This enables all CLI commands without browser interaction. If CLI token login fails, fall back to GraphQL API with Authorization: Bearer {TOKEN} header.
2. Interactive CLI login — Run npx zeabur auth login. Requires browser interaction from the user.

Token expiry: If previously authenticated commands start returning 401/unauthorized, the token may have expired. Re-run npx zeabur auth status to confirm, then re-authenticate. See references/troubleshooting.md for detailed auth troubleshooting.

CLI Quick Reference

All commands via npx zeabur. Add -i=false to disable interactive mode (for CI/CD).

npx zeabur auth login              # Authenticate
npx zeabur context set project     # Set working project
npx zeabur deploy                  # Deploy from local directory

For complete command reference with all flags and examples, read references/cli-commands.md.

API

GraphQL endpoint: https://api.zeabur.com/graphql Auth: Authorization: Bearer {TOKEN} (generate at Dashboard > Settings > API Keys)

For complete API reference including queries, mutations, REST upload API, and WebSocket terminal, read references/api-reference.md.

Configuration

For complete configuration details (zbpack.json, template YAML, environment variables, predefined variables, volumes), read references/deployment.md.

Key Points

• Build config: zbpack.json in project root — set build_command, start_command, app_dir, plan_type
• Env vars: Set via Dashboard, CLI, or template. Reference syntax: ${VAR_NAME}. Predefined: ${PORT} (8080), ${ZEABUR_WEB_URL}, ${PASSWORD}
• Override build: ZBPACK_IGNORE_DOCKERFILE=true, ZBPACK_DOCKERFILE_NAME=custom.Dockerfile

Networking

Important: With Cloudflare, do NOT use Full (Strict) SSL mode.

Data Management

• Volumes: Mount persistent storage at a path. $0.20/GB/month. Note: volumes disable zero-downtime restart.
• Config Editor: Edit config files at absolute paths (e.g., /etc/nginx/nginx.conf). Free.
• Backups: Online backup for PostgreSQL/MySQL/MariaDB/MongoDB. Auto-backup daily. 7-day retention.

For template YAML format, zbpack.json config, and deployment details, read references/deployment.md.

Troubleshooting

For common issues and diagnostic steps, read references/troubleshooting.md.

Quick Diagnostic Checklist

1. Auth failure → npx zeabur auth status — re-authenticate if token expired
2. Build failure → npx zeabur deployment log -t=build — check language detection, dependencies
3. Service unreachable → verify domain binding, port ($PORT env var), health check
4. DB connection fail → use private hostname (*.zeabur.internal), check exposed variables
5. Env var not working → check variable precedence, restart service
6. SSL error → Cloudflare users: switch from Full (Strict) to Full

Common Recipes

For step-by-step real-world scenarios (Next.js + PostgreSQL, monorepo deploy, staging/production setup, CI/CD pipeline, Docker image deploy), read references/recipes.md.

Operations

For cost optimization, high availability architecture, and MCP integration setup, read references/operations.md.