Level CLI Examples and Recipes | Level Documentation

These recipes show common ways to use Level CLI from a terminal. Replace sample names such as web-01, Laptops, and Disk cleanup with resources from your Level account.

ℹ️ NOTE: Run lvl auth status before a recipe to confirm the active profile and Level organization. Prefer resource IDs when a name matches more than one record.

Sign in and verify the session

Start the browser-based sign-in:

lvl auth login

Confirm the active session:

lvl auth status

The login command prints a one-time code and verification URL. After you approve access in your browser, the CLI saves the session for the active profile.

List and filter devices

Search device names and return every matching page:

lvl device list --search web --limit all

Return the same results as JSON:

lvl device list --search web --limit all -o json

Use the built-in jq filter to select specific fields:

lvl device list --search web --limit all --jq '.list[] | {id, name, online}'

--jq implies JSON output. String results print as plain text. Objects and other values print as compact JSON, one result per line.

ℹ️ NOTE: Paginated list commands return up to 100 records by default. Use --limit all only when you need the complete result set.

Export devices to CSV

Export devices in a group:

lvl device export --group Laptops > devices.csv

The export writes raw CSV to standard output. Redirect it to a file instead of adding -o json.

You can use the same pattern for alerts and automation runs:

lvl alert export --status resolved > resolved-alerts.csv
lvl run export --status error > failed-runs.csv

Run a read-only diagnostic on a Unix-like device

The following example checks filesystem usage on a Linux or macOS device:

lvl script run \
  --device web-01 \
  --command 'df -h' \
  --shell bash \
  --run-as current_user \
  --wait \
  -o json

This command creates an ad-hoc script run. --wait polls for completion and includes the step output in the result.

If you omit --wait, the CLI returns the discovered run IDs. Check a run later with:

lvl run get RUN_ID --wait -o json

⚠️ WARNING: Confirm the target operating system before running an ad-hoc command. Script creation and ad-hoc runs default to the SYSTEM run-as setting unless you specify another value.

Create and reuse a saved diagnostic script

If you already have a reviewed Bash script in os-info.sh, save it in Level:

lvl script create \
  --name 'OS info' \
  --file ./os-info.sh \
  --shell bash \
  --run-as current_user \
  -o json

Run the saved script by name:

lvl script run 'OS info' --device web-01 --wait -o json

A saved script keeps its configured shell, timeout, and run-as setting. When you run a saved script by name or ID, do not add shell or run-as overrides.

Use a script ID when more than one script has the same name.

Preview an automation specification

Export an existing automation as YAML:

lvl automation spec 'Disk cleanup' > disk-cleanup.yaml

Preview how that specification would change the live automation:

lvl automation apply -f disk-cleanup.yaml --dry-run -o json

A dry run prints the planned changes without applying them.

After reviewing the file and the dry-run result, apply it with:

lvl automation apply -f disk-cleanup.yaml

⚠️ WARNING: Applying a specification reconciles the live automation with the file. Existing triggers or actions missing from the file can be deleted. Changes are applied in sequence, so an error can leave earlier changes in place. Keep a current export and run --dry-run before every apply.

Inspect monitor policies

List monitor policies:

lvl monitor policy list --limit all

Get one policy by ID or name:

lvl monitor policy get 'Server health' -o json

Export its specification:

lvl monitor policy spec 'Server health' > server-health.yaml

Preview a specification before applying it:

lvl monitor policy apply -f server-health.yaml --dry-run -o json

Like automation apply, monitor policy apply reconciles the live resource and is not transactional.

Use group-qualified references

Device references can use an ID, hostname, name, nickname, or a group-qualified hostname:

lvl device get 'Servers/web-01'

Group-qualified references help when different device groups contain the same hostname. If a reference is still ambiguous, the CLI stops and lists the matches instead of choosing one.

Inspect exact flags and output shapes

Show normal command help:

lvl script run --help

Show the generated reference, including the JSON output shape:

lvl skill describe script run

Show every command under a group:

lvl skill describe update

The installed CLI is the source of truth for its current flags and output definitions.

Safety checklist

Before running a command that changes Level or a managed device:

Confirm the active organization with lvl auth status.
Confirm every target by ID, name, or group-qualified reference.
Review scripts and JSON or YAML specifications in full.
Check whether the command defaults to SYSTEM, installs updates, reboots a device, or replaces a file.
Use --dry-run where available.
Use --yes only after reviewing the complete set of selected resources.
Check run history or update logs for asynchronous results.

Permanent delete commands require confirmation in an interactive terminal and require --yes in non-interactive execution. Some commands, including device restart and shutdown, request the action immediately without a confirmation prompt.