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:

| Concept | Description |
|---------|-------------|
| **zbpack** | Auto-detect build tool. Identifies language/framework, generates Dockerfile. |
| **Region** | Deployment location. Common: `aws-us-west`, `aws-ap-east` (HK), `aws-ap-northeast` (JP/TW), `gcp-asia-east` (TW). Selected at project creation, cannot be changed later. |

## 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](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).

```bash
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](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](references/api-reference.md).

## Configuration

For complete configuration details (zbpack.json, template YAML, environment variables, predefined variables, volumes), read [references/deployment.md](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

| Type | Pattern |
|------|---------|
| Public HTTP | Bind domain via Dashboard/CLI. Auto-SSL. |
| Auto domain | `service-name.zeabur.app` |
| Custom domain | CNAME to zeabur. Apex domain: use Cloudflare CNAME flattening or A record. |
| Private (internal) | `[service-name].zeabur.internal` — same project only, no bandwidth cost. |
| Non-HTTP (TCP) | Assigned hostname + port (e.g., `hkg1.clusters.zeabur.com:34567`) |

**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](references/deployment.md).

## Troubleshooting

For common issues and diagnostic steps, read [references/troubleshooting.md](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](references/recipes.md).

## Operations

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