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.

All CLI commands communicate with a background daemon that manages process state. The daemon starts automatically on the first command — you don't need to start it manually.

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.

---

Daemon

The daemon is the background process that holds all running state. It starts automatically and stays alive until explicitly stopped.

corral daemon start

Start the daemon in the background. No-op if already running.

corral daemon stop

Stop the running daemon. Sends a graceful shutdown request, falls back to SIGTERM.

corral daemon status

Show whether the daemon is running, its PID, and the socket path.

---

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, git repository and branch, bindings, settings, and running state. Git information (repository URL, host, and current branch) is included when the project has a detected git remote.

corral project info my-worker

corral project scan <directory>

Find all directories containing a recognized project (Cloudflare, Next.js, Vite, etc.).

corral project scan ~/code

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
corral project set my-worker dev-command "npm run dev"
corral project set my-worker package-manager pnpm

Available keys: node-version, subdomain, environment, auto-start, dev-command, package-manager

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

corral project open <project>

Open the project's .test domain in your default browser.

corral project open my-worker

Flag	Description
--localhost	Open http://localhost:<port> instead of the .test domain (project must be running)

corral project open my-worker --localhost

corral project open-repo <project>

Open the project's git repository in your default browser.

corral project open-repo my-worker

The remote URL is detected when the project is added. If no git remote is found, the command will error and suggest running corral project refresh.

---

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

corral pm [args...]

Universal package manager command. Resolves the correct package manager for your project (npm, yarn, pnpm, or bun) and translates your command into the right syntax.

corral pm install
corral pm add react
corral pm add -D vitest
corral pm remove lodash
corral pm run dev
corral pm test

Flag	Description
--node-version <version>	Override Node.js version resolution
--about	Show which package manager would be used and why

Resolution order:

1. Per-project package-manager setting
2. Lockfile detection (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb/bun.lock)
3. App-wide default-package-manager setting
4. Fallback: npm

Bidirectional syntax: Both npm-style and yarn/pnpm-style commands work regardless of the underlying package manager:

# These do the same thing — add a dependency
corral pm install react    # npm style
corral pm add react        # yarn/pnpm style

# These do the same thing — remove a dependency
corral pm uninstall lodash # npm style
corral pm remove lodash    # yarn/pnpm style

Every invocation prints the resolved package manager to stderr (e.g., ▸ pnpm) so you always know what's running.

Diagnostics: Use --about to see the full resolution chain:

corral pm --about
#   Package manager    pnpm
#   Source             lockfile (pnpm-lock.yaml)
#   Project            my-api
#   Project override   (not set)
#   App default        npm
#   Node.js            v22.14.0

TIP

After installing shims, you can use cpm as a shorthand for corral pm:

cpm install
cpm add -D vitest
cpm run dev

---

Shell Shims

corral install-shims

Install node, npm, npx, and cpm 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
corral settings set default-package-manager pnpm

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

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 d1 schema <project> <binding> <table>

Show column schema for a D1 table.

corral data d1 schema my-worker MY_DB users

Displays column name, type, nullable, default value, and primary key status.

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 r2 get <project> <binding> <key>

Download an R2 object. By default, writes raw bytes to stdout (suitable for piping). Use --output to save to a file.

corral data r2 get my-worker MY_BUCKET image.png --output ./image.png
corral data r2 get my-worker MY_BUCKET config.json > config.json

Flag	Description
--output, -o	Write to a file instead of stdout

corral data do instances <project> <binding>

List Durable Object instances.

corral data do instances my-worker MY_DO

corral data do storage <project> <binding> <instance_id>

List storage entries for a Durable Object instance.

corral data do storage my-worker MY_DO abc123def456
corral data do storage my-worker MY_DO abc123def456 --limit 20 --offset 0

Flag	Default	Description
--limit	50	Maximum entries to return
--offset	0	Entry offset for pagination

corral data secrets list <project> <binding>

List secrets in a Secrets Store binding.

corral data secrets list my-worker API_KEY

Flag	Default	Description
--limit	50	Maximum secrets to return
--offset	0	Secret offset for pagination

corral data secrets get <project> <binding> <name>

Get a secret's value.

corral data secrets get my-worker API_KEY my-api-key

corral data secrets create <project> <binding> <name>

Create a secret. The value is read from stdin — in an interactive terminal you will be prompted, or you can pipe it:

corral data secrets create my-worker API_KEY my-api-key
echo "sk-1234" | corral data secrets create my-worker API_KEY my-api-key

corral data secrets delete <project> <binding> <name>

Delete a secret.

corral data secrets delete my-worker API_KEY my-api-key

corral data workflow instances <project> <binding>

List workflow instances with status, step count, and size.

corral data workflow instances my-worker MY_WORKFLOW

corral data workflow detail <project> <binding> <instance_id>

Show details for a workflow instance including steps, params, and status.

corral data workflow detail my-worker MY_WORKFLOW abc123def456

---

Shell Completions

corral completions <shell>

Generate shell completion scripts. Supported shells: bash, zsh, fish.

# Zsh (add to ~/.zshrc)
corral completions zsh > ~/.corral/_corral
fpath=(~/.corral $fpath)

# Bash (add to ~/.bashrc)
corral completions bash > ~/.corral/corral.bash
source ~/.corral/corral.bash

# Fish
corral completions fish > ~/.config/fish/completions/corral.fish

---

Diagnostics

corral doctor

Run a system health check. Verifies that all infrastructure components are configured and responding.

corral doctor

Checks performed:

Check	What it verifies
Daemon	Background daemon is running
DNS resolver	/etc/resolver/{tld} file exists
dnsmasq	DNS server is responding on 127.0.0.1
Caddy	Reverse proxy is responding
Node.js	At least one version is installed
Shims	Shell shims are installed and in PATH

Each check reports pass or fail with an actionable message on failure. Use --json for machine-readable output.