CLI and Scaffolding

Relevant source files

The following files were used as context for generating this wiki page:

• packages/create-statusbeam/src/index.ts
• packages/cli/src/commands/deploy.ts
• DEPLOYMENT.md
• ARCHITECTURE.md
• scripts/setup.sh
• README.md

StatusBeam utilizes a "package-based distribution" model where the core application logic is maintained in versioned packages, while user projects remain thin repositories containing only configuration and resource identifiers. This architecture avoids the complexities of upstream merges typical of fork-based status pages. The CLI and scaffolding tools are the primary interfaces for users to initialize, provision, and deploy their status pages.

Sources: ARCHITECTURE.md:120-123, README.md:213-219

Project Scaffolding with create-statusbeam

The scaffolding process is handled by the create-statusbeam package. It initializes a new project directory by copying a predefined template tree and customizing it based on user input. This tool is designed to create a "thin project" that depends on the @statusbeam/cli to manage deployments.

Scaffolding Logic

The scaffolder performs several critical operations during initialization:

1. Argument Parsing: It identifies the target directory, optional --name, and --yes (non-interactive) flags.
2. Template Copying: It copies the contents of the internal templates directory to the target.
3. Dependency Management: It generates a package.json that pins @statusbeam/cli to a version compatible with the scaffolder itself.
4. Configuration Injection: It prompts the user for a status page name and injects it into the status.config.yml file.
5. Environment Setup: It renames gitignore to .gitignore (bypassing npm's default stripping) and initializes a git repository.

Sources: packages/create-statusbeam/src/index.ts:1-125, DEPLOYMENT.md:14-20

Scaffolder Data Flow

The following diagram illustrates the flow from running the create command to a ready-to-use local project.

The StatusBeam CLI (@statusbeam/cli)

The CLI serves as the operational engine for a StatusBeam project. It abstracts the complexity of Cloudflare resource provisioning, D1 schema application, and Worker deployment.

Core Commands

Command	Description	Implementation Detail
setup	Provisions D1 + KV, configures wrangler.jsonc, and performs initial deploy.	Idempotent; wires resource IDs into user config.
deploy	Applies SQL schema, uploads YAML to KV, and deploys Workers.	Fuses user IDs/domains into build artifacts.
update	Bumps @statusbeam/* packages via the package manager.	Followed by deploy to ship new versions.

Sources: DEPLOYMENT.md:31-35, packages/cli/src/commands/deploy.ts:7-12

Deployment Workflow

The deploy command orchestrates a multi-stage process to ensure the Cloudflare environment matches the local configuration.

Setup and Provisioning Logic

The setup process, whether triggered via statusbeam setup or the setup.sh script in the monorepo, is designed to be idempotent. It handles the lifecycle of infrastructure on Cloudflare.

Resource Provisioning

1. D1 Lookup/Create: Checks for an existing database named statusbeam. If missing, it creates it and captures the UUID.
2. KV Lookup/Create: Checks for a STATUS_KV namespace. If missing, it creates it and captures the ID.
3. Wrangler Configuration: It writes these IDs, along with user-provided custom domains and cron schedules, into wrangler.worker.jsonc and wrangler.web.jsonc.

Sources: scripts/setup.sh:84-142, DEPLOYMENT.md:22-29

Configuration Splicing

The CLI uses the apply-config.ts utility to idempotently edit wrangler.jsonc files. This ensures that manually added settings in those files are preserved while automated resource IDs are updated.

// From scripts/setup.sh logic
D1_ID="$D1_ID" KV_ID="$KV_ID" CRON="$CRON" \
  SET_NETWORKING=1 CUSTOM_DOMAIN="$CUSTOM_DOMAIN" \
  bun scripts/apply-config.ts

Sources: scripts/setup.sh:144-148, packages/cli/src/commands/deploy.ts:16-18

Project Structure (Scaffolded)

A project generated by the scaffolding tools contains the following primary files:

File	Purpose
status.config.yml	The single source of truth for service monitoring and UI settings.
wrangler.worker.jsonc	Configuration for the Cron Worker (Prober).
wrangler.web.jsonc	Configuration for the Astro Status Page Worker.
package.json	Project metadata and scripts targeting the StatusBeam CLI.

Sources: packages/create-statusbeam/templates/README.md:1-20, README.md:154-159

Technical Constraints and Invariants

• Configuration Independence: The builds are configuration-independent. The CLI fuses the specific user's Cloudflare resource IDs into the deployment artifact, but the actual service list is read from KV at runtime.
• Authentication: The CLI requires a Cloudflare User API token (not account-owned) to perform D1 operations.
• Environment: The CLI and scaffolding tools are optimized for the Bun runtime and utilize wrangler for all Cloudflare interactions.

Sources: ARCHITECTURE.md:120-123, DEPLOYMENT.md:45-53, packages/create-statusbeam/src/index.ts:120-125

Summary

The CLI and scaffolding system enable a "Status Page as a Dependency" workflow. By separating application code from user configuration, StatusBeam allows for seamless updates via the CLI while maintaining a simple, YAML-driven user experience for monitoring services on Cloudflare's edge.