Registry stack documentation: machine-readable Markdown.
Index of all pages: https://docs.registrystack.org/llms.txt
Full corpus: https://docs.registrystack.org/llms-full.txt

# bregctl dev start command reference

> Generated syntax and options for bregctl dev start.

{/* Generated from Clap command definitions by scripts/generate-cli-reference.mjs. Run npm run generate. */}

Start or reuse the project's retained local database and services.

## Contract status

This page is generated from the public Clap command tree for Registry Stack source version `0.34.0` and catalog SHA-256 `521175a69262e60df96745886392348e5bb8d82e63cdd24bdf4baa80d46e5ff4`. Hidden implementation commands are omitted.

## Description

Start or reuse the project's retained local database and services. A resident supervisor owns this project's PostgreSQL and ThunderID containers plus its Base Registry Engine (BReg) child. The database runs the pinned image postgres:17.11@sha256:67f41722b7a8cbdb868a44a4995c846eddfdc2973bccb291ce937dce88ad5675, or, when the compiled schema requires PostGIS, postgis/postgis@sha256:01a6a70e41e6c4467c8f55f6063555ed72db2d6662cd0d571040d42eadaeb6f6, which the supervisor pulls on the first start. Each supervised prerequisite command may run for 120 seconds, and the database and each started service have 45 seconds to answer as ready. A start that passes a deadline fails, stops what it acquired, and keeps its owner-only diagnostics in the project's private .breg/dev/logs directory. Catchable termination signals trigger owned cleanup, but an uncatchable outside kill can leave surviving service owners that need inspection before restart. products/breg/DEV.md documents this lifecycle in 'Native local BReg lifecycle' and its recovery in 'Retained state and recovery'.

## Usage

```text
bregctl dev start [OPTIONS] [PROJECT]
```

## Arguments

| Argument | Always required | Default | Values | Environment | Description |
| --- | --- | --- | --- | --- | --- |
| `[PROJECT]` | No | `.` | n/a | n/a | Existing authored registry project. Its package environment must be local. A symbolic link at any component of this path is refused. |

## Options

| Option | Always required | Default | Values | Environment | Description |
| --- | --- | --- | --- | --- | --- |
| `--clients-file <FILE>` | No | n/a | n/a | n/a | Local clients, profile bindings, and optional seed records (default on first start: dev-clients.yaml in the project; retained for restarts). A symbolic link at any component of this path is refused. |
| `--breg-port <BREG_PORT>` | No | n/a | n/a | n/a | Registry loopback port on first start (default 8090; retained for restarts) |
| `--issuer-port <ISSUER_PORT>` | No | n/a | n/a | n/a | Local issuer loopback port on first start (default 8091; retained for restarts) |
| `--issuer-project <PROJECT>` | No | n/a | n/a | n/a | Ready Base Registry Engine (BReg) dev project that owns the shared local issuer and client registrations. A symbolic link at any component of this path is refused. |
| `--issuer-image <ISSUER_IMAGE>` | No | n/a | n/a | n/a | Immutable local candidate issuer image ID on first start; retained for restarts |
| `--mint-port <MINT_PORT>` | No | n/a | n/a | n/a | Retained spelling from earlier Mint-based dev sessions; refused with legacy-session guidance rather than silently ignored |
| `--mint-bin <MINT_BIN>` | No | n/a | n/a | n/a | Retained spelling from earlier Mint-based dev sessions; refused with legacy-session guidance rather than silently ignored |
| `--database-port <DATABASE_PORT>` | No | n/a | n/a | n/a | PostgreSQL loopback port on first start (default 55432; retained for restarts) |
| `--format <FORMAT>` | No | `human` | `human`, `json` | n/a | Emit the selected command's report in this format |
| `-h, --help` | No | n/a | n/a | n/a | Print help (see a summary with '-h') |

## Generation contract

Run `npm run generate` from `docs/site` after changing a public command, argument, option, default, environment binding, or help description.