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

# evidencectl source add command reference

> Generated syntax and options for evidencectl source add.

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

Connect a retained local registry through its public lookup export.

## Contract status

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

## Description

Connect a retained local registry through its public lookup export. This command reviews the connection by default and reports the choices it would apply; re-run it with --apply to perform them. It drives the public Base Registry Engine commands, so a bregctl binary of this same version must be on PATH, or named by --bregctl-bin or BREGCTL_BIN.

## Usage

```text
evidencectl source add [OPTIONS] <REGISTRY>
```

## Constraints

| Condition | Requirement |
| --- | --- |
| Command invocation | `--all-records` and `--row-claim <ROW_CLAIM>` cannot be used together. |
| Command invocation | `--all-records` and `--row-field <ROW_FIELD>` cannot be used together. |
| Command invocation | `--all-records` and `--row-value-file <ROW_VALUE_FILE>` cannot be used together. |

## Arguments

| Argument | Always required | Default | Values | Environment | Description |
| --- | --- | --- | --- | --- | --- |
| `<REGISTRY>` | Yes | n/a | n/a | n/a | Registry project containing a stopped retained Base Registry Engine development session |

## Options

| Option | Always required | Repeatable | Default | Values | Environment | Description |
| --- | --- | --- | --- | --- | --- | --- |
| `--project <PROJECT>` | No | No | `.` | n/a | n/a | Evidence project directory; defaults to the current directory. This command extends an editable project or creates a source-first editable project when the directory is absent. |
| `--entity <ENTITY>` | No | No | n/a | n/a | n/a | Existing registry entity; prompted when omitted in a terminal |
| `--selector-field <SELECTOR_FIELD>` | No | No | n/a | n/a | n/a | Existing unique identifier field; prompted when omitted in a terminal |
| `--fields <FIELDS>` | No | Yes | n/a | n/a | n/a | Existing scalar facts to expose; comma-separated, prompted when omitted |
| `--all-records` | No | No | n/a | n/a | n/a | Explicitly allow lookups across every record in the selected entity |
| `--row-field <ROW_FIELD>` | No | No | n/a | n/a | n/a | Restrict the workload to records matching this existing field |
| `--row-claim <ROW_CLAIM>` | No | No | n/a | n/a | n/a | Advanced: direct workload claim name; defaults to registry_source_row |
| `--row-value-file <ROW_VALUE_FILE>` | No | No | n/a | n/a | n/a | Private input file holding a nonsecret scope label as one JSON string; stored in dev-clients.yaml |
| `--source-id <SOURCE_ID>` | No | No | n/a | n/a | n/a | Source identifier; defaults to a bounded registry- name derived from the entity |
| `--connection <CONNECTION>` | No | No | `registry` | n/a | n/a | Shared connection name, also used for credential filenames |
| `--client <CLIENT>` | No | No | n/a | n/a | n/a | Dedicated local source client label; defaults to a bounded name derived from the source identifier |
| `--access-profile <ACCESS_PROFILE>` | No | No | n/a | n/a | n/a | Dedicated registry lookup access profile; defaults to a bounded name derived from the source identifier |
| `--selector-profile <SELECTOR_PROFILE>` | No | No | n/a | n/a | n/a | Registry selector profile; defaults to a bounded name derived from the source identifier |
| `--target <TARGET>` | No | No | n/a | n/a | n/a | Local target to extend; defaults to PROJECT/targets/local |
| `--apply` | No | No | n/a | n/a | n/a | Perform the reviewed connection; without it this command reviews new choices only |
| `--bregctl-bin <BREGCTL_BIN>` | No | No | n/a | n/a | n/a | Public Base Registry Engine tooling binary; otherwise BREGCTL_BIN or bregctl on PATH |
| `--format <output_format>` | No | No | `human` | `human`, `json` | n/a | Select human-readable or machine-readable output |
| `-h, --help` | No | 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.