Command Line Interface

Using the CLI to get and manage system information

Your QMI comes pre-configured with the QCS Command-Line Interface (CLI). The CLI allows you to view a list of available QPU lattices, and easily book and manage reservations. The CLI is available directly after logging into your QMI, or from a terminal window of your JupyterLab notebook environment.

Usage and Help

Once you've connected to your QMI, you can list all available CLI commands with the following command:

[forest@3414-qmi ~]$ qcs help
The Rigetti QCS Command Line Interface (CLI)
VERSION
qcs-cli/1.0.0 linux-x64 node-v8.16.1
USAGE
$ qcs [COMMAND]
COMMANDS
cancel Cancel reservations in the compute schedule.
devices View available QPU devices.
help display help for qcs
lattices View available lattices.
qmis View, create, start/stop, and delete QMIs.
reservations View the compute block schedule.
reserve Book reservations in the compute schedule.

To use a command, simply type qcs followed by the command:

[forest@3414-qmi ~]$ qcs devices
DEVICE
Name: Aspen-8

To obtain more information about any command and possible flags type the command with --help flag

[forest@3414-qmi ~]$ qcs devices --help
View available QPU devices.
USAGE
$ qcs devices
OPTIONS
-f, --format=json|json-pretty|tabular [default: tabular] Data serialization format.
-h, --help show CLI help
EXAMPLE
$ qcs devices

From the example above you can see that qcs will often display display its output in a variety of formats including JSON. The default tabular format is intended to be easy to read on a terminal. For certain commands, using one of the JSON formats will provide you with more detailed information than is available through the tabular format. JSON output is designed to support integrating CLI output into scripts or programs.

System Status Commands

devices - obtain a list of QPUs available for your account.

To obtain a list of available Rigetti QPUs use the devices command:

[forest@3414-qmi ~]$ qcs devices
DEVICE
Name: Aspen-8

If you use either --format=json or --format-json-pretty then you will see a JSON object containing additional information about each QPU that is available. It is beyond the scope of this document to describe the JSON format and that format is subject to change without notice.

qmis - list status of QMIs for your account

To obtain a list and status including IP address of any QMIs associated with this account use the qmis command:

[forest@3414-qmi ~]$ qcs qmis
ID IP STATUS
1327 64.84.56.7 ACTIVE

The following flags are also available modify the QMI command.

Flag

Action

create

Create a QMI. Requires specifying an SSH public key with --keypath, and optional a timezone with a --timezone

delete

Delete a QMI. Requires specifying a QMI to delete with the --id flag.

start

Start previously stopped QMI, requires specifying a QMI with the --id flag.

stop

Stop a running QMI, required specifuing a QMI with the --id flag.

QPU Reservation Commands

reserve - make a reservation for QPU time

To create a new reservation for QPU time, use the reserve command and follow the prompts. The following describes

[forest@3414-qmi ~]$ qcs reserve
Available credits: $5,000.00
The next available compute block is:
START END DURATION LATTICE PRICE
2020-07-19 17:00 PDT 2020-07-19 17:15 PDT 15.00m Aspen-8 $0.00
Accept? Type (y)es, (n)o to continue looking, or (q)uit: y
Booking reservation(s)...
Reservation(s) confirmed, run 'qcs reservations' to see the latest schedule.

If you type n at the prompt asking to accept the next available block, you will be presented with a list of alternative reservations to choose from.

Flag

Action

start

Specify a start time for the reservation (defalut is now). You can be fairly free form, but if you have spaces use quotes. e.g. "Friday at 5pm".

duration

Duration of requested reservation.

reservations - list QPU reservations for your account.

To obtain a list of pending reservations for your account, use the reservations command.

[forest@3414-qmi ~]$ qcs reservations
UPCOMING COMPUTE BLOCKS
ID START END DURATION LATTICE PRICE
34857 2020-07-19 17:00 PDT 2020-07-19 17:15 PDT 15.00m Aspen-8 $0.00

cancel - cancel a reservation

To delete a pending reservation use the cancel command. This is the same as deleting a reservation with the reserve --delete command.

[forest@3414-qmi ~]$ qcs cancel --id=34857
UPCOMING COMPUTE BLOCKS
ID START END DURATION LATTICE PRICE
34857 2020-07-19 17:00 PDT 2020-07-19 17:15 PDT 15.00m Aspen-8 $0.00
Cancel reservation(s)? (y)es, (N)o: y
Reservation(s) cancelled. Type 'qcs reservations' to see the latest schedule.