LAVACLI(1)

📦
version 2.9.0 · 3 versions
, in ubuntu stonking

💖 NAME 💖

okay so bestie, welcome to lavacli(1) — the lavacli manual, and yes we're doing the whole thing together 🫶

lavacli is a command line tool to interact with one or many LAVA instances using XML-RPC. that's the entire elevator pitch and honestly? iconic.

✨ FEATURES ✨

lavacli lets you poke at literally every LAVA object out there:

  • aliases
  • device-types
  • devices
  • events
  • jobs
  • results
  • tags
  • workers

not one of them left behind 💅

🌈 TABLE OF CONTENTS 🌈

🎀 Installation

Debian

there's a Debian package (https://packages.debian.org/unstable/lavacli) available for Debian unstable, and you can grab it with:

apt install lavacli

PyPi

lavacli is also chillin' on Pypi (https://pypi.org/project/lavacli/) and installs like:

pip install lavacli

Development versions

and if you wanna live on the edge (main character energy), you can run it straight from the sources:

git clone https://gitlab.com/lava/lavacli.git
cd lavacli
virtualenv -p python3 venv
source venv/bin/activate
pip install -r requirements.txt
python3 -m lavacli

💅 Configuration

lavacli works with or without a configuration file. no config file? totally valid. but having one is lowkey a lifesaver when you're juggling more than one lava instance.

Without a configuration file

when there's no config file in sight, you pass the uri as a command line argument:

lavacli --uri https://validation.linaro.org/RPC2 devices list

the authentication can also ride along inside the uri:

lavacli --uri https://admin:my_secret_token@validation.linaro.org/RPC2 devices list
⚠️ bestie, keep in mind: any user on the same machine will then see the username and token in the process list. not the moment 🙈

With a configuration file

the lavacli configuration file lives at ~/.config/lavacli.yaml. it's a YAML dictionary where each key is an identity.

default:
  uri: https://validation.linaro.org/RPC2
validation:
  uri: https://validation.linaro.org/RPC2
admin@validation:
  uri: https://validation.linaro.org/RPC2
  username: admin
  token: my_secret_token
staging:
  uri: https://staging.validation.linaro.org/RPC2
  events:
    uri: tcp://staging.validation.linaro.org:5500

when you're running lavacli, you pick the identity with -i or --identity:

lavacli -i admin@validation devices list
lavacli -i staging events listen

by default, the default identity gets used. so these two commands are literally identical:

lavacli devices list
lavacli -i validation devices list

Available options

for each identity, you have to set:

  • uri: the uri of the RPC endpoint.

you can also set:

  • username: the api username
  • token: the api token
  • version: the api version to use when talking to this instance
  • timeout: the http timeout (defaults to 20 seconds)
  • proxy: the uri to the proxy
  • verify_ssl_cert: set it to false to ignore SSL certificates errors (defaults to true)
  • events: zmq event configuration

the events key is a dictionary where you can specify:

  • uri: the uri of the events stream. if it's not specified, lavacli will ask the server.
  • socks_proxy: uri to the socks proxy, if needed

🦋 Usage

here's the full list of available commands and sub-commands 💖

Aliases

LAVA aliases can be managed by:

lavacli aliases add <name>
lavacli aliases delete <name>
lavacli aliases list
lavacli aliases show <name>

Device types

LAVA device types can be managed by:

lavacli device-types add [...]
lavacli device-types aliases add <name> <alias>
lavacli device-types aliases delete <name> <alias>
lavacli device-types aliases list
lavacli device-types health-check get <name>
lavacli device-types health-check set <name> <health-check.yaml>
lavacli device-types list
lavacli device-types show <name>
lavacli device-types template get <name>
lavacli device-types template set <name> <template.jinja2>
lavacli device-types update [...]

Devices

LAVA devices can be managed by:

lavacli devices add [...]
lavacli devices control <hostname> (on|off|reset|connect) [--dry-run]
lavacli devices dict get <hostname>
lavacli devices dict set <hostname>
lavacli devices list
lavacli devices maintenance <hostname> [--force] [--no-wait] [--reason <text>]
lavacli devices show <hostname>
lavacli devices tags add <hostname> <name>
lavacli devices tags delete <hostname> <name>
lavacli devices tags list
lavacli devices update [...]

the control command lets you control the device power and serial connection directly from the workstation, using the commands defined in the device dictionary:

  • on: turn the device on (commands.power_on)
  • off: turn the device off (commands.power_off)
  • reset: hard reset the device (commands.hard_reset)
  • connect: connect to the device primary serial port (commands.connections.<primary>.connect)

use --dry-run (or -n) to print the command that would be run without executing it. peek, don't touch 🫶

Events

LAVA events can be used by:

lavacli events listen
lavacli events wait device [...]
lavacli events wait job [...]
lavacli events wait worker [...]

Groups

LAVA groups can be managed by:

lavacli add [...]
lavacli delete <group>
lavacli list
lavacli perms add [...]
lavacli perms list
lavacli perms delete [...]
lavacli show <group>

Identities

lavacli identities can be managed by:

lavacli identities add [...]
lavacli identities delete <id>
lavacli identities list
lavacli identities show <id>

Jobs

LAVA jobs can be managed by:

lavacli jobs cancel <job_id>
lavacli jobs config <job_i>
lavacli jobs definition <job_id>
lavacli jobs list
lavacli jobs logs <job_id>
lavacli jobs queue <device-type>
lavacli jobs resubmit <job_id>
lavacli jobs run <definition.yaml>
lavacli jobs show <job_id>
lavacli jobs submit <definition.yaml>
lavacli jobs validate <definition.yaml>
lavacli jobs wait <job_id>
lavacli jobs find-errors

Lab

LAVA lab can be managed by:

lavacli lab apply <config>
lavacli lab import <config>

Results

LAVA results can be managed by:

lavacli results <job_id>
lavacli results <job_id> <suite>
lavacli results <job_id> <suite> <case>

System

a LAVA instance can be managed by:

lavacli system active
lavacli system api
lavacli system maintenance
lavacli system methods list
lavacli system methods help <method>
lavacli system methods signature <method>
lavacli system version
lavacli system whoami

in order to put a full instance into maintenance, an admin could call system maintenance. this function will:

  • set all workers health to MAINTENANCE
  • wait for all jobs to finish

if the instance should be put into maintenance immediately, adding --force will:

  • set all workers health to MAINTENANCE
  • cancel all running jobs
  • wait for all jobs to finish

it's also possible to exclude some workers with --exclude.

when the maintenance is finished, calling system active will move every worker's health out of MAINTENANCE and into ACTIVE. we're so back 🔥

Tags

LAVA tag can be managed by:

lavacli tags add [...]
lavacli tags delete <tag>
lavacli tags list
lavacli tags show <tag>

Tokens

manage user remote artifact tokens:

lavacli add [...]
lavacli delete <token>
lavacli list
lavacli show <token>

Users

manage LAVA users with:

lavacli add [...]
lavacli delete <user>
lavacli groups add <user> [...]
lavacli groups list
lavacli groups delete [...]
lavacli perms add <user> [...]
lavacli perms list
lavacli perms delete [...]
lavacli list
lavacli show <user>
lavacli update <user> [...]

Utils

some utilities are available with:

lavacli utils logs print <output.yaml>
lavacli utils templates render <output.yaml>

Printing logs

when you're working with raw logs, lavacli might help by coloring the logs by levels. ✨

it's also possible to filter the logs by level. to only print the serial output and the commands sent by LAVA to the board, use:

lavacli utils logs print --filter target,input

available log levels are: exception, error, warning, info, debug, target, input, feedback, results.

Workers

LAVA workers can be managed by:

lavacli workers add [...]
lavacli workers config get <hostname>
lavacli workers config set <hostname> <config.yaml>
lavacli workers env get <hostname>
lavacli workers env set <hostname> <env.yaml>
lavacli workers list
lavacli workers maintenance <hostname>
lavacli workers update [...]
lavacli workers show <hostname>

👑 Author

Rémi Duraffort

2018, Rémi Duraffort

and that's the whole page bestie, you ate that 🍓 this was lavacli version 2.9.0, dated June 25, 2026 — fr fr, go manage some devices now 💅✨

📦 where this page comes from