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.

Commands marked with PRO require an active Corral Pro license. Learn more →

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

Flag	Description
--host	Serve on the local network (bind to 0.0.0.0 instead of 127.0.0.1)

When --host is used, the dev server becomes accessible from other devices on your local network. Corral prints the network URL after starting:

corral start my-worker --host
# ok Started my-worker
#    network http://192.168.1.100:8787

corral stop <project>

Stop a running project.

corral stop my-worker

corral restart <project>

Stop and restart a project.

corral restart my-worker

Flag	Description
--host	Serve on the local network (bind to 0.0.0.0 instead of 127.0.0.1)

corral share <project>

Share a project to the internet via a Cloudflare Quick Tunnel. Prints a public https://*.trycloudflare.com URL that anyone can access.

If the project isn't running, Corral starts it first automatically.

corral share my-worker
# ok Sharing my-worker
#    public https://random-words.trycloudflare.com
#
#    This URL is ephemeral — it changes when the project restarts.

Flag	Description
--stop	Stop sharing instead of starting

corral share my-worker --stop
# ok Stopped sharing my-worker

The tunnel URL is ephemeral — it changes every time the tunnel restarts. Sharing requires no Cloudflare account and is completely free. The cloudflared binary is downloaded automatically on first use (~30 MB).

---

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 browser.

corral project open my-worker

Flag	Description
--localhost	Open http://localhost:<port> instead of the .test domain (project must be running)
--browser <name>	Open in a specific browser (e.g. "Google Chrome") instead of the preferred/default

corral project open my-worker --localhost
corral project open my-worker --browser "Firefox"

When --browser is not specified, Corral uses the preferred browser from settings. If no preferred browser is set, the system default is used.

corral project open-repo <project>

Open the project's git repository in your browser.

corral project open-repo my-worker

Flag	Description
--browser <name>	Open in a specific browser (e.g. "Google Chrome")

corral project open-repo my-worker --browser "Safari"

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.

TIP

The preferred-browser setting does not apply to open-repo — git repository URLs always open in the system default browser unless --browser is explicitly passed.

---

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 PRO

corral exec <command> [args...] PRO

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...] PRO

Shorthand for corral exec npm.

corral npm install
corral npm run build

corral npx [args...] PRO

Shorthand for corral exec npx.

corral npx vitest
corral npx wrangler deploy

corral pm [args...] PRO

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 PRO

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
corral settings set preferred-browser com.google.Chrome

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

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

---

Services PRO

corral service list

List installed services and their status (name, version, ports, state, auto-start). Services with more than one port render all of them in the PORTS column as role=port pairs (e.g. smtp=1025,web=8025).

corral service catalog

Show available services from the remote catalog, grouped by category.

corral service install <name>

Install a service. Downloads the binary, verifies the checksum, and extracts it.

Services that support concurrent multi-version installs (e.g. postgres, mariadb) accept a name@version argument and install side-by-side with any other installed majors; each gets its own port and its own isolated data directory. The version component can be exact ([email protected], [email protected]) or a prefix (postgres@16 resolves to the newest 16.x; [email protected] resolves to the newest 11.4.x). Bare name resolves to the catalog's default version for the install.

LTS-aware default-version resolution. For services with multiple LTS branches in flight (mariadb today: 10.11, 11.4, 11.8 LTS plus rolling 12.x), the bare-name install resolves to the newest LTS rather than the newest version overall — corral service install mariadb lands on the latest 11.8.x (or whichever LTS is currently freshest), not on a rolling 12.x release. This is per-service catalog metadata (lts_branches + default_version_policy), so it doesn't change behavior for services like postgres where every supported major is itself a long-term branch.

Flag	Description
--version <version>	Legacy equivalent of the @<version> suffix; accepts the same exact/prefix forms.

corral service uninstall <name>

Uninstall a service. Removes the binary but keeps the data directory by default. For multi-version services, target a specific install with name@version (e.g. corral service uninstall postgres@15) — other installed versions are untouched.

Flag	Description
--delete-data	Also remove the service's data directory

corral service start <name>

Start a stopped service. Accepts name@version to target a specific installed version of a multi-version service.

corral service stop <name>

Stop a running service. Accepts name@version to target a specific installed version of a multi-version service.

corral service restart <name>

Restart a service (stop then start). Accepts name@version to target a specific installed version of a multi-version service.

corral service info <name>

Show service details: version, port(s), status, connection string, environment variables, web UI URL (if any), auto-start, data and install paths. Accepts name@version.

If a bare name is passed for a service with multiple installed versions and no default-version set, the command errors with AmbiguousVersion and lists the installed candidates.

corral service set <name> <key> <value>

Update a service setting.

Key	Values	Description
port	Number >= 1024	Port the service listens on. Only valid for single-role services whose sole role is main (e.g. Valkey, Meilisearch).
port.<role>	Number >= 1024	Port for a specific role on any service with named roles: port.smtp 1026 / port.web 8030 (Mailpit), port.sql 5433 (PostgreSQL), port.sql 3307 (MariaDB — same sql role name as Postgres), port.http 9201 / port.transport 9301 (OpenSearch), port.api 9100 / port.console 9101 (MinIO), port.api 8200 / port.peering 8201 (Typesense). Each port must be >= 1024 and unique across roles.
auto-start	true/false	Start automatically with the daemon
default-version	Version string, or - to unset	For services with concurrent multi-version installs, the version resolved by bare-name lookups (e.g. corral service start postgres). - unsets, after which bare names fail with AmbiguousVersion when 2+ versions are installed.

JSON output

corral service list --json and corral service info --json emit a RunningServiceInfo record per service:

{
  "name": "mailpit",
  "display_name": "Mailpit",
  "version": "1.29.7",
  "service_ref": "[email protected]",
  "is_default": true,
  "ports": {"smtp": 1025, "web": 8025},
  "state": "Running",
  "auto_start": false,
  "connection_string": "smtp://127.0.0.1:1025",
  "env_vars": [
    {"key": "SMTP_HOST", "value": "127.0.0.1"},
    {"key": "SMTP_PORT", "value": "1025"},
    {"key": "SMTP_FROM", "value": "corral@localhost"}
  ],
  "web_ui_url": "http://127.0.0.1:8025",
  "data_dir": "/Users/you/.corral/services/mailpit/1.29.7/data",
  "install_dir": "/Users/you/.corral/services/mailpit/1.29.7"
}

For services with multiple installed versions, list emits one record per (service, version) pair — each with its own service_ref and is_default flag. Example for a machine that has Postgres 16 and 17 side-by-side with 16 marked default:

[
  {
    "name": "postgres",
    "display_name": "PostgreSQL",
    "version": "16.4.1",
    "service_ref": "[email protected]",
    "is_default": true,
    "ports": {"sql": 5432},
    "state": "Running",
    "auto_start": true,
    "connection_string": "postgresql://[email protected]:5432/corral",
    "env_vars": [
      {"key": "DATABASE_URL", "value": "postgresql://[email protected]:5432/corral"},
      {"key": "PGHOST", "value": "127.0.0.1"},
      {"key": "PGPORT", "value": "5432"},
      {"key": "PGUSER", "value": "corral"},
      {"key": "PGDATABASE", "value": "corral"}
    ],
    "web_ui_url": null,
    "data_dir": "/Users/you/.corral/services/postgres/16.4.1/data",
    "install_dir": "/Users/you/.corral/services/postgres/16.4.1"
  },
  {
    "name": "postgres",
    "display_name": "PostgreSQL",
    "version": "17.2.0",
    "service_ref": "[email protected]",
    "is_default": false,
    "ports": {"sql": 5433},
    "state": "Stopped",
    "auto_start": false,
    "connection_string": "postgresql://[email protected]:5433/corral",
    "env_vars": [],
    "web_ui_url": null,
    "data_dir": "/Users/you/.corral/services/postgres/17.2.0/data",
    "install_dir": "/Users/you/.corral/services/postgres/17.2.0"
  }
]

service_ref is the canonical name@version string — pass it straight back into any command that accepts name@version. is_default is the marker set by corral service set <name> default-version <version>, useful for scripting a "start the default" flow without having to re-read the registry.

Shape change since 0.2.9

Prior releases emitted "port": <number> as a top-level field. It is now "ports": {"<role>": <number>} to support multi-port services. Scripts that consumed the old shape should update their JSON path expression — e.g. jq '.port' becomes jq '.ports.main' for single-port services like Valkey. The env_vars and web_ui_url fields also date from this release. The service_ref and is_default fields, and the version-scoped data_dir path, were added alongside concurrent multi-version support (PostgreSQL, OpenSearch). The version_display field was added with the MinIO provider — it carries a human-friendly version label (MinIO trims its RELEASE.<ISO-8601> tag to a YYYY-MM-DD form), and falls back to version for services that don't override it.

---

Data Inspection PRO

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> PRO

List tables in a D1 database.

corral data d1 tables my-worker MY_DB

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

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> PRO

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> PRO

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> PRO

Get a KV entry's value.

corral data kv get my-worker MY_KV user:123

corral data r2 objects <project> <binding> PRO

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> PRO

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> PRO

List Durable Object instances.

corral data do instances my-worker MY_DO

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

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> PRO

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> PRO

Get a secret's value.

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

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

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> PRO

Delete a secret.

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

corral data workflow instances <project> <binding> PRO

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> PRO

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

corral data workflow detail my-worker MY_WORKFLOW abc123def456

---

License

corral license status

Show the current license status.

corral license status

Displays license status, customer info, device count, expiry date, and validation state. Shows "No license activated" if no license is present.

corral license activate <key>

Activate a Corral Pro license key on this device.

corral license activate 90F84D88-5A29-4AB4-8B27-E93602B0F274

Activates the license with the license server, stores the activation locally, and unlocks Pro features immediately.

corral license deactivate

Deactivate the license on this device, freeing the device slot.

corral license deactivate

Deactivates the license with the license server and removes the local license file. Use this before transferring your license to another device.

---

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.