Skip to content

cli.md

Latest commit

 

History

History
153 lines (104 loc) · 3.54 KB

cli.md

File metadata and controls

153 lines (104 loc) · 3.54 KB
Raw

CLI Reference

OpenWard ships a single primary binary: openward.

For same-machine agents, this is the primary control surface.

Operator Commands

These start, stop, and configure the service:

openward start
openward helper
openward import-dns
openward import-pcap
openward watch-dns
openward doctor

Operator Shortcuts (legacy)

These are plain-text shortcuts for quick operator use. Prefer the agent-grade commands above in scripts or agents, as these lack structured output.

openward devices   # use: openward device list --json
openward stats     # use: openward status --json
openward rescan

Common Operator Checks

Use these first before you dig into deeper debugging:

openward doctor
openward stats
openward devices

Agent-Grade Commands

These are the preferred commands when an agent runs on the same machine as OpenWard.

All of them support --json.

openward status --json
openward device list --json
openward device show <id> --json
openward report digest --json
openward report evidence --json
openward policy list --json
openward policy show <id> --json
openward policy replay <id> --json
openward policy approve <id> --json
openward policy enforce <id> --json
openward policy rollback <id> --json
openward mute propose --scope network --level standard --json
openward agent list --json

Use the CLI when you want:

  • a local agent on the OpenWard host
  • stable JSON output without HTTP setup
  • direct host-local automation
  • the simplest reviewable write path

openward start

Use this to run the controller, dashboard, API, DNS watcher, and runtime jobs.

Common options:

--host <HOST>
--port <PORT>
--db <DB>
--input <INPUT>
--poll-ms <POLL_MS>
--blocklist-path <PATH>
--firewall-rules-path <PATH>
--helper-socket <PATH>
--admin-token <TOKEN>

Typical use:

  • dedicated Linux host
  • manual local testing
  • service debugging outside the installer or Docker path

openward helper

Use this when you want the narrow privileged helper process that performs local side effects through a Unix socket.

Typical use:

  • split-privilege production install
  • local troubleshooting of firewall or dnsmasq side effects

openward import-dns

Use this for one-shot import of an existing resolver log into the SQLite state.

Typical use:

  • backfilling a new install from an older resolver log
  • fixture and replay preparation

openward import-pcap

Use this for offline packet metadata import from pcap or pcapng captures.

Typical use:

  • replay and validation work
  • lab captures
  • packet review without running the live controller

openward watch-dns

Use this to watch a DNS log file without starting the full web surface.

openward doctor

Use this to check local install health before or after deployment changes.

openward devices

Print the current discovered-device view from the local database.

openward stats

Print a compact tracking summary from the local database.

openward rescan

Rescan existing DNS history against the currently enabled tracker lists.

Practical Notes

Related Docs