Provided by: lava-tool_0.24-1_all 
NAME
lava-tool - LAVA Tool Command Line Support
SUMMARY
lava-tool is a command-line tool to interact with LAVA.
USAGE
lava-tool [-h] <subcommand> [args]
OPTIONAL ARGUMENTS
-h, --help
show this help message and exit
SUBCOMMANDS
Type lava-tool <subcommand> -h for help on a specific subcommand.
DEPRECATED V1 COMMANDS
The following commands are deprecated. Support will remain in lava-tool for a limited time
only and some calls have already been disabled for some LAVA instances. Once the rest of
the upstream V1 support is removed at the end of 2017, the deprecated functions within
lava-tool will also be removed.
data-views, deserialize, get, put, bundles, server-version, query-data-view, streams,
make-stream, pull.
AVAILABLE SUBCOMMANDS
data-views
Show data views defined on the server DEPRECATED
Usage: lava-tool data-views [-h] –dashboard-url URL [–verbose-xml-rpc]
[–experimental-notice]
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
Experimental commands:
--experimental-notice
Explain the nature of experimental commands
job-output
Get job output from the scheduler
Usage: lava-tool job-output [-h] [–overwrite] [–output OUTPUT] SERVER JOB_ID
Positional arguments:
SERVER Host to download job output from
JOB_ID Job ID to download output file
Optional arguments:
-h, --help
show this help message and exit
--overwrite
Overwrite files on the local disk
--output OUTPUT, -o OUTPUT
Alternate name of the output file
devices-list
Get list of devices from the scheduler.
Usage: lava-tool devices-list [-h] SERVER
Positional arguments:
SERVER Host to query for the list of devices
Optional arguments:
-h, --help
show this help message and exit
help Show a summary of all available commands
deserialize
Deserialize a bundle on the server DEPRECATED
Usage: lava-tool deserialize [-h] –dashboard-url URL [–verbose-xml-rpc] SHA1
Positional arguments:
SHA1 SHA1 of the bundle to deserialize
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
get Download a bundle from the server DEPRECATED
Usage: lava-tool get [-h] –dashboard-url URL [–verbose-xml-rpc] [–overwrite]
[–output OUTPUT] SHA1
Positional arguments:
SHA1 SHA1 of the bundle to download
Optional arguments:
-h, --help
show this help message and exit
--overwrite
Overwrite files on the local disk
--output OUTPUT, -o OUTPUT
Alternate name of the output file
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
auth-add
Add an authentication token
Usage: lava-tool auth-add [-h] [–token-file TOKEN_FILE] [–no-check] HOST
Positional arguments:
HOST Endpoint to add token for, in the form scheme://username@host. The
username will default to the currently logged in user.
Optional arguments:
-h, --help
show this help message and exit
--token-file TOKEN_FILE
Read the secret from here rather than prompting for it.
--no-check
By default, a call to the remote server is made to check that the
added token works before remembering it. Passing this option
prevents this check.
--user-shortcut USER_SHORTCUT
Shortcut name for the user.
--endpoint-shortcut ENDPOINT_SHORTCUT
Shortcut name for the endpoint.
--default-user
Set this user as default user for the endpoint
auth-config
Modify authentication configuration
Usage: lava-tool auth-config [-h] [–user-shortcut USER_SHORTCUT]
[–endpoint-shortcut ENDPOINT_SHORTCUT] [–default-user] HOST
Positional arguments:
HOST Endpoint to add token for, in the form scheme://username@host.
Optional arguments:
-h, --help
show this help message and exit
--user-shortcut USER_SHORTCUT
Shortcut name for the user.
--endpoint-shortcut ENDPOINT_SHORTCUT
Shortcut name for the endpoint.
--default-user
Set this user as default user for the endpoint.
auth-list
List authentication configuration
Usage: lava-tool auth-list [-h] [HOST]
Positional arguments:
HOST Endpoint to list tokens for, in the form scheme://host.
Optional arguments:
-h, --help
show this help message and exit
put Upload a bundle on the server DEPRECATED
Usage: lava-tool put [-h] –dashboard-url URL [–verbose-xml-rpc] LOCAL [REMOTE]
Positional arguments:
LOCAL pathname on the local file system
REMOTE pathname on the server
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
bundles
Show bundles in the specified stream DEPRECATED
Usage: lava-tool bundles [-h] –dashboard-url URL [–verbose-xml-rpc] [PATHNAME]
Positional arguments:
PATHNAME
pathname on the server (defaults to /anonymous/)
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
server-version
Display dashboard server version DEPRECATED
Usage: lava-tool server-version [-h] –dashboard-url URL [–verbose-xml-rpc]
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
cancel-job
Cancel job
Usage: lava-tool cancel-job [-h] SERVER JOB_ID
Positional arguments:
SERVER Host to cancel job on
JOB_ID Job ID to cancel
Optional arguments:
-h, --help
show this help message and exit
resubmit-job
Resubmit job
Usage: lava-tool resubmit-job [-h] SERVER JOB_ID
Positional arguments:
SERVER Host to resubmit job on
JOB_ID Job ID to resubmit
Optional arguments:
-h, --help
show this help message and exit
version
Show the lava-tool client version
Usage: lava-tool version [-h]
Optional arguments:
-h, --help
show this help message and exit
query-data-view
Invoke a specified data view DEPRECATED
Usage: lava-tool restore [-h] –dashboard-url URL [–verbose-xml-rpc]
[–experimental-notice] QUERY
Positional arguments:
QUERY Data view name and any optional and required arguments
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
Experimental commands:
--experimental-notice
Explain the nature of experimental commands
submit-job
Submit a job to lava-scheduler
Usage: lava-tool submit-job [-h] [–block] SERVER JOB_FILE
Positional arguments:
SERVER Host to resubmit job on
JOB_FILE
JOB file with test definition to submit
Optional arguments:
-h, --help
show this help message and exit
--publish-artifacts
Publish all file:/// references within job definition via
publishing API and rewrite URL’s. Job definition file must
contain the ‘secrets’ section which includes API_USER and API_KEY
which are used to authenticate with remote artifacts server.
--artifacts-url ARTIFACTS_URL
Remote server which accepts file uploads via curl. Defaults to
https://archive.validation.linaro.org If non-default url is used,
user is responsible for setting up the artifacts upload server as
well as relevant account and secret.
--artifacts-path ARTIFACTS_PATH
Location on the remote server to which artifacts will be uploaded.
Defaults to team/lava.
--block
Blocks until the job gets executed. Deprecated. This option adds
unnecessary load on the server. Please use wait-job-events
command instead.
Experimental commands:
--experimental-notice
Explain the nature of experimental commands
wait-job-events
Wait for a job events from lava-publisher. Can also submit a job and wait for that
particular one.
Usage: lava-tool wait-job-events [-h] (–job-definition JOB_DEFINITION | –job-id
JOB_ID) [–timeout TIMEOUT] [–quiet] SERVER
Positional arguments:
SERVER Host to submit job on and/or listen to job events from.
Optional arguments:
-h, --help
show this help message and exit
--job-definition JOB_DEFINITION
Definition file path of the job that will be submitted.
--job-id JOB_ID
ID of the job to wait for. If this argument is provided, this command
will not submit new job.
--timeout TIMEOUT
Time to wait until the job is finished. Default will wait until
manually canceled.
--publish-artifacts
Publish all file:/// references within job definition via publishing
API and rewrite URL’s. Job definition file must contain the
‘secrets’ section which includes API_USER and API_KEY which are used
to authenticate with remote artifacts server.
--artifacts-url ARTIFACTS_URL
Remote server which accepts file uploads via curl. Defaults to
https://archive.validation.linaro.org If non-default url is used,
user is responsible for setting up the artifacts upload server as
well as relevant account and secret.
--artifacts-path ARTIFACTS_PATH
Location on the remote server to which artifacts will be uploaded.
Defaults to team/lava.
--quiet, -q
Do not print out interim messages (when job becomes Submitted or
Running) but only when the job is finished.
validate-pipeline-devices
Validate pipeline devices on the specified server. Print output in the form of
“device_hostname: {‘Valid’: null} | {‘Invalid’: message}”
Usage: lava-tool validate-pipeline-devices [-h] [–name NAME] SERVER
Positional arguments:
SERVER
Optional arguments:
-h, --help
show this help message and exit
--name NAME
Hostname of the device or device_type name.
streams
Show streams you have access to DEPRECATED
Usage: lava-tool streams [-h] –dashboard-url URL [–verbose-xml-rpc]
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
make-stream
Create a bundle stream on the server DEPRECATED
Usage: lava-tool make-stream [-h] –dashboard-url URL [–verbose-xml-rpc] [–name
NAME] pathname
Positional arguments:
pathname
Pathname of the bundle stream to create
Optional arguments:
-h, --help
show this help message and exit
--name NAME
Name of the bundle stream (description)
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
compare-device-conf
Compare device configurations and output a diff.
Usage: lava-tool compare-device-conf [-h] [–wdiff] [–use-stored USE_STORED]
[–dispatcher-config-dir DISPATCHER_CONFIG_DIR] [CONFIGS [CONFIGS …]]
Positional arguments:
CONFIGS
List of device config paths, at least one, max two.
Optional arguments:
-h, --help
show this help message and exit
--wdiff, -w
Use wdiff for parsing output
--use-stored USE_STORED, -u USE_STORED
Use stored device config with specified device
--dispatcher-config-dir DISPATCHER_CONFIG_DIR
Where to find the device_type templates.
pull Copy bundles and bundle streams from one dashboard to another DEPRECATED
Usage: lava-tool pull [-h] –dashboard-url URL [–verbose-xml-rpc]
[–experimental-notice] FROM [STREAM [STREAM …]]
Positional arguments:
FROM URL of the remote validation dashboard
Optional arguments:
-h, --help
show this help message and exit
Dashboard specific arguments:
--dashboard-url URL
URL of your validation dashboard
STREAM Streams to pull from (all by default)
Debugging arguments:
--verbose-xml-rpc
Show XML-RPC data
Experimental commands:
--experimental-notice
Explain the nature of experimental commands
This command checks for two environment variables: The value of DASHBOARD_URL is
used as a replacement for –dashboard-url. The value of REMOTE_DASHBOARD_URL as a
replacement for FROM. Their presence automatically makes the corresponding
argument optional.
get-pipeline-device-config
Get pipeline device configuration to a local file or stdout.
Usage: lava-tool get-pipeline-device-config [-h] [–overwrite] [–output OUTPUT]
[–output-to-stdout] SERVER DEVICE_HOSTNAME
Positional arguments:
SERVER Host to download pipeline device configuration from
DEVICE_HOSTNAME
HOSTNAME of the pipeline device for which configuration is required
Optional arguments:
-h, --help
show this help message and exit
--overwrite
Overwrite files on the local disk
--output OUTPUT, -o OUTPUT
Alternate name of the output file
--stdout
Write output to stdout
device-dictionary
Update or export device dictionary data as jinja2 data. [Superusers only.] Either
[–update | -u] or [–export | -e] must be used. Wraps the import-device-dictionary
and export-device-dictionary XMLRPC API calls on the specified server.
Usage: lava-tool device-dictionary [-h] [–update UPDATE] [–export]
SERVER DEVICE_HOSTNAME
Positional arguments:
SERVER Host to query or update the device dictionary on
DEVICE_HOSTNAME DEVICE_HOSTNAME to query or update
Optional arguments:
-h, --help
show this help message and exit
--update UPDATE, -u UPDATE
Load a jinja2 file to update the device dictionary
--export, -e
Export the device dictionary for this device as jinja2
job-results
Download job results in either YAML or CSV format.
Usage: lava-tool job-results [-h] [–csv] SERVER JOB_ID
Positional arguments:
SERVER Host from where to download the results. JOB_ID ID of the
job to get results for.
Optional arguments:
-h, --help
show this help message and exit
--csv If this is specified, results will be printed out in CSV format,
otherwise in YAML.
test-suite-results
Download test suite results in either YAML or CSV format.
Usage: lava-tool test-suite-results [-h] [–csv] SERVER JOB_ID SUITE_NAME
Positional arguments:
SERVER Host from where to download the results. JOB_ID ID of the
job to get results from. SUITE_NAME Name of the suite to get results for.
Optional arguments:
-h, --help
show this help message and exit
--csv If this is specified, results will be printed out in CSV format,
otherwise in YAML.
test-case-results
Download test case results in either YAML or CSV format.
Usage: lava-tool test-case-results [-h] [–csv] SERVER JOB_ID SUITE_NAME TEST_CASE
Positional arguments:
SERVER Host from where to download the results. JOB_ID ID of the
job to get results from. SUITE_NAME Name of the suite to get results from.
TEST_CASE Name of the test case to get results for.
Optional arguments:
-h, --help
show this help message and exit
--csv If this is specified, results will be printed out in CSV format,
otherwise in YAML.
LAVA TEST DEFINITIONS
A LAVA Test Definition comprises of two parts:
• the data to setup the test, the job definition.
• the instructions to run inside the test, expressed as a YAML file.
For help on writing job definitions and test definitions, please see the help available on
the LAVA instance you want to use to run the test.
As a reminder, JSON job submissions relate to the deprecated LAVA V1 support which is
superseded by LAVA V2 using YAML for the job submission.
The latest information and help on LAVA V2 is available via the staging instance:
https://staging.validation.linaro.org/static/docs/v2/
EXAMPLES
lava-tool simplifies the token handling required to interact with one or more LAVA
instances using XML-RPC.
See the lava-tool help on the instance you want to use when running tests for more
information on using lava-tool. For example, if you have LAVA installed on
http://localhost, the lava-tool help will be available at:
http://localhost/static/docs/v2/lava-tool.html#new-features
Make sure you have already logged into the instance and created an Authentication Token
using the web UI.
Alternatively, admins of up to date LAVA instances can generate a token for a user with
the lava-server manage tokens add command:
$ lava-tool auth-add
http://localuser@localhost/RPC2 Paste token for
http://localuser@localhost/RPC2/: Token added successfully for user localuser.
Now set the user for this authentication as the default user for this endpoint
(localhost):
$ lava-tool auth-config --default-user http://localuser@localhost/RPC2
Auth configuration successfully updated on endpoint http://localhost/RPC2.
Now set a shortcut for http://localhost/RPC2 as local:
$ lava-tool auth-config --endpoint-shortcut local http://localuser@localhost/RPC2
Auth configuration successfully updated on endpoint http://localhost/RPC2.
$ lava-tool auth-list
Endpoint URL: http://localhost/RPC2/
endpoint-shortcut: local
default-user: localuser
Tokens found for users: localuser
NOTE:
For any instance other than localhost, always use https so that your token is protected
during transmission.
BUGS AND ISSUES
NOTE:
lava-tool is intended for user command line interaction. For all scripting
requirements use XMLRPC support directly. Help on using XMLRPC with python is in the
API | Available Methods section of the LAVA instance. e.g.
https://validation.linaro.org/api/help/ Other languages also have XMLRPC support.
AUTHOR
Linaro Validation Team
COPYRIGHT
2010-2018, Linaro Limited