# Commands

`dev-cockpit` ships five core commands. A profile contributes its own commands via `setupCli(program)` — these register **first**, so a profile can take over a core command name (the matching core command is then skipped).

| Command           | What it does                                                                  |
|-------------------|-------------------------------------------------------------------------------|
| `dev`             | Boots the four-pane TUI (Targets / Output / Health / Help).                     |
| `doctor`          | Runs every registered health check once and prints a status table.            |
| `init-config`     | Writes a `cockpit.yaml` (static template or interactive wizard).              |
| `mount`           | Manages a docker-compose bind-mount overlay (apply / status / clear).         |
| `migrate-config`  | Rewrites `cockpit.yaml` at the current `CONFIG_VERSION`.                       |

## `dev`

```
dev-cockpit dev [-c <path>]
```

Loads `cockpit.yaml` (auto-migrating older versions in memory), runs the active profile's `boot` lifecycle hook, wires the action registry (built-ins + profile defaults + dynamic boot-result actions + user config), starts an optional Docker log tailer if `config.docker.services[]` is declared, then renders the cockpit shell.

## `doctor`

```
dev-cockpit doctor [-c <path>]
```

Builds the health registry from `config.health[]` plus `profile.healthChecks`, runs the `startup` trigger set once, and prints `✓ / ⚠ / ✗` per check. Exits non-zero on any `error` severity.

## `init-config`

```
dev-cockpit init-config [--with-docker] [-i|--interactive] [-f|--force]
```

Writes a `cockpit.yaml` at the current directory.

- **Static template** (default): heavily commented; uncomment what you need. `--with-docker` uncomments the docker block.
- **Interactive wizard** (`-i`): 8 steps with auto-detection from `package.json` / `compose.yaml`. Picks up scripts as actions (test/build/lint/format) or processes (dev/watch). Profile-contributed steps via `Profile.wizardSteps` run between Notifications and the summary; their output lands under `profile.<appName>:`. See [init-config.md](./init-config.md).

## `mount`

```
dev-cockpit mount [-c <path>] [-s|--service <name>] [-q|--quiet] [-e|--exclude <name>]
dev-cockpit mount status [-c <path>]
dev-cockpit mount clear  [-c <path>]
```

Merges `config.mounts[]` with `profile.mountCandidatesProvider?.()` and writes a docker-compose overlay + manifest. Interactive picker by default (when candidates exist); `--quiet` skips the prompt. Full reference: [mount.md](./mount.md).

## `migrate-config`

```
dev-cockpit migrate-config [-c <path>] [--dry-run]
```

Reads `cockpit.yaml`, runs migrators from whatever version it declares up to the current `CONFIG_VERSION`, writes the result back with a comment banner. Idempotent on a current-version file. `--dry-run` prints the migrated YAML to stdout instead of writing.

The `dev` command auto-applies migrations in memory each boot — `migrate-config` exists to persist the change so the warning stops firing.

## Profile setupCli

A profile bundle implements the `Profile` type's `setupCli(program)` to register additional commands or override core ones:

```ts
import type { Profile } from 'dev-cockpit';

export const myProfile: Profile = {
  appName: 'my-app',
  setupCli(program) {
    program
      .command('release')
      .description('cut a release')
      .action(async () => {
        /* … */
      });
  },
};
```

The profile is invoked **before** the core commands register. Any name the profile claims (`dev`, `doctor`, etc.) silently skips its core counterpart — no overrides API, no array mutation, just registration order.

## `:` command palette (not a CLI command)

Inside the running cockpit, `:` opens a vim-style palette over the action registry. Type to substring-filter, ↑/↓ to navigate, Enter to fire, Esc to cancel. Actions can also be bound to a single keystroke via `key:` and dispatched directly in their scope (e.g., `scope: repos:<id>` actions fire on a keypress when that row is selected). See `actions:` in [config-reference.md](./config-reference.md).
