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 command reference

> Generated syntax and options for bregctl dev.

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

Start or stop this project's retained local development 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.

## Usage

```text
bregctl dev [OPTIONS] [PROJECT]
       bregctl dev <COMMAND>
```

## Commands

| Command | Description |
| --- | --- |
| [`start`](./start/) | Start or reuse the project's retained local database and services |
| [`stop`](./stop/) | Stop only this project's supervised services, preserving its database, records, audit history, keys and built package |
| [`events`](./events/) | Show received local webhook deliveries, hiding projected values by default |
| [`export-client`](./export-client/) | Copy an explicitly selected retained local client credential pair |
| [`token`](./token/) | Acquire a fresh local client token and report its private header-file path |
| [`grant`](./grant/) | Exchange an existing Casework approval using an explicit configured issuer connection |

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

## Generation contract

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