> ## Documentation Index
> Fetch the complete documentation index at: https://defendable.science/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> The defendable-science command tree, generated from the Typer app.

Supporting tooling for the defendable-science research-workflow plugin.

Every command emits JSON on success and a clear, non-zero exit with an actionable message on failure. Run `defendable-science --version` to print the installed version. This page is generated from the Typer app on every build, so it always matches the released CLI.

## `defendable-science doctor`

Report the local environment: Python, `uv` and `rclone`.

Prints a short diagnostic report. Missing optional tools (`uv`,
`rclone`) are reported, not treated as failures. Always exits 0.

```text theme={null}
defendable-science doctor
```

## `defendable-science literature`

Citation-graph and metadata tools.

### `defendable-science literature resolve`

Resolve an identifier (DOI, arXiv id, OpenAlex/S2 id) to a canonical work.

```text theme={null}
defendable-science literature resolve IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

### `defendable-science literature cites`

List works that cite the given work (JSON array).

```text theme={null}
defendable-science literature cites [OPTIONS] IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

| Option  | Default | Description  |
| ------- | ------- | ------------ |
| `--max` | `0`     | Cap on rows. |

### `defendable-science literature refs`

List the backward references (OpenAlex ids) of the given work.

```text theme={null}
defendable-science literature refs IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

### `defendable-science literature enrich`

Enrich one or more works with their metadata bundle (JSON array).

```text theme={null}
defendable-science literature enrich [OPTIONS] IDENTIFIERS
```

| Argument      | Required | Description |
| ------------- | -------- | ----------- |
| `IDENTIFIERS` | yes      | —           |

| Option      | Default | Description |
| ----------- | ------- | ----------- |
| `--context` | `false` | —           |

### `defendable-science literature neighbors`

List co-citation / bibliographic-coupling neighbours of the given work.

```text theme={null}
defendable-science literature neighbors [OPTIONS] IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

| Option   | Default | Description               |
| -------- | ------- | ------------------------- |
| `--kind` | `both`  | cocite \| couple \| both. |
| `--top`  | `20`    | —                         |

## `defendable-science dataset`

Dataset manifest, retrieval and mirroring.

### `defendable-science dataset validate`

Validate a `datasets.yml` manifest (the register/audit gate).

Prints a JSON report `{ok, errors, warnings}` and exits non-zero on any
hard error.

```text theme={null}
defendable-science dataset validate [MANIFEST]
```

| Argument   | Required | Description                       |
| ---------- | -------- | --------------------------------- |
| `MANIFEST` | no       | Path to the manifest to validate. |

### `defendable-science dataset ingest`

Ingest a published Croissant JSON-LD file to bootstrap a draft entry.

Prints the draft registry entry as JSON, with the human-owned fields it could
not fill listed under `_needs_human` (the caller confirms them on register).

```text theme={null}
defendable-science dataset ingest CROISSANT
```

| Argument    | Required | Description |
| ----------- | -------- | ----------- |
| `CROISSANT` | yes      | —           |

### `defendable-science dataset emit`

Emit a Croissant JSON-LD document for a manifest entry (or all entries).

```text theme={null}
defendable-science dataset emit [OPTIONS] [IDENTIFIER]
```

| Argument     | Required | Description                               |
| ------------ | -------- | ----------------------------------------- |
| `IDENTIFIER` | no       | The dataset id to emit (omit with --all). |

| Option       | Default        | Description                       |
| ------------ | -------------- | --------------------------------- |
| `--all`      | `false`        | Emit every entry as a JSON array. |
| `--manifest` | `datasets.yml` | Path to the manifest to read.     |

### `defendable-science dataset fetch`

Fetch a registered dataset through the resolution chain (pooch/rclone).

```text theme={null}
defendable-science dataset fetch [OPTIONS] IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

| Option       | Default        | Description           |
| ------------ | -------------- | --------------------- |
| `--manifest` | `datasets.yml` | Path to the manifest. |

### `defendable-science dataset verify`

Verify on-disk bytes against the manifest SHA-256 (offline).

```text theme={null}
defendable-science dataset verify [OPTIONS] IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

| Option       | Default        | Description           |
| ------------ | -------------- | --------------------- |
| `--manifest` | `datasets.yml` | Path to the manifest. |

### `defendable-science dataset mirror`

Populate/refresh the private rclone mirror for a dataset.

```text theme={null}
defendable-science dataset mirror [OPTIONS] IDENTIFIER
```

| Argument     | Required | Description |
| ------------ | -------- | ----------- |
| `IDENTIFIER` | yes      | —           |

| Option       | Default        | Description           |
| ------------ | -------------- | --------------------- |
| `--manifest` | `datasets.yml` | Path to the manifest. |

### `defendable-science dataset audit`

Audit fixity, mirror presence and manifest completeness.

```text theme={null}
defendable-science dataset audit [OPTIONS] [IDENTIFIER]
```

| Argument     | Required | Description                                     |
| ------------ | -------- | ----------------------------------------------- |
| `IDENTIFIER` | no       | Optional dataset id; whole manifest if omitted. |

| Option       | Default        | Description           |
| ------------ | -------------- | --------------------- |
| `--manifest` | `datasets.yml` | Path to the manifest. |

## `defendable-science defend`

Defensibility record helpers.

### `defendable-science defend record`

Record a `defend`/`digest` examination: patch understanding + log.

Writes `status.understanding` into the artifact frontmatter and appends the
full evidentiary point record (ADR-0033) to the accountability log. Records
observed facts only — never a verdict, score, or answer key.

```text theme={null}
defendable-science defend record [OPTIONS]
```

| Option            | Default                    | Description                                                |
| ----------------- | -------------------------- | ---------------------------------------------------------- |
| `--artifact`      | —                          | Target markdown artifact.                                  |
| `--target`        | —                          | claim \| cited-work \| methodology \| paper-comprehension. |
| `--points`        | —                          | Point records: a JSON-array file path, or '-' for stdin.   |
| `--signed-off-by` | —                          | —                                                          |
| `--override`      | `false`                    | —                                                          |
| `--acks`          | —                          | Per-gap sign-offs, 'gap::name\|\|…'.                       |
| `--transcript`    | —                          | Transcript file, or '-' for stdin.                         |
| `--log-dir`       | `docs/research/defend-log` | —                                                          |

## `defendable-science backlog`

Exploration backlog management.

### `defendable-science backlog park`

Park a raw one-line idea as a `parked` backlog row.

```text theme={null}
defendable-science backlog park [OPTIONS] ONE_LINE
```

| Argument   | Required | Description |
| ---------- | -------- | ----------- |
| `ONE_LINE` | yes      | —           |

| Option         | Default      | Description          |
| -------------- | ------------ | -------------------- |
| `--provenance` | —            | Origin, verbatim.    |
| `--backlog`    | `backlog.md` | Path to the backlog. |
| `--level`      | `hypothesis` | hypothesis \| paper. |
| `--id`         | —            | Explicit row id.     |

### `defendable-science backlog add`

Add a `candidate` row (realizes the `generate` verb).

```text theme={null}
defendable-science backlog add [OPTIONS] ONE_LINE
```

| Argument   | Required | Description |
| ---------- | -------- | ----------- |
| `ONE_LINE` | yes      | —           |

| Option         | Default      | Description          |
| -------------- | ------------ | -------------------- |
| `--provenance` | —            | Origin, verbatim.    |
| `--backlog`    | `backlog.md` | Path to the backlog. |
| `--level`      | `hypothesis` | hypothesis \| paper. |
| `--id`         | —            | Explicit row id.     |

### `defendable-science backlog list`

List backlog rows as JSON (read-only), optionally filtered by status.

```text theme={null}
defendable-science backlog list [OPTIONS]
```

| Option      | Default      | Description          |
| ----------- | ------------ | -------------------- |
| `--backlog` | `backlog.md` | Path to the backlog. |
| `--level`   | `hypothesis` | hypothesis \| paper. |
| `--status`  | —            | Filter by status.    |

### `defendable-science backlog rank`

Score a row and set it `ranked` (advises; never selects).

```text theme={null}
defendable-science backlog rank [OPTIONS] ROW_ID
```

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `ROW_ID` | yes      | —           |

| Option       | Default      | Description          |
| ------------ | ------------ | -------------------- |
| `--backlog`  | `backlog.md` | Path to the backlog. |
| `--level`    | `hypothesis` | hypothesis \| paper. |
| `--eig`      | —            | —                    |
| `--feas`     | —            | —                    |
| `--interest` | —            | —                    |
| `--frame`    | —            | —                    |

### `defendable-science backlog promote`

Mark a `ranked` row `promoted` (an explicit human pick).

Flips the row's status and saves the backlog. Scaffolding the next-stage
artifact is a follow-up step (`scaffold_hypothesis` / `scaffold_paper`).

```text theme={null}
defendable-science backlog promote [OPTIONS] ROW_ID
```

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `ROW_ID` | yes      | —           |

| Option      | Default      | Description          |
| ----------- | ------------ | -------------------- |
| `--backlog` | `backlog.md` | Path to the backlog. |
| `--level`   | `hypothesis` | hypothesis \| paper. |

### `defendable-science backlog drop`

Retire a row as `dropped` with a recorded reason (never deletes it).

```text theme={null}
defendable-science backlog drop [OPTIONS] ROW_ID
```

| Argument | Required | Description |
| -------- | -------- | ----------- |
| `ROW_ID` | yes      | —           |

| Option      | Default      | Description          |
| ----------- | ------------ | -------------------- |
| `--reason`  | —            | Why it is dropped.   |
| `--backlog` | `backlog.md` | Path to the backlog. |
| `--level`   | `hypothesis` | hypothesis \| paper. |

## `defendable-science keys`

Store, list and check API keys & credentials (ADR-0029).

### `defendable-science keys set`

Store a key. The value comes from **stdin or a hidden prompt**, never argv.

Piping a JSON object (`{"NAME": "value", ...}`) sets many at once. Unknown
names warn but are still stored. No value is ever echoed.

```text theme={null}
defendable-science keys set [NAME]
```

| Argument | Required | Description                                    |
| -------- | -------- | ---------------------------------------------- |
| `NAME`   | no       | Key name; omit only when piping a JSON object. |

### `defendable-science keys list`

List every known + stored key with its metadata and presence (no values).

```text theme={null}
defendable-science keys list
```

### `defendable-science keys check`

Report presence/absence and source of each key as JSON (never a value).

```text theme={null}
defendable-science keys check
```

### `defendable-science keys unset`

Remove a key from the store (a no-op if it was not stored).

```text theme={null}
defendable-science keys unset NAME
```

| Argument | Required | Description                        |
| -------- | -------- | ---------------------------------- |
| `NAME`   | yes      | Key name to remove from the store. |

### `defendable-science keys path`

Print the resolved key-store path.

```text theme={null}
defendable-science keys path
```