Skip to content

Command Line Interface Reference

Category "db"

CLI commands for DB management.

rally db create

Create Rally database.

rally db ensure

Creates Rally database if it doesn't exists.

rally db recreate

Drop and create Rally database.

This will delete all existing data.

rally db revision

Print current Rally database revision UUID.

rally db show

Show the connection string.

Argument Description
--creds [ref] Do not hide credentials from connection string

rally db upgrade

Upgrade Rally database to the latest state.

Category "env"

Set of commands that allow you to manage envs.

rally env check

Check availability of all platforms in environment.

Argument Description
--env <uuid> [ref] UUID or name of the env.

Type: str
--json [ref] Format output as JSON.
--detailed [ref] Show detailed information.

rally env create

Create new environment.

Argument Description
--name <name>,
-n <name> [ref]
Name of the env.

Type: str
--description <description>,
-d <description> [ref]
Env description

Type: str
--extras <extras>,
-e <extras> [ref]
JSON or YAML dict with custom non validate info.

Type: str
--from-sysenv [ref] Iterate over all available platforms and check system environment for credentials.
--spec <path>,
-s <path> [ref]
Path to env spec.

Type: str
--json [ref] Format output as JSON.
--no-use [ref] Don't set new env as default for future operations.

rally env delete

Deletes all records related to Env from db.

Argument Description
--env <uuid> [ref] UUID or name of the env.

Type: str
--force [ref] Delete DB records even if env is not destroyed.

rally env destroy

Destroy existing environment.

Argument Description
--env <uuid> [ref] UUID or name of the env.

Type: str
--skip-cleanup [ref] Do not perform platforms cleanup before destroy.
--json [ref] Format output as JSON.
--detailed [ref] Show detailed information.

rally env info

Show environment information.

Argument Description
--env <uuid> [ref] UUID or name of the env.

Type: str
--json [ref] Format output as JSON.

rally env list

List existing environments.

Argument Description
--json [ref] Format output as JSON.

rally env show

Argument Description
--env <uuid> [ref] UUID or name of the env.

Type: str
--json [ref] Format output as JSON.
--only-spec [ref] Print only a spec for the environment.

rally env use

Set default environment.

Argument Description
--env <uuid> [ref] UUID or name of a env.

Type: str
--json [ref] Format output as JSON.

Category "plugin"

Set of commands that allow you to manage Rally plugins.

rally plugin list

List all Rally plugins that match name and platform.

Argument Description
--name <name> [ref] List only plugins that match the given name.

Type: str
--platform <platform> [ref] List only plugins that are in the specified platform.

Type: str
--namespace [ref] [Deprecated since Rally 0.10.0] Use '--platform' instead.

--plugin-base <plugin_base> [ref] Plugin base class.

Type: str

rally plugin show

Show detailed information about a Rally plugin.

Argument Description
--name <name> [ref] Plugin name.

Type: str
--platform <platform> [ref] Plugin platform.

Type: str
--namespace [ref] [Deprecated since Rally 0.10.0] Use '--platform' instead.

Category "task"

Set of commands that allow you to manage tasks and results.

rally task abort

Abort a running task.

Argument Description
--uuid <uuid> [ref] UUID of task.

Type: str
--soft [ref] Abort task after current scenario finishes execution.

rally task delete

Delete task and its results.

Argument Description
--force [ref] force delete
--uuid <task-id> [ref] UUID of task or a list of task UUIDs.

Type: str

rally task detailed

Argument Description
--uuid <uuid> [ref] UUID of task. If --uuid is "last" the results of the most recently created task will be displayed.

Type: str
--iterations-data [ref] Print detailed results for each iteration.

rally task export

Export task results to the custom task's exporting system.

Argument Description
--uuid <uuid> [ref] UUIDs of tasks or json reports of tasks

Type: str
--type <type> [ref] Report type. Out-of-the-box types: JSON, HTML, HTML-Static, Elastic, JUnit-XML. HINT: You can list all types, executing `rally plugin list --plugin-base TaskExporter` command.

Type: str
--to <dest> [ref] Report destination. Can be a path to a file (in case of JSON, HTML, HTML-Static, JUnit-XML, Elastic etc. types) to save the report to or a connection string. It depends on the report type.

Type: str

rally task import

Import json results of a test into rally database

Argument Description
--file <path> [ref] JSON file with task results

Type: str
--deployment <uuid> [ref] UUID or name of a deployment.

Type: str
--tag <tag> [ref] Mark the task with a tag or a few tags.

Type: str

rally task list

List tasks, started and finished.

Displayed tasks can be filtered by status or deployment. By default 'rally task list' will display tasks from the active deployment without filtering by status.

Argument Description
--deployment <uuid> [ref] UUID or name of a deployment.

Type: str
--all-deployments [ref] List tasks from all deployments.
--status <status> [ref] List tasks with specified status. Available statuses: aborted, aborting, crashed, finished, init, paused, running, sla_failed, soft_aborting, validated, validating, validation_failed

Type: str
--tag <tag> [ref] Tags to filter tasks by.

Type: str
--uuids-only [ref] List task UUIDs only.

rally task report

Generate a report for the specified task(s).

Argument Description
--tasks [ref] [Deprecated since Rally 0.10.0] Use '--uuid' instead.

--out <path> [ref] Report destination. Can be a path to a file (in case of HTML, HTML-STATIC, etc. types) to save the report to or a connection string.

Type: str
--open [ref] Open the output in a browser.
--html [ref]
--html-static [ref]
--json [ref]
--junit [ref] [Deprecated since Rally 0.10.0] Use 'rally task export --type junit-xml' instead.
--uuid <uuid> [ref] UUIDs of tasks or json reports of tasks

Type: str

rally task results

Display raw task results.

This will produce a lot of output data about every iteration.

Argument Description
--uuid <uuid> [ref] UUID of task.

Type: str

rally task sla-check

Display SLA check results table.

Argument Description
--uuid <uuid> [ref] UUID of task.

Type: str
--json [ref] Output in JSON format.

rally task sla_check

DEPRECATED since Rally 0.8.0, use rally task sla-check instead.

Argument Description
--uuid <uuid> [ref] UUID of task.

Type: str
--json [ref] Output in JSON format.

rally task start

Run task.

If both task_args and task_args_file are specified, they are going to be merged. task_args has a higher priority so it overrides values from task_args_file. There are 3 kinds of return codes, 0: no error, 1: running error, 2: sla check failed.

Argument Description
--deployment <uuid> [ref] UUID or name of a deployment.

Type: str
--task <path>,
--filename <path> [ref]
Path to the input task file.
--task-args <json> [ref] Input task args (JSON dict). These args are used to render the Jinja2 template in the input task.

--task-args-file <path> [ref] Path to the file with input task args (dict in JSON/YAML). These args are used to render the Jinja2 template in the input task.

--tag <tag> [ref] Mark the task with a tag or a few tags.

Type: str
--no-use [ref] Don't set new task as default for future operations.
--abort-on-sla-failure [ref] Abort the execution of a task when any SLA check for it fails for subtask or workload.

rally task status

Display the current status of a task.

Argument Description
--uuid <uuid> [ref] UUID of task

Type: str

Generate workloads trends HTML report.

Argument Description
--out <path> [ref] Path to output file.

Type: str
--open [ref] Open the output in a browser.
--tasks <tasks> [ref] UUIDs of tasks, or JSON files with task results

rally task use

Set active task.

Argument Description
--uuid <uuid> [ref] UUID of the task

Type: str
--task [ref] [Deprecated since Rally 0.2.0] Use '--uuid' instead.

Type: str

rally task validate

Validate a task configuration file.

This will check that task configuration file has valid syntax and all required options of scenarios, contexts, SLA and runners are set.

If both task_args and task_args_file are specified, they will be merged. task_args has a higher priority so it will override values from task_args_file.

Argument Description
--deployment <uuid> [ref] UUID or name of a deployment.

Type: str
--task <path>,
--filename <path> [ref]
Path to the input task file.
--task-args <json> [ref] Input task args (JSON dict). These args are used to render the Jinja2 template in the input task.

--task-args-file <path> [ref] Path to the file with input task args (dict in JSON/YAML). These args are used to render the Jinja2 template in the input task.

Category "verify"

Verify an OpenStack cloud via a verifier.

rally verify add-verifier-ext

Add a verifier extension.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--source <source> [ref] Path or URL to the repo to clone verifier extension from.

Type: str
--version <version> [ref] Branch, tag or commit ID to checkout before installation of the verifier extension (the 'master' branch is used by default).

Type: str
--extra-settings <extra_settings> [ref] Extra installation settings for verifier extension.

Type: str

rally verify configure-verifier

Configure a verifier for a specific deployment.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--deployment-id <id> [ref] Deployment name or UUID. HINT: You can list all deployments, executing command `rally deployment list`.

Type: str
--reconfigure [ref] Reconfigure verifier.
--extend <path/json/yaml> [ref] Extend verifier configuration with extra options. If options are already present, the given ones will override them. Can be a path to a regular config file or just a json/yaml.

Type: str
--override <path> [ref] Override verifier configuration by another one from a given source.

Type: str
--show [ref] Show verifier configuration.

rally verify create-verifier

Create a verifier.

Argument Description
--name <name> [ref] Verifier name (for example, 'My verifier').

Type: str
--type <type> [ref] Verifier plugin name. HINT: You can list all verifier plugins, executing command `rally verify list-plugins`.

Type: str
--platform <platform> [ref] Verifier plugin platform. Should be specified in case of two verifier plugins with equal names but in different platforms.

Type: str
--namespace [ref] [Deprecated since Rally 0.10.0] Use '--platform' instead.

--source <source> [ref] Path or URL to the repo to clone verifier from.

Type: str
--version <version> [ref] Branch, tag or commit ID to checkout before verifier installation (the 'master' branch is used by default).

Type: str
--system-wide [ref] Use the system-wide environment for verifier instead of a virtual environment.
--extra-settings <extra_settings> [ref] Extra installation settings for verifier.

Type: str
--no-use [ref] Not to set the created verifier as the default verifier for future operations.

rally verify delete

Delete a verification or a few verifications.

Argument Description
--uuid <uuid> [ref] UUIDs of verifications. HINT: You can list all verifications, executing command `rally verify list`.

Type: str

rally verify delete-verifier

Delete a verifier.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--deployment-id <id> [ref] Deployment name or UUID. If specified, only the deployment-specific data will be deleted for verifier. HINT: You can list all deployments, executing command `rally deployment list`.

Type: str
--force [ref] Delete all stored verifications of the specified verifier. If a deployment specified, only verifications of this deployment will be deleted. Use this argument carefully! You can delete verifications that may be important to you.

rally verify delete-verifier-ext

Delete a verifier extension.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--name <name> [ref] Verifier extension name.

Type: str

rally verify import

Import results of a test run into the Rally database.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--deployment-id <id> [ref] Deployment name or UUID. HINT: You can list all deployments, executing command `rally deployment list`.

Type: str
--file <path> [ref] File to import test results from.

Type: str
--run-args <run_args> [ref] Arguments that might be used when running tests. For example, '{concurrency: 2, pattern: set=identity}'.

Type: str
--no-use [ref] Not to set the created verification as the default verification for future operations.

rally verify list

List all verifications.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--deployment-id <id> [ref] Deployment name or UUID. HINT: You can list all deployments, executing command `rally deployment list`.

Type: str
--tag <tag> [ref] Tags to filter verifications by.

Type: str
--status <status> [ref] Status to filter verifications by.

Type: str

rally verify list-plugins

List all plugins for verifiers management.

Argument Description
--platform <platform> [ref] Requried patform (e.g. openstack).

Type: str
--namespace [ref] [Deprecated since Rally 0.10.0] Use '--platform' instead.

rally verify list-verifier-exts

List all verifier extensions.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str

rally verify list-verifier-tests

List all verifier tests.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--pattern <pattern> [ref] Pattern which will be used for matching. Can be a regexp or a verifier-specific entity (for example, in case of Tempest you can specify 'set=smoke').

Type: str

rally verify list-verifiers

List all verifiers.

Argument Description
--status <status> [ref] Status to filter verifiers by.

Type: str

rally verify report

Generate a report for a verification or a few verifications.

Argument Description
--uuid <uuid> [ref] UUIDs of verifications. HINT: You can list all verifications, executing command `rally verify list`.

Type: str
--type <type> [ref] Report type (Defaults to JSON). Out-of-the-box types: HTML, HTML-Static, JSON, JUnit-XML. HINT: You can list all types, executing `rally plugin list --plugin-base VerificationReporter` command.

Type: str
--to <dest> [ref] Report destination. Can be a path to a file (in case of HTML, JSON, etc. types) to save the report to or a connection string. It depends on the report type.

Type: str
--open [ref] Open the output file in a browser.

rally verify rerun

Rerun tests from a verification for a specific deployment.

Argument Description
--uuid <uuid> [ref] Verification UUID. HINT: You can list all verifications, executing command `rally verify list`.

Type: str
--deployment-id <id> [ref] Deployment name or UUID. HINT: You can list all deployments, executing command `rally deployment list`.

Type: str
--failed [ref] Rerun only failed tests.
--tag <tag> [ref] Mark verification with a tag or a few tags.

Type: str
--concurrency <N> [ref] How many processes to be used for running verifier tests. The default value (0) auto-detects your CPU count.

Type: int
--detailed [ref] Show verification details such as errors of failed tests.
--no-use [ref] Not to set the finished verification as the default verification for future operations.

rally verify show

Show detailed information about a verification.

Argument Description
--uuid <uuid> [ref] Verification UUID. HINT: You can list all verifications, executing command `rally verify list`.

Type: str
--sort-by <query> [ref] Sort tests by 'name', 'duration' or 'status'.

Type: str
Defaults: name
--detailed [ref] Show verification details such as run arguments and errors of failed tests.

rally verify show-verifier

Show detailed information about a verifier.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str

rally verify start

Start a verification (run verifier tests).

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--deployment-id <id> [ref] Deployment name or UUID. HINT: You can list all deployments, executing command `rally deployment list`.

Type: str
--tag <tag> [ref] Mark verification with a tag or a few tags.

Type: str
--pattern <pattern> [ref] Pattern which will be used for running tests. Can be a regexp or a verifier-specific entity (for example, in case of Tempest you can specify 'set=smoke').

Type: str
--concurrency <N> [ref] How many processes to be used for running verifier tests. The default value (0) auto-detects your CPU count.

Type: int
--load-list <path> [ref] Path to a file with a list of tests to run.

Type: str
--skip-list <path> [ref] Path to a file with a list of tests to skip. Format: json or yaml like a dictionary where keys are test names and values are reasons.

Type: str
--xfail-list <path> [ref] Path to a file with a list of tests that will be considered as expected failures. Format: json or yaml like a dictionary where keys are test names and values are reasons.

Type: str
--detailed [ref] Show verification details such as errors of failed tests.
--no-use [ref] Not to set the finished verification as the default verification for future operations.

rally verify update-verifier

Update a verifier.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str
--update-venv [ref] Update the virtual environment for verifier.
--version <version> [ref] Branch, tag or commit ID to checkout. HINT: Specify the same version to pull the latest repo code.

Type: str
--system-wide [ref] Switch to using the system-wide environment.
--no-system-wide [ref] Switch to using the virtual environment. If the virtual environment doesn't exist, it will be created.

rally verify use

Choose a verification to use for the future operations.

Argument Description
--uuid <uuid> [ref] Verification UUID. HINT: You can list all verifications, executing command `rally verify list`.

Type: str

rally verify use-verifier

Choose a verifier to use for the future operations.

Argument Description
--id <id> [ref] Verifier name or UUID. HINT: You can list all verifiers, executing command `rally verify list-verifiers`.

Type: str