Skip to content
Kira LOCAL-FIRST
Operator and agent CLI

Use the CLI for repeatable card and topic-inbox workflows.

The editorial CLI is a one-shot process: each command opens the SQLite store, performs one transaction, prints, and exits. This is intentionally automation-friendly.

Plain-language version

Most streamers do not need the CLI. It is for operators, scripts, and agents that prepare cards or topic suggestions in a repeatable way.

Safe CLI workflow

1

Prepare

A human, script, or agent creates a small card or topic proposal.

2

Validate

The CLI accepts only bounded, curated input and returns clear errors.

3

Review

Topic proposals still need human review in the app.

4

Use live

Approved content can support Kira during the stream.

Quick path

  1. 1 Run commands from the repo root or packaged Python environment.
  2. 2 Use --json for agents and parse stderr when the exit code is nonzero.
  3. 3 Treat exit 1 as a decided validation/state result, not something to blind-retry.
  4. 4 Retry only transient "database is locked" failures, with backoff.

Who should use it

Streamer

Use the app UI first. It is the safer, clearer path for live operation.

Operator

Use the CLI when preparing many cards or proposals before a show.

Agent/script

Use --json, check exit codes, and never assume topic approval happened.

Common commands

Create a card

python -m opencohost.editorial_cli --json create --from-json

Arm and inspect

python -m opencohost.editorial_cli arm <card_id>
python -m opencohost.editorial_cli show <card_id> --json

Explicit card link

python -m opencohost.editorial_cli link <topic_slug> <card_id>

Propose a topic

python -m opencohost.editorial_cli topic propose --title "<title>" --angle "<angle>" --source "<agent>"

List or discard proposals

python -m opencohost.editorial_cli topic list --json
python -m opencohost.editorial_cli topic discard <ti_id>

Hard boundaries

No CLI approval for topics
topic approve is deliberately refused. Approval happens in the app where the operator can read title and angle.
Curated context only
Cards reject raw dumps, code-like content, and oversized fields. Agents should summarize before writing.
One operation per process
There is no CLI daemon or session memory; command order is the state machine.