Level CLI Reference | Level Documentation

Use this article as a map of the Level CLI command tree. For the exact flags and JSON output shape in your installed version, use normal help or the generated skill reference:

lvl --help
lvl skill describe

For example:

lvl device list --help
lvl skill describe device list

Command syntax

The general form is:

lvl [--profile ] [arguments] [flags]

Show the top-level command list:

lvl --help

Show every generated reference entry:

lvl skill describe

Profiles and authentication

Level CLI includes a built-in prod profile for https://api.level.io.

Profile selection follows this order:

The root --profile flag.
The LVL_PROFILE environment variable.
The saved default profile.
The built-in prod profile.

Common commands:

Command	Purpose
`lvl auth login`	Sign in through a browser-based approval flow.
`lvl auth status`	Verify the active session and organization.
`lvl auth logout`	Revoke the active session and remove local credentials.
`lvl profile list`	List configured API-server profiles.
`lvl profile create <name> <url>`	Add a profile. Use `--default` to select it immediately.
`lvl profile use <profile>`	Set the default profile.
`lvl profile delete <profile>`	Remove local profile configuration and credentials.

⚠️ WARNING: Deleting a profile does not revoke its server-side session. Run lvl --profile <profile> auth logout before deleting it.

Output formats

Most commands display a human-readable table or summary by default.

Use JSON output:

lvl device list -o json

Use the built-in jq filter:

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

--jq implies JSON. It cannot be combined with explicit table output.

CSV export commands write raw CSV to standard output:

lvl device export > devices.csv
lvl alert export > alerts.csv
lvl run export > runs.csv

Automation and monitor-policy specification commands use --format yaml|json, with YAML as the default. They do not use the standard -o flag for the specification itself.

Pagination

Most resource list commands support:

Flag	Behavior
`--limit <count>`	Return up to the requested number of records. The default is 100.
`--limit all`	Fetch every result page.
`--page <number>`	Return a 1-based page.

--limit all cannot be combined with --page.

Paginated commands include alert, automation, automation-trigger, device, file, monitor, monitor-policy, run, script, tag, update, update-summary, update-device, update-log, and update-exclusion lists.

API keys, groups, custom fields, profiles, and variables use unpaginated lists.

In JSON list output, count is the total number of matching server records, not the number returned on the current page.

Resource references

Many commands accept an ID or a human-readable reference. An exact ID match takes priority. Name and alias matching is case-insensitive.

Common forms include:

Resource	Accepted references
Device	ID, hostname, name, nickname, or `<group>/<hostname>`
Device group	ID, name, or nested path such as `Ops/Maintenance`
Automation	ID or name
Script	ID or name
Repository file	ID or filename, with or without its extension
Monitor policy	ID or name
Tag	Name
Custom field	Name or generated reference
Update exclusion	ID or KB number, with or without the `KB` prefix

If a reference matches more than one resource, the CLI stops and lists the candidates instead of choosing one.

Alert commands

Command	Purpose
`alert list`	List active, resolved, or all alerts.
`alert get <alert-id>`	Get one alert.
`alert resolve`	Resolve alerts by ID or filters.
`alert unresolve <alert-id>...`	Reopen resolved alerts by ID.
`alert export`	Export matching alerts as CSV.

API key commands

Command	Purpose
`apikey list`	List API keys.
`apikey get <api-key>`	Get one API key. Use `--reveal` to show the full token in table output.
`apikey create`	Create a read-only or read-and-write API key.
`apikey update <api-key>`	Update an API key.
`apikey delete <api-key>...`	Permanently delete API keys.

⚠️ WARNING: API key JSON output contains the full token. Protect terminal output, exported files, and CI logs.

Automation commands

Command	Purpose
`automation list`	List automations.
`automation get <automation>`	Get one automation.
`automation create`	Create an automation from flags or a specification file.
`automation spec <automation>`	Export an automation specification.
`automation apply -f <spec>`	Reconcile an existing automation with a specification.
`automation update <automation>`	Update automation properties.
`automation delete <automation>...`	Archive automations.
`automation restore <automation>...`	Restore archived automations.
`automation run <automation>`	Run an automation on devices or groups.
`automation trigger ...`	List, add, update, delete, or manually run triggers.
`automation action ...`	Add, update, or delete actions.
`automation variable ...`	Manage automation variables.
`automation group ...`	Manage automation groups.

Trigger and action mutation commands accept --json or --json-file. The payload must contain exactly one supported type, and unknown fields are rejected.

Run lvl automation action --help or lvl skill describe automation action for the action types supported by your installed version.

⚠️ WARNING:automation apply can delete triggers and actions that are absent from the specification. The apply is not transactional. Run with --dry-run and review the plan first.

Custom-field commands

Command	Purpose
`customfield list`	List organization custom fields.
`customfield get <field>`	Get one custom field.
`customfield create`	Create a field.
`customfield update <field>`	Update a field.
`customfield delete <field>...`	Delete fields.
`customfield set <field> <value>`	Set an organization-level value.
`customfield clear <field>`	Clear an organization-level value.
`device customfield ...`	List, set, or clear device-level values.
`device group customfield ...`	List, set, or clear device-group values.

Custom-field values inherit from organization to device group to device. Cascading set or clear operations can overwrite or remove descendant values.

Device commands

Command	Purpose
`device list`	List and filter devices.
`device get <device>`	Get device details.
`device restart <device>...`	Request a restart.
`device shutdown <device>...`	Request a shutdown.
`device maintenance enable\|disable <device>...`	Change maintenance mode.
`device update <device>`	Update editable device properties.
`device delete <device>...`	Permanently delete devices.
`device favorite\|unfavorite <device>...`	Change favorite status.
`device flag\|unflag <device>...`	Change flag status.
`device export`	Export devices as CSV.
`device install-key`	Print an agent-install key for provisioning.
`device group ...`	Manage device groups and assignments.
`device customfield ...`	Manage device custom-field values.

Restart and shutdown request the action immediately and do not wait for the device to complete it.

⚠️ WARNING:device install-key prints a provisioning credential to standard output. Avoid exposing it in shell history, shared terminals, or CI logs.

File commands

Command	Purpose
`file list`	List repository files.
`file get <file>`	Get file metadata.
`file upload <path>...`	Upload local files.
`file download <file> [<dest>]`	Download a file. Use `-` as the destination for standard output.
`file rename <file> <filename>`	Rename a repository file.
`file replace <file> <path>`	Replace file content while preserving the repository file ID.
`file delete <file>...`	Permanently delete files.
`file storage`	Show storage usage.
`file group ...`	Manage repository-file groups.

file download --overwrite can replace an existing local file. Replacing a repository file changes the content used by automations that reference that file ID.

Monitor commands

Command	Purpose
`monitor list`	List monitors across policies.
`monitor get <monitor>`	Get one monitor.
`monitor add <policy>`	Add a monitor to a policy from a JSON payload.
`monitor update <monitor>`	Update a monitor with a JSON payload.
`monitor delete <monitor>...`	Delete monitors.
`monitor enable\|disable <monitor>... --device <device>`	Override monitors for one device.
`monitor policy list`	List monitor policies.
`monitor policy get <policy>`	Get one policy.
`monitor policy create`	Create a policy from flags or a specification.
`monitor policy spec <policy>`	Export a policy specification.
`monitor policy apply -f <spec>`	Reconcile a policy with a specification.
`monitor policy target\|untarget <policy>`	Manage target tags.

Monitor payload commands accept --json or --json-file. Run lvl monitor add --help for the supported monitor types.

Monitor-policy apply can delete monitors absent from the file and is not transactional. Use --dry-run first.

Run commands

Command	Purpose
`run list`	List automation and script runs.
`run get <run-id>`	Get a run and its steps. Use `--wait` to poll for completion.
`run cancel`	Cancel runs by ID or filters.
`run rerun`	Start new runs from selected runs.
`run retry <run-id>...`	Retry failed runs from the failed step.
`run approve <run-id>...`	Approve runs paused at an approval step.
`run deny <run-id>...`	Deny and cancel runs paused at an approval step.
`run export`	Export runs as CSV.

Waiting defaults to 15 minutes and returns up to 1,000 output lines per step. Use --wait-timeout and --output-lines to change those limits.

An ERROR or CANCELED result exits non-zero. A WARNING result is treated as successful.

Script commands

Command	Purpose
`script list`	List saved scripts.
`script get <script>`	Get a saved script. Use `--raw` to print only its body.
`script create`	Create a script from `--file` or `--command`.
`script update <script>`	Update a saved script.
`script delete <script>...`	Delete scripts.
`script run [<script>]`	Run a saved script, file, or inline command.
`script variable ...`	Manage script variables.
`script group ...`	Manage script groups.

A run target can come from repeated --device flags, --group, or both. Duplicate targets are run once.

A saved script uses its stored shell, timeout, and run-as setting. Ad-hoc script runs infer the shell from an explicit flag, file extension, shebang, or target operating system.

⚠️ WARNING: Script creation and ad-hoc script runs default to the SYSTEM run-as setting. Review the script and target list before execution.

Skill commands

Command	Purpose
`skill show`	Print the generated `SKILL.md`.
`skill install`	Install the skill for the current user.
`skill install --project`	Install the skill in the current project.
`skill describe [<command>...]`	Print flags and JSON output definitions.

Reinstall the skill after upgrading lvl so coding agents receive the current command tree.

Tag commands

Command	Purpose
`tag list`	List tags.
`tag get <tag>`	Get a tag.
`tag create`	Create a tag.
`tag update <tag>`	Update a tag.
`tag delete <tag>...`	Delete unused tags.
`tag assign <tag> --device <device>...`	Assign a tag to devices.
`tag unassign <tag> --device <device>...`	Remove a tag from devices.

Update commands

Command	Purpose
`update list`	List available, installed, or all updates.
`update get <update-id>`	Get one update.
`update check <device>...`	Request an update scan.
`update install`	Install selected updates.
`update retry`	Retry selected failed installations.
`update install-all`	Install available updates on selected devices.
`update log list\|get`	Review update-install records and logs.
`update summary list`	List update summaries.
`update device list`	List devices in update context.
`update exclusion list\|create\|update\|delete`	Manage global KB exclusions.

Update installation, retry, and install-all allow required reboots by default. Use --no-reboot when the selected command should not reboot a device.

⚠️ WARNING: Review update and device selections before installation. Filter-based and all-device operations require explicit confirmation.

Group commands

Device, script, automation, and file groups share these subcommands:

list
create
rename
move
delete
assign
unassign

Group lists fetch the complete hierarchy. Deleting a group requires it to be empty and have no child groups.

Confirmation and asynchronous work

Permanent delete commands support --yes. In an interactive terminal, the CLI may prompt. In non-interactive execution, commands that require confirmation fail unless --yes is supplied.

Some commands return after Level accepts the request, before work finishes on a device. These include power actions, update checks and installations, scripts, automations, and trigger runs. Use run history, run get --wait, update logs, or the Level web app to confirm the final result.