~/docs/cli/reference

╭─ § 05.01 ─╮

Command 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 → — or activate a license from the in-app Subscription room.

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:

UUID — exact match
Name — exact match (case-insensitive)
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. Renders a table of all units (projects, services, infrastructure) with their lifecycle, health, uptime, and ports.

corral status

Failed units display structured failure details — failure kind, diagnostic message, and suggested remediation. Cascade failures (failures triggered by an upstream dependency) show a link to the root cause.

With --json, the output includes full unit details: id, kind, display_name, lifecycle (Pending/Active/Idle/Failed/Abandoned), health (Nominal/Degraded/Critical), last_failure (with kind, message, trigger, remediation_actions), depends_on, and data_dir.

`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

If the project is a member of a running stack, Corral asks for confirmation first — stopping it would drop a member out from under a stack that still needs it. Pass -y / --yes to skip the prompt; non-interactive shells (pipes, --json) proceed without asking.

`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 retry <project>`

Retry a failed or abandoned project. This command is specifically for projects in a Failed or Abandoned state — it clears the failure record, resets the crash-loop counter, and runs the start path fresh.

corral retry my-worker

Use restart for a running project that needs to pick up config changes. Use retry when a project has failed and you’ve fixed the underlying issue (e.g., freed up a port, resolved a dependency, added disk space).

`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 list --ungrouped   # hide projects that belong to a stack

`corral project add <path>`

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, canonical URL, 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
corral project set my-worker address-mode localhost
corral project set my-worker localhost-port 5173
corral project set my-worker serve-proxy-route false

Available keys: node-version, subdomain, environment, auto-start, dev-command, package-manager, address-mode, localhost-port, serve-proxy-route

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

Address mode: address-mode accepts proxy (serve <name>.test, the default), localhost (also serve http://localhost:<port>), or localhost-tls (also serve https://localhost:<port>). Pair it with localhost-port (a port number, or none to auto-pick) and serve-proxy-route false to serve localhost only. See Serving a project at localhost.

`corral project open <project>`

Open the project’s canonical URL in your browser — its address-mode URL (<name>.test by default, or http(s)://localhost:<port> when the project uses a localhost address mode).

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.

Stacks

A stack is a runnable composition of projects and services — start or stop the whole group with one command, and see how its members wire together. Reads (list / status) are free; creating, editing, and running stacks are Corral Pro.

Stacks are either manual (you choose the members) or Cloudflare-derived (membership and wiring are read from each worker’s wrangler config and kept in sync). Every corral stack command also accepts --json.

`corral stack list`

List every stack with its aggregate status, origin (manual / cloudflare), and member count.

corral stack list

`corral stack status <stack>`

Show a stack as a dependency tree — members with their lifecycle and dev URL, the wiring between them, and, for a Cloudflare-derived stack, whether its config has drifted (with a re-sync hint).

corral stack status storefront

`corral stack create <name> [--member <project>…]`

Create a manual stack, optionally seeding members.

corral stack create storefront --member web --member api

`corral stack add <stack> <project>…` · `corral stack rm <stack> <project>`

Add or remove members of a manual stack.

A Cloudflare-derived stack’s membership comes from wrangler config — edit the config, or corral stack eject it to a manual copy first (Corral will point you there).

corral stack add storefront auth
corral stack rm storefront auth

`corral stack start|stop|restart <stack>`

Bring the stack’s members up (in dependency order) or down.

Members are ref-counted: one shared by two running stacks isn’t stopped until both release it.

corral stack start storefront
corral stack stop storefront

`corral stack resync <stack>` · `corral stack eject <stack>`

Re-derive a Cloudflare-derived stack from its workers’ current wrangler config, or fork it into an editable manual copy (leaving the original intact).

corral stack resync storefront
corral stack eject storefront

`corral stack delete <stack>` · `corral stack rename <stack> <new-name>`

Delete a stack (its members are preserved) or rename it.

corral stack delete storefront
corral stack rename storefront shop

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

`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:

Per-project package-manager setting
Lockfile detection (package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lock, legacy bun.lockb)
App-wide default-package-manager setting
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

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:

Removes the CA certificate from the system keychain
Kills any orphaned Caddy and dnsmasq processes
Removes the DNS resolver file (/etc/resolver/{tld})
Removes the privileged helper daemon
Deletes the data directory (~/.corral)
Clears app preferences
Removes shell profile shims
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

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

Install

`corral install app`

(Re)install or repair the macOS app from the terminal. The standard installer already sets the app up; reach for this if the app bundle was removed, or to force a fresh, fully-verified copy. It downloads Corral.app to /Applications through the same two-layer-verified path the in-app updater uses.

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

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

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

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.

The macOS app’s Subscription room provides a visual interface for all of the above (status, activate, deactivate, retry validation, manage subscription).

MCP

Corral ships an MCP (Model Context Protocol) server so AI coding tools — Claude Code, Cursor, VS Code, Codex, Continue, Zed, Windsurf — can drive your local environment over a typed protocol. The server is built into the CLI; the subcommands below detect and configure those clients. See AI Tools (MCP) for the full guide.

`corral mcp`

Start the stdio MCP server. AI clients spawn this automatically — you don’t run it by hand. corral mcp serve is the explicit spelling of the same thing.

`corral mcp install`

Configure AI clients to use Corral’s MCP server. With no --client, configures every client detected on your machine.

corral mcp install                  # every detected client, user scope
corral mcp install --client cursor  # one client (honored even if not yet installed)
corral mcp install --project        # project-scoped config in the current directory

Flag	Description
`--client <name>`	Configure only this client: `claude-code`, `cursor`, `vscode`, `codex`, `continue`, `zed`, `windsurf`
`--project`	Write project-scoped config (current directory) instead of user-global config

Corral merges a single corral entry into each client’s native config (JSON, TOML, or YAML), leaving everything else untouched. The command exits non-zero if any targeted client could not be configured.

`corral mcp uninstall`

Remove Corral’s entry from AI client configs — other servers and settings are left untouched. Same --client / --project flags as install; with no --client, removes from every detected client.

corral mcp uninstall
corral mcp uninstall --client zed

`corral mcp status`

Show each AI client’s configuration status at every scope it supports: configured, not configured, mismatched (points at a different path), unparseable, or error (the config couldn’t be read). Supports --json.

corral mcp status

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.

`corral report`

File a bug report with the maintainers, optionally attaching a diagnostics bundle (logs, unit state, crash reports). Runs entirely in-process, so it works even when the daemon is wedged or won’t start. See Reporting Problems for what’s included and the privacy posture.

corral report
corral report -m "wrangler dev exits immediately" --include-logs
corral report -m "DNS stopped resolving .test" --unit dns -y

Run with no -m in a terminal and Corral opens $EDITOR for the description, then prompts for diagnostics, a contact email (pre-filled from your license), and a confirmation. Off a terminal — or with --json — diagnostics are opt-in: they’re never bundled unless you pass --include-logs or --save.

Flag	Short	Description
`--message <text>`	`-m`	The problem description. If omitted on a terminal, opens `$EDITOR`.
`--email <email>`		Contact email for follow-up (pre-filled from your license if present).
`--include-logs`		Include diagnostics (logs, unit state, crash reports). Prompted on a terminal; off a terminal it’s off unless you pass this.
`--no-logs`		Do not include diagnostics (message only).
`--unit <id>`		Attach a specific unit’s failure snapshot (name or UUID).
`--yes`	`-y`	Skip the confirmation prompt.
`--dry-run`		Build the diagnostics bundle but do not send it.
`--save <path>`		Write the diagnostics bundle to this path (implies `--include-logs`).

On success, Corral prints a reference code:

corral report -m "..." -y
# ✓ Sent — reference CORRAL-7F3A2
#   Keep this reference if you'd like to follow up.

With --json, the result is one of these shapes:

{"status":"sent","reference":"CORRAL-7F3A2","included_logs":true,"bundle_bytes":52124}
{"status":"not_sent","saved":"/path/to/report.tar.gz","included_logs":true,"bundle_bytes":52124}
{"status":"network_failure","message":"...","saved":"/path/to/report.tar.gz","included_logs":true}
{"status":"rejected","http_status":429,"message":"..."}
{"status":"cancelled"}

// Last updated 2026-07-11

Command Reference

Global Flags

Project Resolution

Daemon

corral daemon start

corral daemon stop

corral daemon status

Lifecycle

corral up

corral down

corral status

corral start <project>

corral stop <project>

corral restart <project>

corral retry <project>

corral share <project>

Projects

corral project list

corral project add <path>

corral project remove <project>

corral project info <project>

corral project scan <directory>

corral project refresh <project>

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

corral project open <project>

corral project open-repo <project>

Stacks

corral stack list

corral stack status <stack>

corral stack create <name> [--member <project>…]

corral stack add <stack> <project>… · corral stack rm <stack> <project>

corral stack start|stop|restart <stack>

corral stack resync <stack> · corral stack eject <stack>

corral stack delete <stack> · corral stack rename <stack> <new-name>

Node.js

corral node list

corral node available

corral node install <version>

corral node remove <version>

Command Execution

corral exec <command> [args...]

corral npm [args...]

corral npx [args...]

corral pm [args...]

Shell Shims

corral install-shims

corral uninstall-shims

Uninstall

corral uninstall

Update

corral update

Install

corral install app

Logs

corral logs [project]

Settings

corral settings show

corral settings set <key> <value>

Infrastructure

corral infra start

corral infra stop

corral infra status

Services

corral service list

corral service catalog

corral service install <name>

corral service uninstall <name>

corral service start <name>

corral service stop <name>

corral service restart <name>

corral service info <name>

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

JSON output

Data Inspection

corral data bindings <project>

corral data d1 tables <project> <binding>

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

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

corral data kv keys <project> <binding>

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

`corral daemon start`

`corral daemon stop`

`corral daemon status`

`corral up`

`corral down`

`corral status`

`corral start <project>`

`corral stop <project>`

`corral restart <project>`

`corral retry <project>`

`corral share <project>`

`corral project list`

`corral project add <path>`

`corral project remove <project>`

`corral project info <project>`

`corral project scan <directory>`

`corral project refresh <project>`

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

`corral project open <project>`

`corral project open-repo <project>`

`corral stack list`

`corral stack status <stack>`

`corral stack create <name> [--member <project>…]`

`corral stack add <stack> <project>…` · `corral stack rm <stack> <project>`

`corral stack start|stop|restart <stack>`

`corral stack resync <stack>` · `corral stack eject <stack>`

`corral stack delete <stack>` · `corral stack rename <stack> <new-name>`

`corral node list`

`corral node available`

`corral node install <version>`

`corral node remove <version>`

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

`corral npm [args...]`

`corral npx [args...]`

`corral pm [args...]`

`corral install-shims`

`corral uninstall-shims`

`corral uninstall`

`corral update`

`corral install app`

`corral logs [project]`

`corral settings show`

`corral settings set <key> <value>`

`corral infra start`

`corral infra stop`

`corral infra status`

`corral service list`

`corral service catalog`

`corral service install <name>`

`corral service uninstall <name>`

`corral service start <name>`

`corral service stop <name>`

`corral service restart <name>`

`corral service info <name>`

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

`corral data bindings <project>`

`corral data d1 tables <project> <binding>`

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

`corral data d1 schema <project> <binding> <table>`

`corral data kv keys <project> <binding>`

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

`corral data r2 objects <project> <binding>`

`corral data r2 get <project> <binding> <key>`

`corral data do instances <project> <binding>`

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

`corral data secrets list <project> <binding>`

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

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

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

`corral data workflow instances <project> <binding>`

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

`corral license status`

`corral license activate <key>`

`corral license deactivate`

`corral mcp`

`corral mcp install`

`corral mcp uninstall`

`corral mcp status`

`corral completions <shell>`

`corral doctor`