CLI Reference

The seerflow CLI ships as a single entry point. Run it directly (seerflow) or through uv run python -m seerflow.

seerflow --help
seerflow --version
seerflow --config /path/to/seerflow.yaml <command>

Global flags

Flag	Description
--config FILE	Use a specific YAML config. Default: seerflow.yaml in the working directory.
--version	Print version and exit.
--help	Print help for the current command.

start

Boot the full pipeline: receivers, parsers, detection, correlation, dashboard, REST API, and WebSocket stream — all in one process.

seerflow start
seerflow --config /etc/seerflow.yaml start

The dashboard and APIs are exposed on dashboard_port (default 8080):

• UI — http://127.0.0.1:8080/
• REST — http://127.0.0.1:8080/api/v1/
• WebSocket — ws://127.0.0.1:8080/api/v1/ws

Ctrl+C triggers a graceful shutdown that flushes events, persists ML model state, and prints a session summary.

tail

Zero-config one-shot mode — monitor one or more files without touching seerflow.yaml. Detection still runs, but only file tailing is enabled and storage uses an ephemeral SQLite DB unless --config is passed.

seerflow tail /var/log/syslog
seerflow tail /var/log/auth.log /var/log/nginx/access.log
seerflow tail '/var/log/*.log'

Stops cleanly on Ctrl+C with the same summary as start.

query

Read from the storage backend currently configured.

seerflow query events --limit 50
seerflow query events --since 1h --entity 10.0.1.42
seerflow query alerts --since 24h
seerflow query alerts --severity high
seerflow query templates --top 20
seerflow query timeline <entity_uuid> --since 24h
seerflow query health

Subcommand	Purpose
events	Stored SeerflowEvent rows. Filters: --since, --entity, --template, --source, --limit.
alerts	Stored alerts. Filters: --since, --severity, --rule, --limit.
templates	Drain3 templates ranked by count or recency. Filters: --top, --since.
timeline	Chronological events involving a given entity UUID. Filters: --since, --limit.
health	Detection ensemble health: per-detector status, queue depth, throughput, last-scored-at, model warm-up state.

--format json is available on every subcommand for scripting.

rules

Inspect the loaded Sigma rule set (63 bundled rules + any directories listed under detection.sigma_rules_dirs).

seerflow rules list
seerflow rules list --technique T1110              # MITRE technique prefix match
seerflow rules list --tactic credential-access     # tactic name or ATT&CK ID
seerflow rules list --tactic TA0006
seerflow rules list --format json

hunt

Natural-language threat hunt — the query is translated to an EventQuery by the configured LLM (backend matrix) and executed against LogStore. The argument is positional; quote it.

seerflow hunt "show me failed SSH logins from 10.0.1.42 in the last 24h"
seerflow hunt "outbound DNS queries to flagged domains" --limit 100
seerflow hunt "ssh brute force attempts" --json

Flag	Default	Purpose
--limit	from llm.hunt_max_results	Max events to return
--db	from config	Override storage DB path
--json	false	Emit machine-readable JSON

Requires llm.backend to be configured. See Natural-Language Hunt for the request/response shape.

export

Stream stored events or alerts to NDJSON or CSV. Useful for backup, replay, or backend migration.

seerflow export events --since 7d --output events.ndjson
seerflow export events --since 24h --format csv --output events.csv
seerflow export alerts --since 7d --output alerts.ndjson

Flag	Default	Purpose
--format	json	json (NDJSON) or csv
--since	24h	Relative window (e.g. 1h, 30m, 7d)
--source	—	Filter by source type (events only)
--severity	—	Minimum severity 0–6 (events only)
--limit	100000	Row cap
--output	stdout	Output path

import

Ingest log files at high speed through the offline import path. Paths are positional and accept globs.

seerflow import /var/log/syslog
seerflow import '/var/log/*.log' --db /tmp/replay.db

Flag	Default	Purpose
--db	from config	Override storage DB path

status

Live pipeline metrics — receivers, queue depth, detection ensemble health, alert counts — fetched from the running Seerflow daemon’s local control endpoint.

seerflow status
seerflow status --json
seerflow status --timeout 5

templates

Inspect Drain3 templates in detail.

seerflow templates list --top 20
seerflow templates list --since 24h --format json
seerflow templates show <template-id>

Subcommand	Purpose
list	Persisted Drain3 templates ranked by recency or count.
show	Full template detail: matched count, first/last seen, example messages.

feedback

Label an alert as a true positive (tp) or false positive (fp). Feedback flows into the rule-suggestion pipeline (LLM Rule Suggestion) and the alert-store audit log.

seerflow feedback <alert-id> tp
seerflow feedback <alert-id> fp --note "ssh from ops jumphost"

Positional args: alert_id, then tp or fp. Optional --note.

graph

Entity-graph maintenance operations.

graph migrate

Move the entity graph between backends (igraph, falkordb, postgres_age).

seerflow graph migrate --from igraph --to falkordb --dry-run
seerflow graph migrate --from igraph --to falkordb
seerflow graph migrate --from falkordb --to igraph
seerflow graph migrate --from igraph --to falkordb --wipe-destination

--dry-run reports counts without writing. --wipe-destination is required if the destination already contains a graph.