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

# CLI reference

> The honest-scholar command tree, generated from the Typer app.

Supporting tooling for the honest-scholar research-workflow plugin.

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

## `honest-scholar 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}
honest-scholar doctor
```

## `honest-scholar literature`

Citation-graph and metadata tools.

### `honest-scholar literature resolve`

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

```text theme={null}
honest-scholar literature resolve IDENTIFIER
```

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

### `honest-scholar literature cites`

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

```text theme={null}
honest-scholar literature cites [OPTIONS] IDENTIFIER
```

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

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

### `honest-scholar literature refs`

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

```text theme={null}
honest-scholar literature refs IDENTIFIER
```

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

### `honest-scholar literature enrich`

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

```text theme={null}
honest-scholar literature enrich [OPTIONS] IDENTIFIERS
```

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

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

### `honest-scholar literature neighbors`

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

```text theme={null}
honest-scholar literature neighbors [OPTIONS] IDENTIFIER
```

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

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

## `honest-scholar dataset`

Dataset manifest, retrieval and mirroring.

### `honest-scholar 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}
honest-scholar dataset validate [MANIFEST]
```

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

### `honest-scholar 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}
honest-scholar dataset ingest CROISSANT
```

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

### `honest-scholar dataset emit`

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

```text theme={null}
honest-scholar 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.     |

### `honest-scholar dataset fetch`

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

```text theme={null}
honest-scholar dataset fetch [OPTIONS] IDENTIFIER
```

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

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

### `honest-scholar dataset verify`

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

```text theme={null}
honest-scholar dataset verify [OPTIONS] IDENTIFIER
```

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

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

### `honest-scholar dataset mirror`

Populate/refresh the private rclone mirror for a dataset.

```text theme={null}
honest-scholar dataset mirror [OPTIONS] IDENTIFIER
```

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

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

### `honest-scholar dataset audit`

Audit fixity, mirror presence and manifest completeness.

```text theme={null}
honest-scholar 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. |

## `honest-scholar defend`

Defensibility record helpers.

### `honest-scholar defend record`

Record a `defend` examination: patch understanding + append the log.

Writes `status.understanding` into the artifact frontmatter and appends the
outcome to the accountability log. Records observed facts only — never a
verdict, score, or answer key.

```text theme={null}
honest-scholar defend record [OPTIONS]
```

| Option            | Default                    | Description                           |
| ----------------- | -------------------------- | ------------------------------------- |
| `--artifact`      | —                          | Target markdown artifact.             |
| `--target`        | —                          | claim \| cited-work \| methodology.   |
| `--gaps`          | —                          | Observed gap facts, '\|\|'-separated. |
| `--signed-off-by` | —                          | —                                     |
| `--override`      | `false`                    | —                                     |
| `--acks`          | —                          | Per-gap sign-offs, 'gap::name\|\|…'.  |
| `--transcript`    | —                          | Transcript file, or '-' for stdin.    |
| `--log-dir`       | `docs/research/defend-log` | —                                     |

## `honest-scholar backlog`

Exploration backlog management.

### `honest-scholar backlog park`

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

```text theme={null}
honest-scholar 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.     |

### `honest-scholar backlog add`

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

```text theme={null}
honest-scholar 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.     |

### `honest-scholar backlog list`

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

```text theme={null}
honest-scholar backlog list [OPTIONS]
```

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

### `honest-scholar backlog rank`

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

```text theme={null}
honest-scholar 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`    | —            | —                    |

### `honest-scholar 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}
honest-scholar 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. |

### `honest-scholar backlog drop`

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

```text theme={null}
honest-scholar 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. |

## `honest-scholar keys`

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

### `honest-scholar 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}
honest-scholar keys set [NAME]
```

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

### `honest-scholar keys list`

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

```text theme={null}
honest-scholar keys list
```

### `honest-scholar keys check`

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

```text theme={null}
honest-scholar keys check
```

### `honest-scholar keys unset`

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

```text theme={null}
honest-scholar keys unset NAME
```

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

### `honest-scholar keys path`

Print the resolved key-store path.

```text theme={null}
honest-scholar keys path
```