qruise¶

The base command for the Qruise CLI.

Syntax¶

qruise [OPTIONS] COMMAND [ARGS]...

Description¶

The qruise command serves as a base for accessing and managing the Qruise ecosystem. All features are divided into subcommands bundling related functionalities and following the noun-verb convention. Hence, all calls of the qruise command line have the same basic structure:

qruise NOUN VERB ...

where NOUN is a subcommand and VERB is a sub-subcommand. It may sound intimidating at first, but it allows for a very intuitive interface. For instance, you can use the flow subcommand to run and manage flows:

$ qruise flow run # run a flow
$ qruise flow list # list all scheduled flows

Similarly, you can use the kb subcommand to interact with the knowledge base:

$ qruise kb log # show the commit history
$ qruise kb commit # commit schema changes
$ qruise kb status # check the status of the knowledge base

For a complete list of subcommands see the Subcommands section.

Configuration¶

The Qruise CLI tool can be configured using:

global configuration files
subcommand-specific files
environment variables
command-line options

Some configuration options are global (e.g. the profiles file), while other are subcommand-specific. Please refer to subcommand documentation for details on what configuration they require.

Global configuration file¶

The bulk of the configuration of the Qruise CLI is contained in the configuration.yaml file located in the $HOME/.config/qruise directory. Before running any qruise commands, make sure that the file exists and is properly structured.

Configuration hierarchy¶

As noted above, there are several ways to configure the behaviour of the qruise command, and it is entirely possible that a certain aspect of the configuration can be present in two or more places. In such cases, a source further down the list overrides any values provided previously, e.g. subcommand-specific files override global configuration files, environment variables override subcommand-specific files, and command-line options override environment variables. This hierarchical approach to configuration allows for more flexibility and is especially useful for automation.

For example, the integration branch for a flow run using qruise flow run command can be specified in the configuration.yaml file (for brevity, only relevent part of the file are shown):

profiles:
  my_profile:
    name: my_profile
    branch: main

However, if a user specifies the QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH environment variable using

epxort QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH=custom_branch_name

then custom_branch_name will be used as integration branch instead of main. Consequently, using the --branch flag will override both the configuration file and the QRUISE_FLOW_DEFAULT_INTEGRATION_BRANCH.

Lists as option values¶

Certain options in Qruise CLI accept a list of values or a list of pairs of values. While it's straightforward to specify them in configuration files, there's no standard syntax for passing such data structures in command-line options or environment variables. Hence, we've adopted the following conventions:

Lists

A list is specified as a continuous string with elements delimited by commas without whitespaces. A trailing comma is optional. See the following table for valid and invalid examples:

Valid stringsInvalid strings

String	Description
`e1`	A list with one element, `e1`.
`e1,`	A list with one element, `e1`. Note the trailing comma in the string.
`e1,e2`	A list with two elements, `e1` and `e2`.
`e1,e2,`	A list with two elements, `e1` and `e2`. Note the trailing comma in the string.
`e1,e2,e3`	A list with three elements, `e1`, `e2`, and `e3`.

String	Description
`e1, e2`	Incorrect syntax: whitespace after the comma.
`e1 ,e2`	Incorrect syntax: whitespace before the comma.

Lists of pairs:

A list of pairs is specified as a continuous string with pairs delimited by commas without whitespaces and pair elements delimited by dashes, also without whitespaces. A trailing comma is optional. See the following table for valid and invalid examples:

Valid stringsInvalid strings

String	Description
`e1-e2`	A list with a single pair consisting of elements `e1` and `e2`.
`e1-e2,`	A list with a single pair consisting of elements `e1` and `e2`. Note the trailing comma in the string.
`e1-e2,e3-e4`	A list with two pairs: `e1` and `e2`, `e3` and `e4`.
`e1-e2,e3-e4,e5-e6,`	A list with three pairs: `e1` and `e2`, `e3` and `e4`, `e5` and `e6`. Note the trailing comma in the string.

String	Description
`e1-e2,e3-`	Incorrect syntax: missing pair element in the second pair.
`e1 - e2,e3-e4`	Incorrect syntax: whitespaces around a pair elements separator.
`e1-e2, e3-e4`	Incorrect syntax: whitespace after a comma.

Options¶

Option	Default	Description
`-v, --version`		Show Qruise CLI version and exit.
`--install-completion`		Install completion for the current shell.
`--show-completion`		Show completion for the current shell, to copy it or customise the installation.
`--help`		Show a help message and exit.

Subcommands¶

Name	Description
`flow`	Run and manage flows.
`kb`	Manage the knowledge base.
`qpu`	Manage QPUs in QruiseOS.