.\" Man page generated from reStructuredText.
.
.TH "LAVA-TOOL" "1" "May 16, 2018" "0.25
" "LAVA Tool"
.SH NAME
lava-tool \- LAVA Tool Command Line Support
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH SUMMARY
.sp
\fBlava\-tool\fP is a command\-line tool to interact with LAVA.
.SH USAGE
.sp
lava\-tool [\-h] <subcommand> [args]
.SH OPTIONAL ARGUMENTS
.INDENT 0.0
.INDENT 3.5
.INDENT 0.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.UNINDENT
.UNINDENT
.SH SUBCOMMANDS
.sp
Type \fBlava\-tool <subcommand> \-h\fP for help on a specific subcommand.
.SH DEPRECATED V1 COMMANDS
.sp
The following commands are \fBdeprecated\fP\&. Support will remain in \fBlava\-tool\fP
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 \fBlava\-tool\fP will also be removed.
.sp
data\-views, deserialize, get, put, bundles, server\-version, query\-data\-view,
streams, make\-stream, pull.
.SH AVAILABLE SUBCOMMANDS
.INDENT 0.0
.TP
.B job\-output
Get job output from the scheduler
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool job\-output [\-h] [\-\-overwrite] [\-\-output OUTPUT] SERVER JOB_ID
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to download job output from
.TP
.B JOB_ID
Job ID to download output file
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-overwrite
Overwrite files on the local disk
.TP
.BI \-\-output \ OUTPUT\fP,\fB \ \-o \ OUTPUT
Alternate name of the output file
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B devices\-list
.INDENT 7.0
.TP
.B Get list of devices from the scheduler.
.INDENT 7.0
.TP
.B Usage:
lava\-tool devices\-list [\-h] SERVER
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to query for the list of devices
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B help
Show a summary of all available commands
.TP
.B auth\-add
Add an authentication token
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool auth\-add [\-h] [\-\-token\-file TOKEN_FILE] [\-\-no\-check] HOST
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B HOST
Endpoint to add token for, in the form scheme://username@host. The
username will default to the currently logged in user.
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-token\-file \ TOKEN_FILE
Read the secret from here rather than prompting
for it.
.TP
.B \-\-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.
.TP
.BI \-\-user\-shortcut \ USER_SHORTCUT
Shortcut name for the user.
.TP
.BI \-\-endpoint\-shortcut \ ENDPOINT_SHORTCUT
Shortcut name for the endpoint.
.TP
.B \-\-default\-user
Set this user as default user for the endpoint
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B auth\-config
Modify authentication configuration
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage: lava\-tool auth\-config [\-h] [\-\-user\-shortcut USER_SHORTCUT]
[\-\-endpoint\-shortcut ENDPOINT_SHORTCUT]
[\-\-default\-user]
HOST
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B HOST
Endpoint to add token for, in the form scheme://username@host.
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-user\-shortcut \ USER_SHORTCUT
Shortcut name for the user.
.TP
.BI \-\-endpoint\-shortcut \ ENDPOINT_SHORTCUT
Shortcut name for the endpoint.
.TP
.B \-\-default\-user
Set this user as default user for the endpoint.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B auth\-list
List authentication configuration
.INDENT 7.0
.INDENT 3.5
Usage: lava\-tool auth\-list [\-h] [HOST]
.INDENT 0.0
.TP
.B Positional arguments:
HOST        Endpoint to list tokens for, in the form scheme://host.
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B cancel\-job
Cancel job
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool cancel\-job [\-h] SERVER JOB_ID
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to cancel job on
.TP
.B JOB_ID
Job ID to cancel
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B resubmit\-job
Resubmit job
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool resubmit\-job [\-h] SERVER JOB_ID
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to resubmit job on
.TP
.B JOB_ID
Job ID to resubmit
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B version
Show the \fBlava\-tool\fP client version
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool version [\-h]
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B submit\-job
Submit a job to lava\-scheduler
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool submit\-job [\-h] [\-\-block] SERVER JOB_FILE
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to resubmit job on
.TP
.B JOB_FILE
JOB file with test definition to submit
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-publish\-artifacts
Publish all \fI\%file:///\fP references within job
definition via publishing API and rewrite URL\(aqs.
Job definition file must contain the \(aqsecrets\(aq
section which includes API_USER and API_KEY which
are used to authenticate with remote artifacts
server.
.TP
.BI \-\-artifacts\-url \ ARTIFACTS_URL
Remote server which accepts file uploads via curl.
Defaults to \fI\%https://archive.validation.linaro.org\fP
If non\-default url is used, user is responsible
for setting up the artifacts upload server as
well as relevant account and secret.
.TP
.BI \-\-artifacts\-path \ ARTIFACTS_PATH
Location on the remote server to which artifacts
will be uploaded.
Defaults to team/lava.
.TP
.B \-\-block
Blocks until the job gets executed. Deprecated.
This option adds unnecessary load on the server.
Please use wait\-job\-events command instead.
.UNINDENT
.TP
.B Experimental commands:
.INDENT 7.0
.TP
.B \-\-experimental\-notice
Explain the nature of experimental commands
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B wait\-job\-events
Wait for a job events from lava\-publisher. Can also submit a job and wait
for that particular one.
.INDENT 7.0
.TP
.B Usage:
lava\-tool wait\-job\-events [\-h]
(\-\-job\-definition JOB_DEFINITION | \-\-job\-id JOB_ID)
[\-\-timeout TIMEOUT] [\-\-quiet]
SERVER
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to submit job on and/or listen to job events from.
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-job\-definition \ JOB_DEFINITION
Definition file path of the job that will be
submitted.
.TP
.BI \-\-job\-id \ JOB_ID
ID of the job to wait for. If this argument is
provided, this command will not submit new job.
.TP
.BI \-\-timeout \ TIMEOUT
Time to wait until the job is finished. Default will
wait until manually canceled.
.TP
.B \-\-publish\-artifacts
Publish all \fI\%file:///\fP references within job
definition via publishing API and rewrite URL\(aqs.
Job definition file must contain the \(aqsecrets\(aq
section which includes API_USER and API_KEY which
are used to authenticate with remote artifacts
server.
.TP
.BI \-\-artifacts\-url \ ARTIFACTS_URL
Remote server which accepts file uploads via curl.
Defaults to \fI\%https://archive.validation.linaro.org\fP
If non\-default url is used, user is responsible
for setting up the artifacts upload server as
well as relevant account and secret.
.TP
.BI \-\-artifacts\-path \ ARTIFACTS_PATH
Location on the remote server to which artifacts
will be uploaded.
Defaults to team/lava.
.TP
.B \-\-quiet\fP,\fB  \-q
Do not print out interim messages (when job becomes
Submitted or Running) but only when the job is
finished.
.UNINDENT
.UNINDENT
.TP
.B validate\-pipeline\-devices
Validate pipeline devices on the specified server. Print output in the form
of "device_hostname: {\(aqValid\(aq: null} | {\(aqInvalid\(aq: message}"
.INDENT 7.0
.TP
.B Usage:
lava\-tool validate\-pipeline\-devices [\-h] [\-\-name NAME] SERVER
.TP
.B Positional arguments:
SERVER
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-name \ NAME
Hostname of the device or device_type name.
.UNINDENT
.UNINDENT
.TP
.B compare\-device\-conf
Compare device configurations and output a diff.
.INDENT 7.0
.INDENT 3.5
.INDENT 0.0
.TP
.B Usage:
lava\-tool compare\-device\-conf [\-h] [\-\-wdiff] [\-\-use\-stored USE_STORED]
[\-\-dispatcher\-config\-dir DISPATCHER_CONFIG_DIR] [CONFIGS [CONFIGS ...]]
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B CONFIGS
List of device config paths, at least one, max two.
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-wdiff\fP,\fB  \-w
Use wdiff for parsing output
.TP
.BI \-\-use\-stored \ USE_STORED\fP,\fB \ \-u \ USE_STORED
Use stored device config with specified device
.TP
.BI \-\-dispatcher\-config\-dir \ DISPATCHER_CONFIG_DIR
Where to find the device_type templates.
.UNINDENT
.UNINDENT
.UNINDENT
.UNINDENT
.TP
.B get\-pipeline\-device\-config
Get pipeline device configuration to a local file or stdout.
.INDENT 7.0
.TP
.B Usage:
lava\-tool get\-pipeline\-device\-config [\-h] [\-\-overwrite]
[\-\-output OUTPUT] [\-\-output\-to\-stdout] SERVER DEVICE_HOSTNAME
.TP
.B Positional arguments:
.INDENT 7.0
.TP
.B SERVER
Host to download pipeline device configuration from
.TP
.B DEVICE_HOSTNAME
HOSTNAME of the pipeline device for which configuration is required
.UNINDENT
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-overwrite
Overwrite files on the local disk
.TP
.BI \-\-output \ OUTPUT\fP,\fB \ \-o \ OUTPUT
Alternate name of the output file
.TP
.B \-\-stdout
Write output to stdout
.UNINDENT
.UNINDENT
.TP
.B 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.
.INDENT 7.0
.TP
.B Usage: lava\-tool device\-dictionary [\-h] [\-\-update UPDATE] [\-\-export]
SERVER DEVICE_HOSTNAME
.TP
.B Positional arguments:
SERVER                Host to query or update the device dictionary on
DEVICE_HOSTNAME       DEVICE_HOSTNAME to query or update
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.BI \-\-update \ UPDATE\fP,\fB \ \-u \ UPDATE
Load a jinja2 file to update the device dictionary
.TP
.B \-\-export\fP,\fB  \-e
Export the device dictionary for this device as jinja2
.UNINDENT
.UNINDENT
.TP
.B job\-results
Download job results in either YAML or CSV format.
.sp
Usage: lava\-tool job\-results [\-h] [\-\-csv] SERVER JOB_ID
.INDENT 7.0
.TP
.B Positional arguments:
SERVER      Host from where to download the results.
JOB_ID      ID of the job to get results for.
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-csv
If this is specified, results will be printed out in CSV format, otherwise in YAML.
.UNINDENT
.UNINDENT
.TP
.B test\-suite\-results
Download test suite results in either YAML or CSV format.
.sp
Usage: lava\-tool test\-suite\-results [\-h] [\-\-csv] SERVER JOB_ID SUITE_NAME
.INDENT 7.0
.TP
.B 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.
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-csv
If this is specified, results will be printed out in CSV format, otherwise in YAML.
.UNINDENT
.UNINDENT
.TP
.B test\-case\-results
Download test case results in either YAML or CSV format.
.sp
Usage: lava\-tool test\-case\-results [\-h] [\-\-csv] SERVER JOB_ID SUITE_NAME TEST_CASE
.INDENT 7.0
.TP
.B 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.
.TP
.B Optional arguments:
.INDENT 7.0
.TP
.B \-h\fP,\fB  \-\-help
show this help message and exit
.TP
.B \-\-csv
If this is specified, results will be printed out in CSV format, otherwise in YAML.
.UNINDENT
.UNINDENT
.UNINDENT
.SH LAVA TEST DEFINITIONS
.sp
A LAVA Test Definition comprises of two parts:
.INDENT 0.0
.IP \(bu 2
the data to setup the test, the job definition.
.IP \(bu 2
the instructions to run inside the test, expressed as a YAML file.
.UNINDENT
.sp
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.
.sp
As a reminder, JSON job submissions relate to the \fBdeprecated\fP LAVA V1
support which is superseded by LAVA V2 using YAML for the job submission.
.sp
The latest information and help on LAVA V2 is available via the staging
instance:
.sp
\fI\%https://staging.validation.linaro.org/static/docs/v2/\fP
.SH EXAMPLES
.sp
\fBlava\-tool\fP simplifies the token handling required to interact with one or
more LAVA instances using XML\-RPC.
.sp
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 \fBhttp://localhost\fP, the lava\-tool help will be available at:
\fI\%http://localhost/static/docs/v2/lava\-tool.html#new\-features\fP
.sp
Make sure you have already logged into the instance and created an
Authentication Token using the web UI.
.sp
Alternatively, admins of up to date LAVA instances can generate a token for a
user with the \fBlava\-server manage tokens add\fP command:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lava\-tool auth\-add
http://localuser@localhost/RPC2 Paste token for
http://localuser@localhost/RPC2/: Token added successfully for user localuser.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now set the user for this authentication as the default user for this endpoint
(localhost):
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lava\-tool auth\-config \-\-default\-user http://localuser@localhost/RPC2
Auth configuration successfully updated on endpoint http://localhost/RPC2.
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Now set a shortcut for \fI\%http://localhost/RPC2\fP as local:
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ 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
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
For any instance other than \fBlocalhost\fP, always use \fBhttps\fP so
that your token is protected during transmission.
.UNINDENT
.UNINDENT
.SH BUGS AND ISSUES
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
\fBlava\-tool\fP 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. \fI\%https://validation.linaro.org/api/help/\fP Other languages also have XMLRPC support.
.UNINDENT
.UNINDENT
.SH AUTHOR
Linaro Validation Team
.SH COPYRIGHT
2010-2018, Linaro Limited
.\" Generated by docutils manpage writer.
.