# QCS CLI Reference

This document serves as a reference for QCS CLI commands and configuration.

{% hint style="success" %}
For a guided tour of the QCS CLI, including how to install it and configure credentials, see [Using the QCS CLI](https://docs.rigetti.com/qcs/guides/using-the-qcs-cli).
{% endhint %}

## Commands

### Basic Commands

#### `help`

> Usage: `qcs help [<command>]`

Display help for any specified command (or subcommand). If no command is given, this will display help for available top-level commands.

{% hint style="info" %}
Alternately, use the `-h` or `--h` flag with any command to display help.
{% endhint %}

#### `help-config`

> Usage: `qcs help-config`

Display [CLI configuration](#configuration-commands) guidance.

#### `help-input`

> Usage: `qcs help-input`

Display guidance on formatting input to [API commands](#api-commands).

#### `version`

> Usage: `qcs version [current|latest|update]`

`current`: Display version information for installed CLI (default).

`latest`: Display version information for latest available CLI.

`update`: Update installed CLI to latest available version.

### API Commands

> Usage: `qcs api [<command>]`

The `api` commands provide a comprehensive set of ways to interact with the [QCS API](https://docs.rigetti.com/qcs/references/qcs-api).

Use `qcs help api` and [`qcs help-input`](#help-input) for full details on using API commands.

{% hint style="success" %}
All timestamps supplied to `qcs api` subcommands must be in [RFC3339 format](https://tools.ietf.org/html/rfc3339). Use [`qcs tools format-date`](#format-date) to format a human-friendly date as an RFC3339 timestamp.
{% endhint %}

### Tool Commands

> Usage: `qcs tools [<command>]`

The `tools` commands provide convenient helpers for common tasks.

See below (or use `qcs help tools`) for details on available commands.

#### `format-date`

> Usage: `qcs tools format-date <date-string>`

Format a human-friendly date string as an [RFC3339](https://tools.ietf.org/html/rfc3339) timestamp, for use with [API commands](#api-commands).

Example:

```bash
qcs tools format-date "Jan  2 15:04:05 PDT 2006"
```

will output:

```
2006-01-02T14:04:05-08:00
```

#### `reserve`

> Usage: `qcs tools reserve --quantum-processor-id <id> [<options>]`

List available reservations for a QPU and interactively book.

**Available Options:**

`--duration` , `-d`

> *string*, default: `15m0s`

Duration of reservation, specified as a sequence of positive or negative numbers, each with a time unit suffix.

Examples: `300ms`, `-1.5h` or `2h45m`

Valid time units are:

* `ns`: Nanoseconds
* `us` (or `µs`): Microseconds
* `ms`: Milliseconds
* `s`: Seconds
* `m`: Minutes
* `h`: Hours

![](https://2751305033-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZEieIEeLjYyh3wXFpS%2F-M_WyY8Pf-sxGUe9dw6H%2F-M_Wy57u2ES39mgcSrYR%2Fhr.png?alt=media\&token=4c62dd34-0b3a-4860-8f5a-6ace911fc3bb)

`--next-available`

> *boolean*

Book the next available reservation.

{% hint style="danger" %}
Including this flag will **immediately** purchase the next available reservation, without additional confirmation.
{% endhint %}

![](https://2751305033-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZEieIEeLjYyh3wXFpS%2F-M_WyY8Pf-sxGUe9dw6H%2F-M_Wy57u2ES39mgcSrYR%2Fhr.png?alt=media\&token=4c62dd34-0b3a-4860-8f5a-6ace911fc3bb)

`--notes`

> *string*

Notes to add to reservation.

![](https://2751305033-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MZEieIEeLjYyh3wXFpS%2F-M_WyY8Pf-sxGUe9dw6H%2F-M_Wy57u2ES39mgcSrYR%2Fhr.png?alt=media\&token=4c62dd34-0b3a-4860-8f5a-6ace911fc3bb)

`--quantum-processor-id`, `-q`

> *string*, **required**

ID of quantum processor to reserve.

`--start-time-from`, `-s`

> *string*, default: current time

Time after which to search for available reservations.

{% hint style="info" %}
For details on allowed time formats, refer to [this page](https://github.com/araddon/dateparse#extended-example).
{% endhint %}

### Configuration Commands

QCS CLI commands derive configuration from the environment:

| Environment Variable | Default Value          | Description |
| -------------------- | ---------------------- | ----------- |
| `QCS_PROFILE_NAME`   | `default`              |             |
| `QCS_SETTINGS_FILE`  | `~/.qcs/settings.toml` |             |
| `QCS_SECRETS_FILE`   | `~/.qcs/secrets.toml`  |             |

* `QCS_SETTINGS_FILE` (default&#x20;

The [`settings`](#settings) and `secrets` commands provide functionality for reading and updating settings and credentials for the QCS CLI.

Use `qcs help settings`, `qcs help secrets`, and [`qcs help-config`](#help-config) for full details on all available commands.

{% hint style="info" %}
The default locations for settings and secrets are `~/.qcs/settings.toml` and `~/.qcs/secrets.toml`, respectively.

These locations can be overridden by setting the `QCS_SETTINGS_FILE_PATH`and`QCS_SECRETS_FILE_PATH` environment variables, respectively.
{% endhint %}