Interactive CLI tool for deploying PACKAGE.broker to Cloudflare Workers
npm install @package-broker/cloudflareCLI tool for deploying PACKAGE.broker to Cloudflare Workers with one command. Supports both interactive and CI/CD modes.
``bash`
npm install @package-broker/cloudflare @package-broker/main
`bash`
npx package-broker-cloudflare init
The CLI will:
- Prompt for tier selection (free/paid)
- Prompt for worker name
- Generate encryption key
- Create Cloudflare resources (D1, KV, R2, Queue if paid)
- Set encryption key as Cloudflare secret
- Generate wrangler.toml with all IDs populated
- Copy migration files
- Optionally deploy the Worker
For non-interactive deployment in GitHub Actions or other CI environments:
`bash`
npx package-broker-cloudflare deploy --ci --json \
--worker-name my-worker \
--tier free \
--domain app.example.com
Required Environment Variables (CI mode):
- CLOUDFLARE_API_TOKEN - Cloudflare API token with required permissionsCLOUDFLARE_ACCOUNT_ID
- - Your Cloudflare account IDENCRYPTION_KEY
- - Base64-encoded encryption key
Optional Environment Variables:
- WORKER_NAME - Worker name (overrides --worker-name flag)CLOUDFLARE_TIER
- - free or paid (overrides --tier flag)DOMAIN
- - Custom domain (overrides --domain flag)SKIP_UI_BUILD
- - Set to true to skip UI build stepSKIP_MIGRATIONS
- - Set to true to skip migration application
Flags:
- --ci - Enable CI mode (non-interactive, no prompts)--json
- - Output JSON result for machine parsing--worker-name
- - Worker name--tier
- - Cloudflare tier--domain
- - Custom domain (e.g., app.example.com)--skip-ui-build
- - Skip UI build step--skip-migrations
- - Skip migration application
JSON Output (when using --json):`json`
{
"worker_url": "https://my-worker.workers.dev",
"database_id": "abc123...",
"kv_namespace_id": "def456...",
"r2_bucket_name": "my-worker-artifacts",
"queue_name": "my-worker-queue"
}
- Interactive setup: Guided prompts for configuration
- CI/CD mode: Non-interactive deployment with JSON output for automation
- Idempotent: Safe to re-run if resources already exist
- Automatic resource creation: D1, KV, R2, and Queue (paid tier)
- Secret management: Encryption key set as Cloudflare secret (not in wrangler.toml)
- Migration handling: Automatically copies and applies migrations
- Tier-aware: Different configuration for free vs paid tiers
- Wrangler version pinning: Enforces wrangler@^4.54.0 as dependency
- Node.js 18+
- Cloudflare account
- Authenticated with wrangler login (interactive mode) or CLOUDFLARE_API_TOKEN environment variable (CI mode)
If you see an error like:
``
[ERROR] Invalid Routes:
example.com/*:
This occurs when using custom domains. The custom_domain = true route type requires the pattern without the /* suffix. If you're using an older version, update to the latest:
`bash`
npm update @package-broker/cloudflare
On a fresh installation, you should see the Setup wizard (to create the first admin user). If you see the Login screen instead:
1. Check the API response:
`bash`
curl -s https://your-domain.com/api/auth/check | jq .
`
2. Expected response for fresh install:
json`
{"authRequired": false, "setupRequired": true}
3. If you see {"auth_required": false} (snake_case, missing setupRequired), you're running an old version. Update packages and redeploy.
If D1/KV/R2 resources are created but the Worker can't access them:
1. Check the wrangler.toml has correct IDs:`
bash`
grep -E "database_id|kv_namespaces|r2_buckets" wrangler.toml
2. Verify bindings in Cloudflare Dashboard: Workers & Pages → Your Worker → Settings → Bindings
3. Redeploy to apply binding changes:
`bash`
npx wrangler deploy
For debugging deployment issues, test locally before pushing to CI:
`bashSet credentials
export CLOUDFLARE_API_TOKEN="your-token"
export CLOUDFLARE_ACCOUNT_ID="your-account-id"
export ENCRYPTION_KEY="test-encryption-key-32-chars-min"
This gives immediate feedback without CI delays or NPM publishing.
- Quickstart Guide
- GitHub Template Repository (alternative deployment method)
- GitHub Action (uses this CLI in CI mode)