Choose the view by the question
lensWhat needs attention on this device? Host pulse, busiest processes, warnings and links into every specialist.lens-topWhich process is using CPU or memory, what is it, and is its behaviour changing?lens-servicesDid a system service fail, restart repeatedly or stop when it should be running?lens-containersIs a Docker or Podman container missing, exited or inaccessible to this user?lens-logsWhat happened around a failure, and which messages belong to the affected service or process?lens-diskWhich filesystem is under pressure, are bytes or inodes exhausted, and is deleted data still open?lens-netDoes the device have the expected interface, address, route and listening sockets? Is a cellular modem registered?lens-hardwareIs the device too hot, throttled or under-voltage? Which board, firmware, USB and serial hardware is present?lens-systemIs the clock synchronized, which resolver is configured, and which local identities and certificate files are visible?lens-healthWhich cross-domain warnings deserve attention, what evidence triggered each one, and what should I inspect next?A practical first pass
- Run
lens. Confirm the hostname and clock so you know you are looking at the intended device and current data. - Check CPU, memory, load and the busiest processes. A high value is a lead, not a diagnosis.
- Open a health finding and read its evidence. Follow the linked domain instead of scanning every screen.
- For an application failure, inspect its service state, then look at logs from the same time window.
- For intermittent connectivity, check interface state and the default route, then inspect listeners or cellular registration as appropriate.
- Use the diagnostic shell for a focused native command while keeping the live Lens view visible.
You can also bypass the cockpit and start a specialist directly. Each command collects only the domain it displays, so opening a process or storage view does not wait for an unrelated log scan.
Controls shared by the interactive views
Up / Down or j / kMove the selected row. Lists scroll around the selection when enough rows are available.EnterOpen the selected process, service, message, filesystem, network item or finding.EscGo back one level or close the current overlay./Search the current view in a modal card.rRequest an immediate refresh.!Open a one-shot local diagnostic shell without leaving Lens.?Show controls relevant to the current screen.q or Ctrl+CQuit.The layout follows the terminal size. Wide windows add detail and can place the shell beside the live view; compact windows remove secondary columns before they remove primary values or navigation.
Readable on light and dark terminals
Lens keeps your terminal's configured background and chooses a contrasting foreground palette. Most terminals publish enough information for this to happen automatically. Browser consoles, serial links and some terminal multiplexers do not.
# Override one command
lens --theme light
# Override the complete suite in this shell
export LENS_THEME=lightAccepted values are auto, light and dark. --no-color remains available when colour is unsuitable.
Use the same tools in a shell or script
# A readable snapshot for a support note
lens --plain
# A focused specialist result
lens-logs --since "30 minutes ago" --severity error --plain
# Assert without jq (exit 3 on miss)
lens-health --fail-on critical --fail-on-collection-warnings --quiet
lens-services --name nginx.service --active active --fail-if-empty --quiet
# Structured data when you still want the full document
lens-health --json --fields findings,collection_warningsPass --once to print one readable snapshot instead of opening an interactive screen. --plain explicitly selects the same one-shot human-readable output, while --json / --jsonl emit the shared schema-versioned snapshot. --fields projects JSON; --quiet keeps only the exit status. Redirected output is plain automatically. Common specialist options include --filter, --match and --limit; domain-specific flags fail clearly when used with the wrong command.
Use --limit 0 deliberately: it removes the row cap and can produce a large result on a busy host. The normal default is 1,000 rows.
The command reference defines exit status (including assert exit 3), standard streams, structured fields and scripting behaviour.
Inspect first, then act on a pinned target
Most Lens views inspect the machine. Narrow action families cover process signals in lens-top, systemd service actions in lens-services, and container start/stop/restart in lens-containers. Interactive actions show the exact target and ask for confirmation. CLI actions require --yes; use --dry-run first. Selectors must resolve to exactly one target.
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-runLens actions run as the current user under the operating system's normal policy. Review the process action guide, service action guide and container action guide before acting on a live target.
Platform coverage and incomplete data
Lens uses the commands, kernel interfaces and permissions available to the invoking account. A loading label means collection is still running. Unavailable or a collection warning means the source could not be read. A displayed zero is reserved for a source that completed successfully and returned no matching records.
Partial data remains useful: one timed-out command does not discard fields collected from the rest of the system. Inspect collection_warnings in JSON when a script must distinguish a healthy empty result from an incomplete one. The compatibility matrix identifies native sources by platform; troubleshooting covers common incomplete-data cases.