Reference

signalsctl CLI

A complete listing of the two Signals binaries and every subcommand and flag they accept. The signals daemon runs collection and serves the local API; the signalsctl client drives it and runs offline diagnostics.

signals (daemon)

The long-running collector. It loads its configuration, opens the local store, runs the collection loop, and serves the management API that signalsctl talks to.

Synopsis

signals --config <path>

Flags

--config <path> — path to the configuration file. When empty, the loader falls back to the lookup order below.

Configuration lookup order

The first existing file wins:

the path given to --config
/etc/signals/signals.yaml
./signals.yaml

Reloading

A running daemon re-reads its configuration without a restart on either a SIGHUP signal or a POST /reload API request. The new config is loaded and validated before it is applied; if loading or validation fails, the reload is rejected and the daemon keeps running on the previous configuration.

# Start the daemon
signals --config /etc/signals/signals.yaml

# Reload after editing the config, in place
kill -HUP "$(pgrep -f '^signals ')"

signalsctl (client)

The command-line client. Most subcommands call the daemon's HTTP API; doctor and connect instead read the config and probe targets directly, so they run without a live daemon.

Global flags

These persistent flags apply to every subcommand:

--api-addr <url> — Signals API address. Default http://127.0.0.1:8081.
--api-token <token> — API bearer token. Defaults to the $SIGNALS_API_TOKEN environment variable.

signalsctl version

Print version, commit, and build-date information for the client.

signalsctl version

signalsctl status

Show collector status as JSON. Issues a GET /status request to the daemon. Takes no flags beyond the global ones.

signalsctl status

signalsctl collect

Collection management. Parent command for now, pause, and resume.

collect now

Trigger an immediate collection cycle.

--force — bypass signals.min_snapshot_interval for this one cycle. Without it, a target collected inside the interval window is skipped.

signalsctl collect now
signalsctl collect now --force

collect pause

Pause collection for one target, or for every enabled target when --target is omitted. A paused target stays paused until collect resume is run; pause state is in-memory only, so a daemon restart resumes all targets.

--target=<name> — target name. Empty means every enabled target.
--reason="…"— operator-supplied reason (≤ 256 characters), recorded in the audit log.

signalsctl collect pause --target=prod-primary --reason="planned maintenance"

collect resume

Resume collection for a paused target, or for every enabled target when --target is omitted. Resume clears the paused state and resets the consecutive-failure counter. Unknown target names are rejected.

--target=<name> — target name. Empty means every enabled target.

signalsctl collect resume --target=prod-primary

signalsctl export

Export collected data as a ZIP archive. With no flags, the export contains only the latest completed snapshot per active target — the unit downstream consumers ingest as a single analysis. The selector flags widen or narrow that scope.

--output <file> (-o) — output file path. Defaults to signals-export-<timestamp>.zip.
--all — include every snapshot in local storage (forensic full-history). Mutually exclusive with --snapshot-id.
--snapshot-id <id> — include exactly one snapshot by id. Mutually exclusive with --all.
--since <RFC3339> — include snapshots collected at or after this timestamp.
--until <RFC3339> — include snapshots collected at or before this timestamp.
--target-id <int> — narrow the export to a single target. 0 means all targets.

# Latest snapshot per target (default)
signalsctl export

# Everything, to a named file
signalsctl export --all -o forensic.zip

# A single snapshot
signalsctl export --snapshot-id 42

# A time window for one target
signalsctl export --since 2026-06-01T00:00:00Z --until 2026-06-08T00:00:00Z --target-id 3

--all and --snapshot-id cannot be combined; supplying both is rejected as a usage error.

signalsctl doctor

Run read-only operator pre-flight checks against the config and targets. Reads the config from disk and probes targets directly — it does not call the daemon API. Exits 0 when every check is OK, 1 when any check fails, and 2 on usage errors (such as an unknown --check name).

--config <path> — path to the config file.
--check <name> — run only the named checks, e.g. --check=C1,C3.
--json — emit a JSON report instead of human-readable text.

The checks:

C1 config_valid — config parses and passes strict validation
C2 store_writable — the SQLite store path is writable
C3 target_reachable — each enabled target accepts TCP
C4 role_safe— each reachable target's role is not superuser, replication, or bypassrls
C5 collector_prerequisites— each target's enabled collectors are classified (available / missing / unsupported)
C6 snapshot_freshness— each target's latest snapshot is within 2× the poll interval

signalsctl doctor --config /etc/signals/signals.yaml
signalsctl doctor --check=C1,C3
signalsctl doctor --json

signalsctl connect

Connection diagnostics. Parent command for test and auto.

connect test

Test PostgreSQL connectivity and classify any failure into one of ok, dns, tcp, tls, auth, startup, role, password_resolve, or config. Exits 0 when every attempt is OK, 1 when any fails, and 2 on usage errors.

Modes:

signalsctl connect test — test every enabled target in the config
signalsctl connect test <target-name> — test one target from the config
signalsctl connect test --dsn "…" — test an ad-hoc DSN without a config

Flags:

--config <path> — path to the config file (ignored when --dsn is supplied).
--dsn "…" — ad-hoc DSN fields as space-separated key=value pairs. Mutually exclusive with a positional target name.
--json — emit a JSON report instead of human-readable text.

Recognised --dsn fields: host, port, dbname, and user are required; sslmode (default prefer), password_env, password_file, and pgpass_file are optional.

signalsctl connect test
signalsctl connect test prod-primary
signalsctl connect test --dsn "host=db port=5432 dbname=app user=signals sslmode=require" --json

connect auto

Guided onboarding for a single PostgreSQL target. Auto-detects the cloud platform and ambient identity, selects an auth method, resolves the credential without printing it, runs the connection diagnostic over verify-full, validates the role is read-only, and prints a ready-to-use, secret-free target config block on success. The default is dry-run (print only). Exits 0 on a verified connection, 1 on a fixable gap, and 2 on usage errors.

--host <host> — target host (required).
--port <int> — target port. Default 5432.
--dbname <db> — target database name.
--user <role> — role to authenticate as (required).
--auth-method <method> — override detection: password, aws_rds_iam, azure_entra, gcp_cloudsql_iam, secret_store, or mtls.
--write <path> — append the verified target block to this config file. Without it, the command is dry-run.

# Dry-run: detect, connect, verify, and print a config block
signalsctl connect auto --host db.example.com --user signals --dbname app

# Append the verified block to a config file
signalsctl connect auto --host db.example.com --user signals --dbname app \
  --auth-method aws_rds_iam --write /etc/signals/signals.yaml

No secret is ever printed by connect auto; the emitted target block is credential-free.