Projects

A project in Corral is a Cloudflare Workers or Pages application that you've registered for local development. Corral reads the project's wrangler configuration, assigns it a local subdomain, and manages its dev server lifecycle.

Registering a Project

CLI:

corral project add ./my-worker

macOS App: Click the + button in the toolbar and select a folder, or drag a project folder onto the main window. Either way, the project is registered and automatically selected in the sidebar.

Corral will:

1. Detect and parse the wrangler config file
2. Determine the project type (Worker, Pages, or Durable Object)
3. Generate a URL-safe subdomain from the project name (e.g., my-worker)
4. Assign a unique ID for internal tracking

If the subdomain would collide with an existing project, Corral appends a suffix (my-worker-2, my-worker-3, etc.).

Scanning for Projects

If you keep your Cloudflare projects in a common parent directory, scan it to find them all at once:

corral project scan ~/code/cloudflare

This lists every immediate subdirectory that contains a wrangler.toml or wrangler.json. You can then register them individually.

What Gets Parsed

Corral reads your wrangler configuration to understand your project. This includes:

Project identity:

• name, main, compatibility_date, compatibility_flags
• Project type detection: Worker (has main), Pages (has pages_build_output_dir), Durable Object (has DO bindings)

Bindings:

• D1 Databases, KV Namespaces, R2 Buckets, Durable Objects
• Queues (producers and consumers), Service Bindings
• AI, Vectorize, Hyperdrive, Analytics Engine, Secrets Store

Additional configuration:

• Cron triggers, build commands, dev server settings
• Observability, CPU limits, routes, environment variables

Environments:

• Named environments defined under [environments] are detected and available for selection
• When you select an environment, its overrides are merged with the top-level configuration

Per-Project Settings

Each project has settings you can customize:

Setting	Description	Default
node-version	Node.js version override	Resolved via version chain
subdomain	Custom subdomain for domain routing	Auto-generated from project name
environment	Wrangler environment to use	None (uses top-level config)
auto-start	Start automatically with corral up	false

Set them via the CLI:

# Pin a Node.js version for this project
corral project set my-worker node-version 22

# Use a custom subdomain
corral project set my-worker subdomain api

# Select a wrangler environment
corral project set my-worker environment staging

# Start automatically with infrastructure
corral project set my-worker auto-start true

Use none to clear an optional setting:

corral project set my-worker node-version none

Or configure them in the macOS app under the project's Settings tab.

Refreshing Configuration

If you edit your wrangler.toml, tell Corral to re-read it:

corral project refresh my-worker

This updates the parsed configuration without removing or re-registering the project. Your project settings (subdomain, Node version, etc.) are preserved.

Removing a Project

corral project remove my-worker

This unregisters the project from Corral. It does not delete any files in your project directory.

Viewing Project Details

corral project info my-worker

Shows the project's ID, path, type, compatibility date, subdomain, current settings, and detected bindings.

Project Resolution

Whenever a command takes a <project> argument, you can use:

• The project's name (exact or substring match)
• The project's UUID

If a substring matches multiple projects, Corral will ask you to be more specific.