> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qbraid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PyQASM CLI

To provide a more interactive experience for developers, PyQASM offers a
command-line interface (CLI) tool. The CLI tool can be installed as an extra
dependency by running the following command:

```shell theme={null}
pip install 'pyqasm[cli]'
```

<Note>
  This feature is still in active development and may not be stable for
  production use
</Note>

Users can then verify their installation by running the following command:

<CodeGroup>
  ```shell Verify installation theme={null}
  pyqasm --help
  ```

  ```shell Output theme={null}
  Usage: pyqasm [OPTIONS] COMMAND [ARGS]...

  The PyQASM CLI.

  ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
  │ --version             -v        Show the version and exit.                                                     │
  │ --install-completion            Install completion for the current shell.                                      │
  │ --show-completion               Show completion for the current shell, to copy it or customize the             │
  │                                 installation.                                                                  │
  │ --help                -h        Show this message and exit.                                                    │
  ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  ╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
  │ validate   Validate OpenQASM files.                                                                            |
  | unroll     Unroll OpenQASM files.                                                                                                               │
  ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
  ```
</CodeGroup>

**Validate**

The `validate` functionality can be used to check QASM files. You can provide the path to
the QASM file or a directory as an argument to the `validate` command. The tool will then check the
semantic validity of the file(s) and return the results.

<Tabs>
  <Tab title="Validate commands">
    <CodeGroup>
      ```shell help command theme={null}
      pyqasm validate --help
      ```

      ```shell Output theme={null}
      Usage: pyqasm validate [OPTIONS] SRC_PATHS...

       Validate OpenQASM files.

      ╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
      │ *    src_paths      SRC_PATHS...  Source file or directory paths to validate.                                   │
      ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
      ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
      │ --skip       -s      TEXT  Files to skip during validation.                                                    │
      │ --help       -h            Show this message and exit.                                                         │
      ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Validate QASM files">
    <CodeGroup>
      ```shell Valid QASM file theme={null}
      $ pyqasm validate tests/cli/resources/valid1.qasm

      Success: no issues found in 1 source file

      ```

      ```shell Invalid QASM file inside a dir theme={null}
      $ pyqasm validate tests/cli/resources/

      tests/cli/resources/invalid1.qasm: error: Index 2 out of range for register of size 1 in qubit [validation]
      Found errors in 1 file (checked 3 source files)
      ```
    </CodeGroup>
  </Tab>
</Tabs>

**Unroll**

The `unroll` functionality is used to expand all macros and modular structures in OpenQASM files into flat, low-level instructions that are directly executable by quantum devices or emulators. You can provide either the path to a specific QASM file or a directory containing multiple QASM files as an argument to the `unroll` command. By default, the unrolled file is saved with the following naming convention: `<original_qasm_filename>_unrolled`

<Tabs>
  <Tab title="Unroll commands">
    <CodeGroup>
      ```shell help command theme={null}
      pyqasm unroll --help
      ```

      ```shell Output theme={null}
      Usage: pyqasm unroll [OPTIONS] SRC_PATHS...

       Unroll OpenQASM files.

      ╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
      │ *    src_paths      SRC_PATHS...  Source file or directory paths to unroll.                                     │
      ╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
      ╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
      │ --skip       -s      TEXT  Files to skip during unrolling.                                                     │
      │ --overwrite                Overwrite original files instead of creating new ones.                              │
      │ --output     -o      TEXT  Output file path (can only be used with a single input file).                       │
      │ --help       -h            Show this message and exit.                                                         │
      ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Unrolling QASM files">
    <CodeGroup>
      ```shell Unroll single QASM file theme={null}
      $ pyqasm unroll tests/cli/resources/valid1.qasm

      Successfully unrolled 1 file
      Checked 1 source file

      ```

      ```shell Unroll multiple QASM file inside a dir theme={null}
      $ pyqasm unroll tests/cli/resources/

      Successfully unrolled 2 files
      ----------------------------------------------------------------------------------------------------
      Failed to unroll: tests/cli/resources/invalid1.qasm

      [validation-error] -> Index 2 out of range for register of size 1 in qubit

      Error at line 8, column 0 in QASM file

       >>>>>> h q[2];
      ----------------------------------------------------------------------------------------------------
      Failed to unroll 1 file
      Checked 3 source files
      ```
    </CodeGroup>
  </Tab>
</Tabs>