Synadia Insights
CLI
The insights binary is a single command with several subcommands. Running insights with no subcommand starts the server. The other subcommands (query, checks, backup) talk to an already-running server over NATS.
Synopsis
insights [flags] [subcommand] [subcommand-flags]
| Subcommand | Purpose |
|---|---|
(default) run | Start the Insights server. |
query | Run a SQL query against the embedded DuckDB over the NATS API. |
checks list | List all available audit checks grouped by category. |
checks info <CODE> | Show full metadata and configurable parameters for one check. |
checks findings <CODE> | Run one audit check and return its findings. |
backup | Create a consistent database snapshot and download it. |
--version | Print the binary version and exit. |
Configuration precedence
When a setting is defined in more than one place, the highest-priority source wins:
- Command-line flags
- Environment variables (
INSIGHTS_*) - YAML config file (
--config/-c) - Built-in defaults
Environment variables mirror the flag path: dots become underscores, everything is uppercased, and the INSIGHTS_ prefix is added. For example, --web.port becomes INSIGHTS_WEB_PORT, and --sys.server becomes INSIGHTS_SYS_SERVER.
Top-level flags
These flags apply to every subcommand.
| Flag | Env | Default | Description |
|---|---|---|---|
--log-level | INSIGHTS_LOG_LEVEL | info | Log level: debug, info, warn, error. |
--nats.server | INSIGHTS_NATS_SERVER | nats://127.0.0.1:4222 | NATS server URL used by subcommands (query, checks, backup) to reach the Insights API. |
--nats.creds | INSIGHTS_NATS_CREDS | (empty) | Path to a NATS credentials file. |
--nats.context | INSIGHTS_NATS_CONTEXT | (empty) | NATS CLI context name (resolved via ~/.config/nats/). |
See Configuration > nats.* for the full nats.* reference (TLS, auth, socks proxy).
insights run
Default subcommand. Starts the Insights server: scraper, indexer, web UI, sink, backup scheduler, and the NATS API endpoints.
insights run [flags]
Because run is the default, you can omit the subcommand name:
insights --config /etc/insights/config.yaml
Flags
run owns every server-only subsystem flag. Rather than duplicate them all here, see the Configuration reference. Each subsystem (scraper, indexer, web, sink, simulator, backup, database, license, and so on) has its own section there.
Frequently used flags:
| Flag | Env | Default | Description |
|---|---|---|---|
--config / -c | (none) | (empty) | Path to YAML config file. |
--data-dir | INSIGHTS_DATA_DIR | (temp dir) | Base directory for DuckDB and JetStream data. |
--simulator.enabled | INSIGHTS_SIMULATOR_ENABLED | false | Run against the built-in simulator instead of a real NATS system. License validation is skipped when enabled. |
--sys.server | INSIGHTS_SYS_SERVER | (empty) | NATS URL of the target system to scrape. |
--sys.creds | INSIGHTS_SYS_CREDS | (empty) | NATS credentials file for the target system. |
--web.hostname | INSIGHTS_WEB_HOSTNAME | 127.0.0.1 | Web UI bind address. |
--web.port | INSIGHTS_WEB_PORT | 8080 | Web UI bind port. |
--license.token | INSIGHTS_LICENSE_TOKEN | (empty) | License JWT string. |
--license.file | INSIGHTS_LICENSE_FILE | (empty) | Path to a file containing the license JWT. |
Example
insights \
--config /etc/insights/config.yaml \
--license.file /etc/insights/license.jwt \
--web.hostname 0.0.0.0
insights query
Send a SQL query to the running Insights server over NATS and write the result to stdout. See the Search reference for the Insights query language. Use query for arbitrary DuckDB SQL against the hx schema.
insights query [flags] [SQL]
The SQL statement can be passed as a positional argument or piped on stdin. If both are omitted, the command exits with an error.
Flags
| Flag | Env | Default | Description |
|---|---|---|---|
--format / -f | (none) | csv | Output format: csv or json. |
--timeout | (none) | 30s | NATS request timeout. |
Plus the top-level --nats.* flags for reaching the server.
Examples
Inline SQL:
insights query "SELECT name, cpu FROM hx.servers ORDER BY cpu DESC LIMIT 10"
SQL via stdin:
cat query.sql | insights query --format json
Against a remote Insights server:
insights --nats.server nats://insights.example.com:4222 \
--nats.creds ~/.config/nats/ops.creds \
query "SELECT COUNT(*) FROM hx.connections"
insights checks list
List every audit check the server knows about, grouped by category. Default output is an aligned text table; pass --format for CSV or JSON.
insights checks list [flags]
Flags
| Flag | Env | Default | Description |
|---|---|---|---|
--format / -f | (none) | text | Output format: text, csv, or json. |
--timeout | (none) | 30s | NATS request timeout. |
Example
insights checks list --format json | jq '.[] | .label'
insights checks info
Show the full metadata for a single check: description, severity, scope, and any tunable parameters with their default and currently resolved values.
insights checks info [flags] <CODE>
Flags
| Flag | Env | Default | Description |
|---|---|---|---|
--format / -f | (none) | text | Output format: text or json. |
--timeout | (none) | 30s | NATS request timeout. |
Example
insights checks info SERVER_003
insights checks findings
Run one audit check by code over a time window and return the resulting findings.
insights checks findings [flags] <CODE>
<CODE> is a check code such as SERVER_001 or JETSTREAM_015. See the Audit Checks Reference for the full catalogue.
Flags
| Flag | Env | Default | Description |
|---|---|---|---|
--format / -f | (none) | text | Output format: text, csv, or json. The JSON response includes pagination metadata. |
--timeout | (none) | 30s | NATS request timeout. |
--duration | (none) | (empty) | Relative window as a DuckDB interval (e.g. 1 hour, 15 minutes, 7 days). |
--start | (none) | (empty) | Absolute start time (UTC, YYYY-MM-DDTHH:MM:SS). When omitted, derived from --duration. |
--end | (none) | (empty, meaning "live") | Absolute end time (UTC). |
--page | (none) | 1 | Page number (1-based) when results exceed one page. |
Example
Run SERVER_003 (High CPU Usage) against the last hour:
insights checks findings SERVER_003 --duration "1 hour"
Page through findings as JSON (1-based):
insights checks findings JETSTREAM_001 --format json --page 2
insights backup
Create a consistent snapshot of the Insights database, upload it to the JetStream object store, and download it locally. This is the recommended way to archive historical data. The server copies tables into a new DuckDB file without blocking live writes.
insights backup [flags]
backup always prints a plan summary (time range, epoch coverage, estimated file size) to stderr. When stdin is a terminal, it prompts for confirmation before running. Pass --force / -f to skip the prompt. --force is required when running non-interactively (for example, cron or CI).
Flags
| Flag | Env | Default | Description |
|---|---|---|---|
--output / -o | (none) | (server-generated filename) | Local output path. Use - to stream to stdout. |
--start | (none) | (no lower bound) | Start time: absolute (YYYY-MM-DD, RFC3339, or YYYY-MM-DDTHH:MM:SS UTC) or relative duration (7d, 1h, 30m). |
--end | (none) | (latest epoch) | End time: same formats as --start. |
--force / -f | (none) | false | Skip the confirmation prompt. Required for non-interactive use. |
--timeout | (none) | 10m | NATS request timeout for the backup operation. |
Examples
Back up the last seven days, prompting for confirmation:
insights backup --start 7d --output weekly-backup.db
Non-interactive full backup to a dated filename:
insights backup --force --output "insights-$(date +%Y%m%d).db"
Stream a backup to another host over SSH:
insights backup --force --output - | ssh archive "cat > /backups/insights-$(date +%s).db"
--version
Print the binary version and exit. Recognized only as the sole argument:
insights --version
Official release binaries print a semantic version. Unstamped binaries print dev.