CLI Reference

The corral command-line interface provides full control over your local development environment. Every feature available in the macOS app is also available from the terminal.

Global Flags

Flag	Description
--json	Output results as JSON instead of formatted text
--data-dir <path>	Override the data directory (default: ~/.corral)

The data directory can also be set via the CORRAL_DATA_DIR environment variable.

Project Resolution

Commands that accept a <project> argument resolve it in this order:

1. UUID — exact match
2. Name — exact match (case-insensitive)
3. Substring — if the input matches part of a project name (must be unambiguous)

If a substring matches multiple projects, the command will error and ask you to be more specific.

---

Lifecycle

corral up

Start infrastructure (DNS + reverse proxy) and all auto-start projects.

corral up

corral down

Stop all running projects and infrastructure.

corral down

corral status

Show infrastructure state and running projects.

corral status

corral start <project>

Start a single project.

corral start my-worker

corral stop <project>

Stop a running project.

corral stop my-worker

corral restart <project>

Stop and restart a project.

corral restart my-worker

---

Projects

corral project list

List all registered projects with their path, subdomain, auto-start status, and current state.

corral project list

corral project add <path>

Register a project directory. Corral detects the wrangler config and parses it automatically.

corral project add ./my-worker
corral project add /Users/me/code/api-service

corral project remove <project>

Unregister a project. Does not delete any files.

corral project remove my-worker

corral project info <project>

Show detailed project information: ID, path, type, bindings, settings, and running state.

corral project info my-worker

corral project scan <directory>

Find all directories containing a wrangler config file.

corral project scan ~/code/cloudflare

corral project refresh <project>

Re-read the wrangler config from disk. Useful after editing wrangler.toml.

corral project refresh my-worker

corral project set <project> <key> <value>

Update a project setting.

corral project set my-worker node-version 22
corral project set my-worker subdomain api
corral project set my-worker environment staging
corral project set my-worker auto-start true

Available keys: node-version, subdomain, environment, auto-start

Clearing a value: use none for optional fields:

corral project set my-worker node-version none

Boolean values: true/false, yes/no, 1/0, on/off

---

Node.js

corral node list

Show installed Node.js versions.

corral node list

corral node available

Show Node.js versions available for download (20 most recent).

corral node available
corral node available --lts

Flag	Description
--lts	Show only LTS releases

corral node install <version>

Download and install a Node.js version.

corral node install 22.3.0
corral node install 22
corral node install lts

corral node remove <version>

Remove an installed Node.js version.

corral node remove 22.3.0

---

Command Execution

corral exec <command> [args...]

Run a command using the resolved Node.js version for the current directory.

corral exec node -v
corral exec npx vitest run

Flag	Description
--node-version <version>	Override version resolution

Also respects the CORRAL_NODE_VERSION environment variable (flag takes precedence).

TIP

corral exec replaces the current process — it does not wrap or fork. Exit codes and signals pass through directly.

corral npm [args...]

Shorthand for corral exec npm.

corral npm install
corral npm run build

corral npx [args...]

Shorthand for corral exec npx.

corral npx vitest
corral npx wrangler deploy

---

Shell Shims

corral install-shims

Install node, npm, npx shims to ~/.corral/bin/.

corral install-shims

Flag	Description
--patch-profile	Add ~/.corral/bin to PATH in your shell profile

corral uninstall-shims

Remove shims and undo shell profile changes.

corral uninstall-shims

---

Uninstall

corral uninstall

Completely remove Corral and all its data from macOS. This performs a full cleanup:

1. Removes the CA certificate from the system keychain
2. Kills any orphaned Caddy and dnsmasq processes
3. Removes the DNS resolver file (/etc/resolver/{tld})
4. Removes the privileged helper daemon
5. Deletes the data directory (~/.corral)
6. Clears app preferences
7. Removes shell profile shims
8. Removes the CLI symlink (/usr/local/bin/corral or ~/.corral/bin/corral)

corral uninstall

You will be prompted for confirmation before anything is removed. Use --force to skip the prompt:

corral uninstall --force

Flag	Description
--force	Skip the confirmation prompt

WARNING

This is destructive and irreversible. All installed Node.js versions, project registrations, settings, and logs will be deleted.

---

Update

corral update

Check for and install the latest version of the CLI.

corral update

Flag	Description
--check	Check for updates without installing

corral update --check

TIP

If the CLI is part of the macOS app bundle, this command will tell you to update the app instead.

---

Install

corral install app

Download and install the macOS app to /Applications.

corral install app

Flag	Description
--force	Reinstall even if the app is already present

After installing, the CLI symlink is repointed to the binary inside the app bundle.

---

Logs

corral logs [project]

View logs. Omit the project name to see logs from all projects.

corral logs
corral logs my-worker

Flag	Short	Description
--follow	-f	Stream logs in real-time
--tail <n>	-t	Show only the last N entries (default: 50 in follow mode)
--search <query>	-s	Filter by text content (case-insensitive)

Examples:

# Stream all logs
corral logs --follow

# Last 10 entries from a project, then stream
corral logs my-worker -f -t 10

# Search across all logs
corral logs --search "error"

---

Settings

corral settings show

Display current app settings.

corral settings show

corral settings set <key> <value>

Update a setting.

corral settings set tld localhost
corral settings set auto-start true
corral settings set default-node-version 22
corral settings set port-range-start 9000

Available keys: tld, auto-start, default-node-version, port-range-start

Clear optional settings with none:

corral settings set default-node-version none

---

Infrastructure

corral infra start

Start DNS and proxy services.

corral infra start

corral infra stop

Stop DNS and proxy services.

corral infra stop

corral infra status

Show infrastructure state.

corral infra status

---

Data Inspection

corral data bindings <project>

Show a summary of all bindings and their local data status.

corral data bindings my-worker

corral data d1 tables <project> <binding>

List tables in a D1 database.

corral data d1 tables my-worker MY_DB

corral data d1 query <project> <binding> <table>

Query rows from a D1 table.

corral data d1 query my-worker MY_DB users
corral data d1 query my-worker MY_DB users --limit 20 --offset 40

Flag	Default	Description
--limit	50	Maximum rows to return
--offset	0	Row offset for pagination

corral data kv keys <project> <binding>

List keys in a KV namespace.

corral data kv keys my-worker MY_KV
corral data kv keys my-worker MY_KV --prefix user:

Flag	Default	Description
--prefix	(none)	Filter keys by prefix
--limit	50	Maximum keys to return
--offset	0	Key offset for pagination

corral data kv get <project> <binding> <key>

Get a KV entry's value.

corral data kv get my-worker MY_KV user:123

corral data r2 objects <project> <binding>

List objects in an R2 bucket.

corral data r2 objects my-worker MY_BUCKET
corral data r2 objects my-worker MY_BUCKET --prefix uploads/

Flag	Default	Description
--prefix	(none)	Filter objects by prefix
--limit	50	Maximum objects to return
--offset	0	Object offset for pagination

corral data do instances <project> <binding>

List Durable Object instances.

corral data do instances my-worker MY_DO