CLI Reference¶

Seerflow ships a single entry-point binary, seerflow, with eleven top-level subcommands:

Group	Commands
Runtime	`start`, `status`, `tail`
Ingest	`import`
Read / inspect	`query`, `export`, `templates`, `rules`
LLM / hunt	`hunt`
Operator feedback	`feedback`
Graph maintenance	`graph migrate`

All subcommands accept --help and respect the global --config flag.

Global Options¶

seerflow [--config PATH] [--version] COMMAND

Option	Type	Default	Description
`--config PATH`	`str`	search CWD	Path to `seerflow.yaml`. When omitted, Seerflow searches the current working directory.
`--version`	flag	—	Print the installed version string and exit.

seerflow start¶

Synopsis¶

seerflow [--config PATH] start

Description¶

Starts the Seerflow pipeline. Seerflow reads the active configuration file, enables all receivers declared under receivers:, and begins processing incoming log streams through parsing, anomaly detection, correlation, and alerting stages. The process runs until interrupted with Ctrl+C.

Examples¶

# Start with the default seerflow.yaml in the current directory
seerflow start

# Start with an explicit config path
seerflow --config /etc/seerflow/seerflow.yaml start

seerflow status¶

Synopsis¶

seerflow [--config PATH] status [--json] [--timeout SECONDS]

Description¶

Polls the local health endpoint of a running Seerflow daemon (default http://127.0.0.1:<dashboard_port>) and prints a merged health + stats document — pipeline state, receiver throughput, detector health, queue depths, and storage readiness. Useful for systemd / container health probes and post-deploy smoke tests.

Options¶

Option	Type	Default	Description
`--json`	flag	`false`	Emit the merged document as JSON instead of a formatted summary.
`--timeout SECONDS`	`float`	`3.0`	HTTP timeout per request. Must be in `[0.1, 30]` seconds.

Examples¶

# Human-readable summary
seerflow status

# Strict timeout, JSON output for an external probe
seerflow status --json --timeout 1.5

seerflow tail¶

Synopsis¶

seerflow tail PATH [PATH ...]

Description¶

Monitor one or more log files in real time without loading a full configuration. Useful for quickly inspecting a live log stream or testing parsing and template extraction outside of a running pipeline.

Arguments¶

Argument	Type	Description
`PATH`	`str` (one or more)	File paths or glob patterns to watch (e.g., `/var/log/nginx/*.log`). At least one path is required.

Examples¶

# Watch a single file
seerflow tail /var/log/syslog

# Watch multiple files with a glob pattern
seerflow tail /var/log/nginx/access.log /var/log/nginx/error.log

# Glob expansion (shell expands before passing to seerflow)
seerflow tail /var/log/app/*.log

seerflow import¶

Synopsis¶

seerflow import [--db PATH] PATH [PATH ...]

Description¶

Batch-imports one or more static log files into the Seerflow database. Events are parsed, templated via Drain3, scored, and written to the configured storage backend. Plain .log and compressed .gz, .bz2, .xz archives are auto-detected; binary files are skipped. Use this command to backfill historical data or to pre-load a test dataset before starting the live pipeline.

Arguments and Options¶

Argument / Option	Type	Default	Description
`PATH`	`str` (one or more)	—	Log file paths or glob patterns to import. At least one path is required.
`--db PATH`	`str`	from config	Override the database path. When omitted, Seerflow uses the path from the active configuration file.

Examples¶

# Import a single file using the configured database
seerflow import /var/log/auth.log

# Import multiple files with a glob pattern
seerflow import /backup/logs/2026-03/*.log

# Import a compressed archive (auto-detected)
seerflow import /backup/logs/auth-2026-03.log.gz

# Import into a specific database
seerflow import --db /data/seerflow.db /var/log/app.log

seerflow query¶

Synopsis¶

seerflow query {events,alerts,templates,timeline,health} [OPTIONS]

Retrieves stored data from the Seerflow database. Each subcommand targets a specific data type. All subcommands support --json for machine-readable output.

query events¶

Query raw log events persisted by the pipeline.

seerflow query events [--last WINDOW] [--template ID] [--source TYPE]
                      [--severity INT] [--limit INT] [--json]

Option	Type	Default	Description
`--last WINDOW`	`str`	—	Restrict results to the given time window (e.g., `1h`, `30m`, `7d`). When omitted, all stored events are eligible.
`--template ID`	`int`	—	Filter by Drain3 template ID.
`--source TYPE`	`str`	—	Filter by source type string (e.g., `nginx`, `syslog`).
`--severity INT`	`int`	—	Minimum severity level (0–6, OpenTelemetry scale).
`--limit INT`	`int`	`50`	Maximum number of results to return.
`--json`	flag	`false`	Output results as a JSON array instead of a formatted table.

# Last 30 minutes of events, severity 4 or higher
seerflow query events --last 30m --severity 4

# Events matching template 12 from nginx, output as JSON
seerflow query events --template 12 --source nginx --json

# Increase result limit
seerflow query events --last 1h --limit 200

query alerts¶

Query alerts generated by the detection and correlation stages.

seerflow query alerts [--last WINDOW] [--type TYPE] [--severity INT]
                      [--tactic TACTIC] [--technique TECHNIQUE]
                      [--limit INT] [--json]

Option	Type	Default	Description
`--last WINDOW`	`str`	—	Time window (e.g., `1h`, `30m`, `7d`).
`--type TYPE`	`str`	—	Alert type: `ml`, `sigma`, `correlation`, `ueba`, or `ioc`.
`--severity INT`	`int`	—	Minimum severity (0–6).
`--tactic TACTIC`	`str`	—	Filter by MITRE ATT&CK tactic (case-insensitive, e.g., `discovery`).
`--technique TECHNIQUE`	`str`	—	Filter by ATT&CK technique ID (case-insensitive, e.g., `t1033`).
`--limit INT`	`int`	`50`	Maximum results to return.
`--json`	flag	`false`	Output as JSON.

# All ML alerts from the last hour
seerflow query alerts --last 1h --type ml

# Sigma alerts mapped to the "discovery" tactic
seerflow query alerts --type sigma --tactic discovery

# Alerts for ATT&CK technique T1078, output as JSON
seerflow query alerts --technique t1078 --json

# High-severity alerts in the last day
seerflow query alerts --last 7d --severity 4 --limit 100

query templates¶

List Drain3 log templates learned by the parser.

seerflow query templates [--limit INT] [--json]

Option	Type	Default	Description
`--limit INT`	`int`	`50`	Maximum number of templates to return.
`--json`	flag	`false`	Output as JSON.

# Show top 50 templates in table format
seerflow query templates

# Show up to 200 templates as JSON
seerflow query templates --limit 200 --json

query timeline¶

Retrieve the event timeline for a specific entity, identified by its UUID5.

seerflow query timeline ENTITY_UUID [--last WINDOW] [--source TYPE]
                        [--severity INT] [--limit INT] [--json]

Argument / Option	Type	Default	Description
`ENTITY_UUID`	`str`	—	Entity UUID5 string (required). Obtain entity UUIDs from `query alerts` or the entity graph.
`--last WINDOW`	`str`	—	Restrict to the given time window (e.g., `1h`, `30m`, `7d`).
`--source TYPE`	`str`	—	Filter by source type.
`--severity INT`	`int`	—	Minimum severity (0–6).
`--limit INT`	`int`	`1000`	Maximum number of events to return.
`--json`	flag	`false`	Output as JSON.

# Full timeline for an entity (last 1000 events)
seerflow query timeline 550e8400-e29b-41d4-a716-446655440000

# Last hour of activity from a specific source
seerflow query timeline 550e8400-e29b-41d4-a716-446655440000 --last 1h --source syslog

# High-severity events only, as JSON
seerflow query timeline 550e8400-e29b-41d4-a716-446655440000 --severity 4 --json

query health¶

Display health and performance statistics for the detection ensemble.

seerflow query health [--json]

Option	Type	Default	Description
`--json`	flag	`false`	Output stats as JSON.

# Human-readable health summary
seerflow query health

# JSON output for integration with monitoring tools
seerflow query health --json

seerflow export¶

Synopsis¶

seerflow export {events,alerts} [OPTIONS]

Stream events or alerts to a file (or stdout) for offline analysis, backups, or feeding downstream SIEMs. Output is NDJSON by default — one record per line — or CSV when requested. Memory usage is O(1) regardless of result size; rows are written as they are read.

Filters mirror query so the same dataset can be inspected interactively and exported reproducibly.

Shared options¶

Option	Type	Default	Description
`--format {json,csv}`	choice	`json`	`json` produces NDJSON (one record per line).
`--since WINDOW`	`str`	`24h`	Time window relative to now (e.g., `1h`, `7d`).
`--severity INT`	`int`	—	Minimum severity.
`--limit INT`	`int`	`100000`	Maximum rows exported.
`--output PATH`	`str`	stdout	Output file path.

export events¶

seerflow export events [--format {json,csv}] [--since WINDOW]
                       [--source TYPE] [--severity INT] [--limit INT]
                       [--output PATH]

Extra option	Description
`--source TYPE`	Filter by source type (e.g., `nginx`).

export alerts¶

seerflow export alerts [--format {json,csv}] [--since WINDOW]
                       [--type TYPE] [--severity INT] [--limit INT]
                       [--output PATH]

Extra option	Description
`--type TYPE`	Alert type filter (`ml`, `sigma`, `correlation`, `ueba`, `ioc`).

Examples¶

# Last 24h of events to stdout as NDJSON
seerflow export events

# Last 7d of high-severity Sigma alerts to a CSV file
seerflow export alerts --since 7d --type sigma --severity 4 \
                       --format csv --output sigma-alerts.csv

# Pipe NDJSON into jq
seerflow export events --since 1h | jq '.entity_uuid' | sort -u

seerflow templates¶

Synopsis¶

seerflow templates {list,prune,reset} [OPTIONS]

Manage the persistent Drain3 template store. Templates accumulate as the parser observes new log formats; prune removes infrequent templates that bloat the working set without contributing detection signal, and reset wipes the parser state entirely (useful after a major log-source change).

templates list¶

seerflow templates list [--limit INT] [--json]

Option	Type	Default	Description
`--limit INT`	`int`	`100`	Max rows to print (cap: 10000).
`--json`	flag	`false`	Emit JSON instead of a table.

templates prune¶

seerflow templates prune --min-count N [--yes] [--json]

Option	Type	Default	Description
`--min-count N`	`int` (required)	—	Delete templates with `event_count` strictly less than `N`. `N >= 0`.
`--yes`	flag	`false`	Skip the interactive confirmation prompt.
`--json`	flag	`false`	One-line JSON summary.

templates reset¶

seerflow templates reset [--yes] [--json]

Wipes all templates and the persisted Drain3 parser state. The parser will re-learn from scratch on the next run.

Examples¶

# Show the 100 most-used templates
seerflow templates list

# Drop templates seen fewer than 5 times (with confirmation)
seerflow templates prune --min-count 5

# Reset Drain3 state non-interactively in a script
seerflow templates reset --yes --json

seerflow rules¶

Synopsis¶

seerflow rules list [--technique ID] [--tactic NAME_OR_ID]
                    [--format {table,json}]

Inspect the Sigma rules loaded into the running configuration. Useful for confirming which rules cover a given ATT&CK technique before incident response, and for verifying that a custom rule loaded successfully.

Option	Type	Default	Description
`--technique ID`	`str`	—	Filter by ATT&CK technique. Prefix match — `T1053` includes sub-techniques (`T1053.001`, …).
`--tactic NAME_OR_ID`	`str`	—	Filter by tactic name (`persistence`) or ID (`TA0003`).
`--format {table,json}`	choice	`table`	Output format.

Examples¶

# Every rule mapping to T1053 scheduled-task techniques
seerflow rules list --technique T1053

# JSON dump of persistence rules
seerflow rules list --tactic persistence --format json

seerflow hunt¶

Synopsis¶

seerflow hunt "NATURAL LANGUAGE QUERY" [--limit INT] [--db PATH] [--json]

Description¶

Natural-language threat hunt. The configured LLM backend (llm.backend = llama_cpp | ollama | cloud) translates the prompt into an internal EventQuery and runs it against the event store. If the LLM is unavailable or the query contains an entity-style token (IPv4, hostname, entity UUID5), Seerflow falls back to a deterministic entity-timeline lookup so the command remains useful without LLM configured.

Arguments and Options¶

Argument / Option	Type	Default	Description
`QUERY`	`str` (required)	—	Free-text hunt query.
`--limit INT`	`int`	from config (`llm.hunt_max_results`, 100)	Max events returned.
`--db PATH`	`str`	from config	Override the database path.
`--json`	flag	`false`	Output as JSON.

Examples¶

# Conceptual hunt — requires an LLM backend
seerflow hunt "any failed logins from new IPs in the last hour"

# Entity hunt — works without an LLM (timeline fallback)
seerflow hunt "10.0.1.42"

# Cap results and emit JSON for a notebook
seerflow hunt "PowerShell execution by service accounts" --limit 50 --json

See LLM Integration for backend setup.

seerflow feedback¶

Synopsis¶

seerflow feedback ALERT_ID {tp,fp} [--note TEXT]

Description¶

Submit a true-positive or false-positive judgment on a specific alert. False positive (fp) feedback is propagated to the DSPOT auto-threshold system, raising the alert threshold for that detector to reduce noise on similar future events. True positives can also be used by the LLM rule-suggestion service to seed Sigma drafts. Feedback is persisted alongside the alert. See Alerting — Feedback Loop for details on how feedback adjusts detection sensitivity.

Arguments and Options¶

Argument / Option	Type	Description
`ALERT_ID`	`str`	The ID of the alert to label. Obtain alert IDs from `seerflow query alerts`.
`{tp,fp}`	choice	Feedback type: `tp` (true positive) or `fp` (false positive).
`--note TEXT`	`str`	Optional free-text note attached to the feedback record (default: empty string).

Examples¶

# Mark alert as a true positive
seerflow feedback alert-abc123 tp

# Mark alert as false positive with an explanatory note
seerflow feedback alert-abc123 fp --note "Scheduled maintenance window, expected behaviour"

# True positive with analyst note
seerflow feedback alert-xyz789 tp --note "Confirmed lateral movement from IR team"

seerflow graph¶

Synopsis¶

seerflow graph migrate --from {igraph,falkordb,postgres_age}
                       --to   {igraph,falkordb,postgres_age}
                       [--batch-size N] [--dry-run] [--wipe-destination]

Description¶

Move the persisted entity graph between backends. Use this when switching from the zero-config igraph in-process backend to a clustered backend (falkordb, postgres_age) for production scale, or back down for debugging.

The migration streams edges in batches and verifies counts at the end. With --wipe-destination, the destination is emptied first and strict count equality is enforced.

Option	Type	Default	Description
`--from {igraph,falkordb,postgres_age}`	choice (required)	—	Source graph backend.
`--to {igraph,falkordb,postgres_age}`	choice (required)	—	Destination graph backend.
`--batch-size N`	positive `int`	`5000`	Edges per write batch.
`--dry-run`	flag	`false`	Report projected edge/vertex counts only.
`--wipe-destination`	flag	`false`	Empty the destination before streaming (strict count check).

Examples¶

# Dry-run estimate before committing to a backend swap
seerflow graph migrate --from igraph --to falkordb --dry-run

# Hot migration into FalkorDB
seerflow graph migrate --from igraph --to falkordb \
                       --batch-size 10000 --wipe-destination

# Roll back to in-process igraph
seerflow graph migrate --from falkordb --to igraph --wipe-destination

See Graph Backends for backend trade-offs and required configuration.