CLI Reference¶

All CLI commands run inside Docker via ./run_cli.sh. Arguments are passed to python3 -m src.cli.main. See Configuration for environment and Docker Architecture for how the CLI container connects to Postgres and Redis.

Running the CLI¶

Bash

./run_cli.sh --help
./run_cli.sh <command> [options]

Global options (before the command):

Option	Description
`--config PATH`	Configuration file or directory (e.g. `config/sources.yaml`)
`--database-url URL`	Override database URL
`--debug` / `--no-debug`	Enable or disable debug logging (default: off)

Commands¶

init¶

When: First-time setup or after adding/editing sources in YAML. Loads sources from config into the database and optionally validates RSS feeds.

Options:

Option	Default	Description
`--config PATH`	(from global or ctx)	Config file or directory
`--validate-feeds` / `--no-validate-feeds`	`True`	Validate RSS feeds on load

Examples:

Bash

./run_cli.sh init --config config/sources.yaml
./run_cli.sh init --config config/sources.yaml --no-validate-feeds

See also: Add feed, Source config precedence.

collect¶

When: Manual fetch from configured sources. Normally the scheduler runs collection; use this for one-off runs or testing. Use --dry-run to see what would be collected without saving.

Options:

Option	Description
`--source ID`	Collect only from this source identifier
`--force`	Collect even if source is not due per schedule
`--dry-run`	Do not save articles; show what would be collected

Examples:

Bash

./run_cli.sh collect --dry-run
./run_cli.sh collect --source threatpost --dry-run
./run_cli.sh collect --source threatpost --force

The CLI runtime intentionally omits the browser stack. RSS and ordinary HTTP sources run normally; a source configured for JavaScript rendering reports a clear runtime message directing you to the Playwright-enabled ingestion worker.

search¶

When: Query articles in the database by text, source, and time window. Use for ad-hoc lookup or piping to other tools (e.g. --format json).

Options:

Option	Default	Description
`--query TEXT`	—	Search query (title/content)
`--source ID`	—	Filter by source identifier
`--days N`	`30`	Only articles from last N days
`--limit N`	`50`	Max results
`--format table\|json`	`table`	Output format

Examples:

Bash

./run_cli.sh search --query ransomware --limit 25 --format json
./run_cli.sh search --source threatpost --days 7
./run_cli.sh search --query CVE --limit 10 --format table

sync-sources¶

When: After editing config/sources.yaml (add/remove/change sources). Pushes YAML state into the database. Use --no-remove to add/update without deleting DB sources that are missing from YAML.

Options:

Option	Default	Description
`--config PATH`	`config/sources.yaml`	Path to sources YAML
`--no-remove`	`False`	Do not remove DB sources that are not in YAML
`--new-only`	`False`	Only insert new sources; skip updating existing ones (preserves DB configs)

Examples:

Bash

./run_cli.sh sync-sources --config config/sources.yaml --no-remove --new-only  # safest: add new, skip existing, no deletes
./run_cli.sh sync-sources --config config/sources.yaml --no-remove              # add/update, no deletes
./run_cli.sh sync-sources --config config/sources.yaml                          # full sync: add/update/delete

See also: Add feed, Source config precedence.

compare-sources¶

When: Compare database source settings with sources.yaml to see drift (only in YAML, only in DB, or field differences). Use before or after sync-sources to verify consistency.

Options:

Option	Default	Description
`--config-path PATH`	`SOURCES_CONFIG` or `config/sources.yaml`	Path to sources YAML

Examples:

Bash

./run_cli.sh compare-sources
./run_cli.sh compare-sources --config-path config/sources.yaml

See also: Sync sources, Source config precedence.

backup¶

When: Create, list, restore, or verify system backups; prune old backups. For full procedures see Backup & Restore.

Subcommands:

Subcommand	Description
`create`	Create backup (full, database, or files)
`list`	List available backups
`restore BACKUP_NAME`	Restore from backup
`verify BACKUP_NAME`	Verify backup integrity
`prune`	Remove old backups by retention policy
`stats`	Show backup statistics

Options (create):

Option	Default	Description
`--backup-dir PATH`	`backups`	Backup directory
`--type full\|database\|files`	`full`	Backup type
`--no-compress`	—	Skip compression
`--no-verify`	—	Skip file validation

Options (restore): --backup-dir, --components (comma-separated), --no-snapshot, --force, --dry-run.

Options (verify): --backup-dir, --test-restore.

Options (prune): --backup-dir, --daily (default 7), --weekly (4), --monthly (3), --max-size-gb (50), --dry-run, --force.

Examples:

Bash

./run_cli.sh backup create --backup-dir backups/
./run_cli.sh backup create --type database
./run_cli.sh backup list
./run_cli.sh backup list --show-details
./run_cli.sh backup restore system_backup_20251010_103000 --dry-run
./run_cli.sh backup verify system_backup_20251010_103000
./run_cli.sh backup prune --dry-run
./run_cli.sh backup stats

See also: Backup & Restore.

cron¶

When: Inspect or replace the current user's crontab (e.g. for backup schedule). Used by the Settings UI and automation; run via CLI to view or edit cron jobs directly.

Subcommands:

Subcommand	Description
`show`	Show cron jobs from current user's crontab
`set`	Replace crontab with jobs read from a file (`--file PATH`, required)

Options (show):

Option	Description
`--raw`	Print raw crontab instead of parsed job list

Options (set):

Option	Description
`--file PATH`	Path to a file containing the full replacement crontab (required)

Examples:

Bash

./run_cli.sh cron show
./run_cli.sh cron show --raw
./run_cli.sh cron set --file new_crontab.txt

Note: backup also has its own cron subgroup (backup cron show|apply|disable) for CTI-owned backup automation via BackupCronService, separate from the top-level cron command above, which reads/replaces the raw crontab.

See also: Backup & Restore (Automated Backups), Settings → Backup schedule.

rescore¶

When: Regenerate keyword-based threat hunting scores (threat_hunting_score in article metadata). Use after changing scoring rules or to backfill missing scores.

Options:

Option	Description
`--article-id ID`	Rescore only this article (including archived)
`--force`	Rescore even if score already exists
`--dry-run`	Compute scores but do not save

Examples:

Bash

./run_cli.sh rescore --article-id 123 --dry-run
./run_cli.sh rescore --force
./run_cli.sh rescore

See also: Scoring. After scoring-rule changes, run ./run_cli.sh rescore --force (per AGENTS.md).

embed¶

When: Manage article embeddings for MCP semantic search and Sigma similarity. Use embed stats to see coverage; use embed embed (the embedding generation subcommand inside the embed group) to generate embeddings for articles that don't have them (queues a Celery task). Use embed search for semantic search from the CLI.

Note: The embedding generation subcommand is embed embed (not just embed by itself). Example: ./run_cli.sh embed embed --batch-size 1000

Subcommands:

Subcommand	Description
`embed`	Generate embeddings for articles missing them (interactive confirm; use `--dry-run` to preview)
`stats`	Show embedding coverage (total, embedded, pending, per-source)
`search`	Semantic search: prompt for query, return similar articles

Options (embed embed):

Option	Default	Description
`--batch-size N`	`1000`	Batch size for processing
`--source-id ID`	—	Only embed articles from this source
`--dry-run`	—	Show what would be processed, do not run task

Options (embed search):

Option	Default	Description
`--limit N`	`10`	Number of results
`--threshold T`	`0.7`	Similarity threshold (0–1)
`--source-id ID`	—	Filter by source ID

Examples:

Bash

./run_cli.sh embed stats
./run_cli.sh embed embed --dry-run
./run_cli.sh embed embed --source-id 1
./run_cli.sh embed search --limit 5 --threshold 0.75

See also: Semantic Search, Sigma Detection Rules.

sigma¶

When: Sync SigmaHQ rules, index them (metadata and optionally embeddings), and match articles to rules. Required for Sigma similarity search and workflow Sigma generation. Indexing is split into metadata (always available) and embeddings (optional; uses local sentence-transformers, no LM Studio required).

Subcommands:

Subcommand	Description
`sync`	Clone or pull SigmaHQ rules repository
`index`	Full index: metadata then embeddings (orchestrator; use for backward compatibility)
`index-metadata`	Index rule metadata and canonical fields only (no embeddings)
`index-embeddings`	Generate embeddings for rules (uses local intfloat/e5-base-v2)
`index-customer-repo`	Index approved rules from customer repo (SIGMA_REPO_PATH) for similarity search
`backfill-metadata`	Recompute canonical fields for existing rules (no repo access needed)
`recompute-atoms`	Backfill `canonical_class`, `atoms`, `surface_score` for all indexed rules (requires `sigma_similarity` package)
`match ARTICLE_ID`	Match one article to Sigma rules; prints the top 10 matches with coverage classification (does not persist)
`stats`	Show Sigma rule and match statistics

Options (sync): --force — force re-clone.

Options (index, index-metadata, index-embeddings): --force — re-index all (or all embeddings).

Options (index-customer-repo): --force — re-index all customer rules; --no-embeddings — metadata only.

Options (match): --threshold T (default 0.7). Examples:

Bash

./run_cli.sh sigma sync
./run_cli.sh sigma index
./run_cli.sh sigma index-metadata --force
./run_cli.sh sigma index-embeddings
./run_cli.sh sigma index-customer-repo   # Include customer repo rules in similarity search
./run_cli.sh sigma backfill-metadata          # Backfill canonical_json/exact_hash/logsource_key for rules missing them
./run_cli.sh sigma backfill-metadata --force  # Recompute those fields for ALL rules (use when the canonical logic changed)
./run_cli.sh sigma recompute-atoms   # Backfill canonical_class, atoms, surface_score (requires sigma_similarity)
./run_cli.sh sigma match 123 --threshold 0.7
./run_cli.sh sigma stats

Note: Sigma rule embeddings use local sentence-transformers (intfloat/e5-base-v2) inside the CLI container; LM Studio is not required for indexing. Run sigma index-metadata first (or sigma index); then run sigma index-embeddings to enable Sigma rule retrieval via MCP. Use capabilities check to see current feature status.

index-embeddings embeds rules in chunks and commits each chunk, so it is resumable: without --force it processes only rules whose embedding is missing, and re-running after an interrupt (e.g. an OOM kill on a memory-constrained host) continues from where it stopped. On low-memory hosts, set SIGMA_EMBED_RULES_PER_CHUNK (default 64) lower to reduce peak memory, e.g. SIGMA_EMBED_RULES_PER_CHUNK=32 ./run_cli.sh sigma index-embeddings.

See also: Generate Sigma, Sigma Detection Rules.

capabilities¶

When: Check which features are available in the current environment (article retrieval, Sigma metadata/embedding indexing, Sigma retrieval via MCP, LLM generation). Used by setup/start scripts and for troubleshooting.

Subcommands:

Subcommand	Description
`check`	Print capability table (enabled/disabled, reason, action)

Options (check): --json-output — output JSON for shell scripts (e.g. startup warnings).

Examples:

Bash

./run_cli.sh capabilities check
./run_cli.sh capabilities check --json-output

See also: Sigma, Semantic Search.

export¶

When: Dump articles to JSON or CSV for analysis, reporting, or migration. Uses last N days and optional source filter.

Options:

Option	Default	Description
`--format json\|csv`	`json`	Output format
`--days N`	`7`	Articles from last N days
`--output PATH`	—	Write to file (default: stdout)
`--source ID`	—	Export only from this source

Examples:

Bash

./run_cli.sh export --format json --days 14 --output articles.json
./run_cli.sh export --format csv --source threatpost
./run_cli.sh export --days 30

stats¶

When: Quick overview of database state (sources, article counts, recent activity).

Options: None.

Example:

Bash

./run_cli.sh stats

archive¶

When: Soft-delete articles (archive) or restore them (unarchive). Useful for cleaning up or hiding a source's articles without losing data.

Subcommands:

Subcommand	Description
`add`	Archive articles (`--article-id` or `--source-id`)
`remove`	Unarchive articles
`list`	List archived articles
`cleanup`	Show archive statistics

Options (add / remove):

Option	Description
`--article-id ID`	Single article
`--source-id ID`	All articles from this source
`--dry-run`	Show what would be archived/unarchived
`--force`	Skip confirmation

Examples:

Bash

./run_cli.sh archive add --article-id 456 --dry-run
./run_cli.sh archive add --source-id 2 --force
./run_cli.sh archive remove --article-id 456
./run_cli.sh archive list --limit 50

Quick reference table¶

Command	When to use
`init`	First setup; load sources from YAML into DB
`collect`	Manual fetch from sources (scheduler does this automatically)
`search`	Query articles (text, source, time window)
`sync-sources`	Apply YAML source changes to DB (`--no-remove` to keep extras; `--new-only` to skip existing)
`compare-sources`	Compare DB source settings vs sources.yaml (drift check)
`backup create/list/restore/verify/prune/stats`	Full backup workflow
`rescore`	Recompute keyword-based threat hunting scores
`embed embed` / `embed stats` / `embed search`	Embedding coverage, generation, coverage stats, semantic search
`sigma sync/index/index-metadata/index-embeddings/index-customer-repo/backfill-metadata/recompute-atoms/match/stats`	Sigma rules: sync, index, semantic backfill, matching
`capabilities check`	Runtime feature capability status
`export`	Dump articles to JSON/CSV
`stats`	DB summary (sources, articles, activity)
`archive add/remove/list/cleanup`	Soft-delete, or restore, or clean up articles

Last updated: 2026-07-03 Last reviewed: 2026-09-01