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. |
lens-top --jsonl | Print schema-versioned JSON Lines. |
| 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”. 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. 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. Findings or collection warnings may still be present.1Collection, configuration, output or an action failed. The error is on standard error.2Command syntax or argument parsing failed before 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.
Decide your own health policy
A Health finding does not change the process exit status. Scheduled checks should inspect both findings and collection completeness:
lens-health --json | jq -e '
(.collection_warnings | length) == 0 and
([.findings[] | select(.severity == "critical")] | length) == 0
'This separates command failure from the threshold an operator chooses for attention and critical findings.
Structured snapshot
| Group | Top-level fields |
|---|---|
| Identity and load | host, processes, services |
| 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, --pid and either --dry-run or --yes. Linux service changes require --action, an exact --target and the same plan-or-confirm choice. Lens revalidates the target immediately before execution and reports the observed result.
lens-top --signal term --pid 4242 --dry-run
lens-services --action restart --target nginx.service --dry-run