Interactive or one shot
| Invocation | Result |
|---|---|
| No format flag on a terminal | Open the interactive view. |
--once | Print one human-readable snapshot and exit. |
--plain | Explicitly select the same one-shot text format. |
--json | Print one schema-versioned document. |
--jsonl | Print schema-versioned JSON Lines (suite-wide). |
--fields LIST | Project JSON/JSONL to named top-level fields (always keeps schema_version, generated_at, host). |
--quiet | Suppress stdout on success; errors still go to stderr. |
| Redirected output | Default to one-shot plain text unless a structured format was selected. |
Use --once when the important instruction is “do not open the TUI”; use --plain when the important instruction is “produce text, not JSON”. Assertion flags, --quiet, --json, --jsonl and --fields force one-shot mode even on a TTY. A closed downstream pipe is a normal exit, so lens-top --plain | head does not report an error.
Limits, filters and measurement
Specialists default to 1,000 rows per result type. --limit 0 is unbounded and should be paired with a deliberate filter or time range on busy hosts. --filter is a case-insensitive match over the values shown by that specialist; --match contains|exact controls how filters and name selectors bind (default contains). Domain selectors such as --name, --active, --port, --mount and --exact-name map to model fields. Flags used with the wrong command fail clearly instead of being ignored.
lens-top samples twice to calculate process CPU and I/O rates. One-shot output uses a fast measurement window capped at 250 ms unless you explicitly pass an interval; --interval 2s requests a two-second measurement.
Standard streams and exit status
0The command produced its result, and any assertion policy passed. Findings or collection warnings may still be present when no assert flags were used.1Collection, configuration, output or an action failed. The error is on standard error.2Command syntax, argument validation or an ambiguous action target failed before collection or mutation.3An opt-in assertion or expect policy failed after a successful collection.Normal output and action results use standard output. Collection warnings belong to a successful snapshot and appear in collection_warnings; they are not silently converted into zero counts.
Script without relying on jq
Findings do not change exit status by themselves. Use opt-in assertion flags for cron and health gates, or keep piping JSON to an external tool:
lens-health --fail-on critical --fail-on-collection-warnings --quiet
lens-services --name nginx.service --active active --fail-if-empty --quiet
lens-net --listening --port 22 --expect-count-min 1 --quiet
lens-health --json | jq -e '
(.collection_warnings | length) == 0 and
([.findings[] | select(.severity == "critical")] | length) == 0
'Shared assert flags include --fail-if-empty, --fail-if-any, --expect-count, --expect-count-min, --expect-count-max, --fail-on and --fail-on-collection-warnings. This separates collection failure from the threshold an operator chooses.
Structured snapshot
| Group | Top-level fields |
|---|---|
| Identity and load | host, processes, services, containers |
| Events | log_sources, logs |
| Storage | mounts, filesystems, deleted_open_files, block_devices |
| Network | interfaces, routes, sockets, cellular_modems |
| System context | clock, dns, accounts, groups, certificates |
| Hardware | hardware, temperatures, hardware_devices |
| Diagnosis | findings, relationships, collection_warnings |
| Contract | schema_version, generated_at, build |
Timestamps are UTC RFC 3339. Byte totals remain bytes, rates are bytes per second, durations are seconds and percentages are numeric. Optional or permission-limited values can be absent or null. Schema version 2 can gain additive optional fields; removing or changing a field or unit requires a new version.
Commands, account names, addresses, log text, SIM identifiers, certificate paths and hardware serial numbers can contain sensitive operational data.
Non-interactive actions are explicit
Process signals require --signal plus either --pid or filters that resolve to exactly one process, and either --dry-run or --yes. Linux service changes require --action plus --target or a unique selector (--name, --service, --filter, --active) and the same plan-or-confirm choice. Zero or multiple matches exit 2 before mutation. Optional --expect-name, --expect-start-ticks and --expect-active (with --wait) harden scripted use.
lens-top --signal term --pid 4242 --dry-run
lens-top --signal term --exact-name nginx --expect-name nginx --dry-run
lens-services --action restart --name nginx.service --match exact --expect-active active --dry-run