CLI surface¶

cb is the operator CLI for Call Baxter. Running cb with no arguments, or running a command group such as cb events without a subcommand, prints the relevant help and exits successfully. CLI parsing uses the standard Python argparse surface; malformed input is reported as normal usage text, and runtime/configuration failures are reduced to one cb: error: ... diagnostic instead of a Pydantic validation dump or Python traceback.

Global connection options must come before the command:

cb [--config-file PATH] [--database-url URL_OR_PATH] [--daemon-url URL] COMMAND ...

Local mode requires a runtime config. You may either pass it explicitly or set the operator environment once:

export CB_CONFIG_FILE=/srv/config/call-baxter.yml
export CB_DATABASE_URL=/srv/data/cb.db

cb health
cb plugins list
cb rules list

Remote daemon mode does not require a local config file:

cb --daemon-url http://127.0.0.1:8943 health
cb --daemon-url http+unix:///srv/run/cb.sock health

If daemon admin authentication is enabled, set CALL_BAXTER_API_KEY or pass --daemon-api-key TOKEN. CB_DAEMON_URL can provide the daemon URL by environment. YAML string values continue to support ${VAR} and ${VAR:-default} expansion.

Output defaults to stable pretty JSON for script compatibility. --output text provides a compact operator-oriented form for simple lists and records.

Health, config, and reload¶

cb health
cb config show
cb reload

cb config show prints the active effective configuration in both local and remote daemon mode. It includes the resolved config path and post-environment-expansion values, but recursively replaces passwords, tokens, API keys, authorization values, credentials, and private keys with <redacted>. Remote mode reads the authenticated daemon GET /v1/config endpoint, so the displayed config is the runtime's current configuration after reload rather than an unrelated local file.

health exits non-zero unless the daemon/runtime returns "ok": true, which keeps it useful for Docker and service-manager checks. Daemon startup logs also state the resolved config path.

Plugins and rules¶

cb plugins list
cb rules list
cb rules list --kind telegram.message.new

Context contracts¶

cb context event list
cb context event show telegram.message.new
cb context action list
cb context action show telegram.send_message

These commands expose the data contracts available to rules, templates, and action invocations.

Events¶

Preferred syntax uses positionals for the required identity and payload arguments:

cb events list [--kind KIND]
cb events publish KIND SOURCE ATTRS_FILE [--subject-ref REF] [--occurred-at ISO_TIMESTAMP]

Example:

cb events publish system.heartbeat manual ./heartbeat.json

The pre-0.7.8 flag spelling remains accepted for compatibility:

cb events publish --kind KIND --source SOURCE --attrs-file ATTRS_FILE

ATTRS_FILE must contain a JSON object.

Actions¶

cb actions list [--kind KIND]
cb actions execute KIND ARGS_FILE [--subject-ref REF]

The old form remains accepted:

cb actions execute --kind KIND --args-file ARGS_FILE [--subject-ref REF]

ARGS_FILE must contain a JSON object.

Ingress adapters¶

cb ingress list
cb ingress runs [--ingress-name NAME] [--limit N]
cb ingress run NAME PAYLOAD_FILE
cb ingress reingest INGRESS_REF

Compatibility form:

cb ingress run --name NAME --payload-file PAYLOAD_FILE

Ingress adapters normalize source-native payloads into internal EventEnvelope instances.

Pollers¶

cb pollers list
cb pollers run NAME [CONFIG_FILE]

The old cb pollers run --name NAME [--config-file CONFIG_FILE] spelling remains accepted.

Schedules¶

cb schedules list
cb schedules sync
cb schedules run-due

Schedules are sourced from the YAML config and mirrored into SQLite.

Policy evidence¶

cb policy outcomes [--event-ref REF] [--rule-id ID] [--outcome OUTCOME] [--limit N]
cb policy simulate EVENT_REF
cb policy replay EVENT_REF
cb policy replay-eligibility EVENT_REF [--limit N]

These are read-only policy/audit operations; they do not add an action-replay execution path.

Plugin-specific CLI boundaries¶

Plugin-specific operator flows live outside the generic command modules. Telegram currently owns its dedicated helper namespace:

cb telegram reingest EVENT_REF

This takes the stored event's attrs.raw_update and sends it back through the telegram.update ingress. cb events reingest-telegram EVENT_REF remains as a compatibility alias, but its implementation lives in the Telegram CLI extension rather than the generic events code.

Generic plugin contracts remain generic: use cb actions, cb ingress, and cb pollers for plugin-defined action/ingress/poller names. Separately packaged integrations can ship their own small operator CLI; for example the WordPress package provides cb-wp verify and cb-wp categories.