# stella db - Command Guide

The `stella db` command group triggers Concelier database operations via backend jobs and advisory-source management APIs.

These commands are operational: they typically require Authority authentication and appropriate Concelier scopes.

## Commands

### db connectors configure

Inspect or update persisted advisory source configuration.

```bash
stella db connectors configure ghsa --server https://concelier.example.internal

stella db connectors configure ghsa \
  --server https://concelier.example.internal \
  --set apiToken=github_pat_xxx

stella db connectors configure cisco \
  --server https://concelier.example.internal \
  --set clientId=... \
  --set clientSecret=...

stella db connectors configure microsoft \
  --server https://concelier.example.internal \
  --set tenantId=... \
  --set clientId=... \
  --set clientSecret=...

stella db connectors configure oracle \
  --server https://concelier.example.internal \
  --set calendarUris=https://www.oracle.com/security-alerts/,https://mirror.example.internal/oracle/

stella db connectors configure adobe \
  --server https://concelier.example.internal \
  --set indexUri=https://mirror.example.internal/adobe/security-bulletin.html

stella db connectors configure chromium \
  --server https://concelier.example.internal \
  --set feedUri=https://mirror.example.internal/chromium/atom.xml
```

Options:

- `--set key=value`: set a field value. Repeat for multiple fields.
- `--clear <field>`: clear a stored field. Repeat for multiple fields.
- `--server`: Concelier API base URL.
- `--tenant`, `-t`: tenant override.
- `--format`, `-f`: `text` or `json`.

Notes:

- Sensitive fields are returned as retained or not-set markers, not plaintext values.
- Multi-value URI fields accept comma-, semicolon-, or newline-separated absolute URIs.
- The current CLI path sends literal values on the command line. Use the Web UI path if command-history exposure is unacceptable for a secret.

Blocked state for credential-gated sources:

- Persisted enablement (`enabled=true`) is kept separate from runtime readiness. When an enabled source is missing required credentials or URIs, its `readiness` (alias `syncState`) is `blocked`, `blockedReason` describes what is missing, and both `/sync` and the batch `/sync` paths skip it with an explicit `blocked` outcome instead of invoking the connector and emitting a misleading scheduler failure.
- Supplying the missing field through `stella db connectors configure <source> --set <field>=<value>` flips the source to `readiness=ready` on the next status call without any disable/re-enable step.
- See [connectors.md -> Blocked / sleeping readiness state](/C:/dev/New%20folder/git.stella-ops.org/docs/modules/concelier/connectors.md) for the full endpoint contract.

### db fetch

Trigger a connector stage (`fetch`, `parse`, or `map`) for a given source.

```bash
stella db fetch --source osv --stage fetch
stella db fetch --source osv --stage parse
stella db fetch --source osv --stage map
```

Options:

- `--source` (required): connector identifier such as `osv`, `redhat`, `ghsa`, or `cisco`
- `--stage` (optional): `fetch`, `parse`, or `map` (defaults to `fetch`)
- `--mode` (optional): connector-specific mode such as `init`, `resume`, or `cursor`

### db merge

Run canonical merge reconciliation.

```bash
stella db merge
```

### db export

Run Concelier export jobs.

```bash
stella db export --format json
stella db export --format trivy-db --delta
```

Options:

- `--format` (optional): `json` or `trivy-db`
- `--delta` (optional): request a delta export when supported
- `--publish-full` or `--publish-delta` (optional): override publish behavior
- `--bundle-full` or `--bundle-delta` (optional): override offline bundle behavior

## Common setup

Point the CLI at the Concelier base URL:

```bash
export STELLAOPS_BACKEND_URL="https://concelier.example.internal"
```

Authenticate:

```bash
stella auth login
```

See `docs/CONCELIER_CLI_QUICKSTART.md` and `docs/modules/concelier/operations/authority-audit-runbook.md`.