> For the complete documentation index, see [llms.txt](https://docs.pending.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pending.ai/developer-tools/cli.md).

# CLI

Documentation for the Pending AI platform CLI

## Overview

The Pending AI CLI (`pendingai` on [PyPI](https://pypi.org/project/pendingai/)) runs the Pending AI services from your terminal. It wraps the APIs, handling authentication for you:

* `pendingai generator`: [PAI Generator](https://docs.pending.ai/api-reference/pai-generator.md)
* `pendingai retro`: [PAI Retro](https://docs.pending.ai/api-reference/pai-retro.md)
* `pendingai synth`: [PAI Synth](https://docs.pending.ai/api-reference/pai-synth.md)

This page documents **version 0.21.0**. See [Installation](https://docs.pending.ai/getting-started/installation.md) to install it.

### Authentication

`pendingai auth login` opens a browser to sign in, then asks which **team** (organization) to sign in to, if you belong to more than one. Everything you run is billed to that team's plan. To switch team, log in again.

```bash
pendingai auth login                 # sign in in a browser, then pick a team
pendingai auth login --org my-team   # sign in to a team without being asked
pendingai auth login --device        # sign in with a code, e.g. over SSH (the team can't be chosen)
pendingai auth status                # show the signed-in account and team
pendingai auth refresh               # refresh the session
```

See [Setting up authentication](https://docs.pending.ai/developer-tools/guides/setting-up-a-authentication.md) for more.

### Long-running commands

* **`pendingai generator sample`** generates up to 500 molecules as one sample, polling until they're ready. For more than 500 it creates a [sample batch](https://docs.pending.ai/api-reference/pai-generator.md) instead, which stays on your account (see `list-batches` and `export-batch`) if the command is interrupted. If the model has to be started first, it says so (this takes about 10-15 s), and it reports the sampling time separately.
* **`pendingai synth search`** creates a job and waits for its routes. If the search takes too long, it prints the job's ID so you can fetch the routes later with `pendingai synth job`.

### When a request is refused for your team's plan

If your team's plan doesn't cover a request (HTTP `402`), the CLI prints the service's reason: for example, that the team has no plan, or that its monthly allowance and overage limit are used up and how much is still available. Nothing is run or billed. A team admin can check the plan and overage limit on the account portal's Billing page. See [Accounts, teams and billing](https://docs.pending.ai/getting-started/accounts-and-billing.md).

***

## Command reference

The reference below is the `--help` output of every command in `pendingai==0.21.0`. Run any command with `--help` to see it for the version you have installed.

## `pendingai`

```
 Usage: pendingai [OPTIONS] COMMAND [ARGS]...

 Pending AI Command-Line Interface.

 Cheminformatics services offered by this CLI are accessible through an API integration with the Pending AI platform. An authenticated
 session is required for use; see <pendingai auth>. Documentation is available with <pendingai docs>.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version          Show the application version and exit.                                                                                │
│ --help             Show this message and exit.                                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ docs       Open documentation in a web browser.                                                                                          │
│ auth       Authenticate with the Pending AI platform.                                                                                    │
│ retro      High-throughput deep-learning retrosynthesis service.                                                                         │
│ generator  Generative solution for molecules.                                                                                            │
│ synth      PAI Synth: fast retrosynthetic route search.                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

 For support, issues, or feature requests, please email support@pending.ai.
```

### `pendingai docs`

```
 Usage: pendingai docs [OPTIONS]

 Open documentation in a web browser.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai auth`

```
 Usage: pendingai auth [OPTIONS] COMMAND [ARGS]...

 Manage an authenticated session with the Pending AI platform.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ login    Login to a Pending AI account.                                                                                                  │
│ logout   Logout of a Pending AI account.                                                                                                 │
│ refresh  Refresh an authenticated session.                                                                                               │
│ status   Show active session information.                                                                                                │
│ token    Get the access token of the current session.                                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth login`

```
 Usage: pendingai auth login [OPTIONS]

 Login to a Pending AI account.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --org           <str>  Organization (team) ID or name to log in to; asked for if not given.                                              │
│ --device               Log in with a code instead of a browser on this machine (e.g. over SSH). The organization can't be chosen this    │
│                        way.                                                                                                              │
│ --help                 Show this message and exit.                                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth logout`

```
 Usage: pendingai auth logout [OPTIONS]

 Logout of a Pending AI account.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth refresh`

```
 Usage: pendingai auth refresh [OPTIONS]

 Refresh an authenticated session.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth status`

```
 Usage: pendingai auth status [OPTIONS]

 Show active session information.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai auth token`

```
 Usage: pendingai auth token [OPTIONS]

 Get the access token of the current session.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai retro`

```
 Usage: pendingai retro [OPTIONS] COMMAND [ARGS]...

 High-throughput deep-learning retrosynthesis service.

 Retrosynthesis predictions are generated by submitting a batch of jobs to an engine, monitoring its status, and retrieving completed
 results. For more information refer to the documentation with <pendingai docs>.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-engines    Retrieve a list of selectable Engines.                                                                                   │
│ list-libraries  Retrieve a list of selectable Libraries.                                                                                 │
│ version         Retrieve the deployed retrosynthesis API version.                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Operations ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create          Create a retrosynthesis Job for a query SMILES structure.                                                                │
│ status          Retrieve status information for a retrosynthesis Job.                                                                    │
│ delete          Delete a retrosynthesis Job and any calculated results.                                                                  │
│ export          Export results for one or more retrosynthesis Jobs to file.                                                              │
│ list            Retrieve a list of retrosynthesis Jobs.                                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Batch Operations ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create-batch    Create a retrosynthesis Batch.                                                                                           │
│ create-batches  Create multiple retrosynthesis Batches from one large SMILES file.                                                       │
│ delete-batch    Delete a retrosynthesis Batch.                                                                                           │
│ export-batch    Export results from a retrosynthesis Batch to file.                                                                      │
│ list-batches    Retrieve a list of retrosynthesis Batches.                                                                               │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list-engines`

```
 Usage: pendingai retro list-engines [OPTIONS]

 Retrieve a list of selectable Engines.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list-libraries`

```
 Usage: pendingai retro list-libraries [OPTIONS]

 Retrieve a list of selectable Libraries.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro version`

```
 Usage: pendingai retro version [OPTIONS]

 Retrieve the deployed retrosynthesis API version.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro create`

```
 Usage: pendingai retro create [OPTIONS] {SMILES}

 Create a retrosynthesis Job for a query SMILES structure.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES      <str>  A SMILES molecule to perform retrosynthesis on. [required]                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine          -e      <str>                     An Engine ID to use for retrosynthesis.                                              │
│ --library         -l      LIST                      One or more Library IDs to use for retrosynthesis.                                   │
│ --num-routes              <int range> [1<=x<=50]    Max number of retrosynthesis routes to generate. [default: 1]                        │
│ --time-limit              <int range> [60<=x<=600]  Max allowed time in seconds for a retrosynthesis Job. [default: 60]                  │
│ --reaction-limit          <int range> [1<=x<=25]    Max times a reaction can be used in retrosynthesis routes. [default: 10]             │
│ --block-limit             <int range> [1<=x<=25]    Max times a building block can be used in retrosynthesis routes. [default: 10]       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro status`

```
 Usage: pendingai retro status [OPTIONS] {JOB_ID}

 Retrieve status information for a retrosynthesis Job.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_ID      <str>  A retrosynthesis Job ID. [required]                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro delete`

```
 Usage: pendingai retro delete [OPTIONS] {JOB_ID}

 Delete a retrosynthesis Job and any calculated results.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_ID      <str>  A retrosynthesis Job ID. [required]                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro export`

```
 Usage: pendingai retro export [OPTIONS] {JOB_IDS}

 Export results for one or more retrosynthesis Jobs to file.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_IDS      <str>  One or more retrosynthesis Job IDs. [required]                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <directory>       A directory to save any command results to.                                                          │
│                                     [default:                                                                                            │
│                                     ./out]                                                                                               │
│ --format          <json|yaml|html>  Result format to use for exporting retrosynthesis results. [default: json]                           │
│ --depict                            Whether to open route depictions in HTML reports in the webbrowser.                                  │
│ --help                              Show this message and exit.                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list`

```
 Usage: pendingai retro list [OPTIONS]

 Retrieve a list of retrosynthesis Jobs.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --page    -p      <int range> [1<=x<=1000000]  Page number being fetched. [default: 1]                                                   │
│ --limit   -l      <int range> [1<=x<=100]      Number of results per page. [default: 10]                                                 │
│ --after           <str>                        Cursor for results after a specific resource ID.                                          │
│ --before          <str>                        Cursor for results before a specific resource ID.                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro create-batch`

```
 Usage: pendingai retro create-batch [OPTIONS] {SMILES_FILE}

 Create a retrosynthesis Batch.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine          -e      <str>                     An Engine ID to use for retrosynthesis.                                              │
│ --library         -l      LIST                      One or more Library IDs to use for retrosynthesis.                                   │
│ --num-routes              <int range> [1<=x<=50]    Max number of retrosynthesis routes to generate. [default: 1]                        │
│ --time-limit              <int range> [60<=x<=600]  Max allowed time in seconds for a retrosynthesis Job. [default: 60]                  │
│ --reaction-limit          <int range> [1<=x<=25]    Max times a reaction can be used in retrosynthesis routes. [default: 10]             │
│ --block-limit             <int range> [1<=x<=25]    Max times a building block can be used in retrosynthesis routes. [default: 10]       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro create-batches`

```
 Usage: pendingai retro create-batches [OPTIONS] {SMILES_FILE}

 Create multiple retrosynthesis Batches from one large SMILES file.

 The file is automatically split into as many Batches as needed to
 respect the per-batch size limit -- each chunk is created as its own,
 independently billed Batch resource. Use 'create-batch' instead for
 a file that already fits in a single Batch.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Retrosynthesis Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine          -e      <str>                     An Engine ID to use for retrosynthesis.                                              │
│ --library         -l      LIST                      One or more Library IDs to use for retrosynthesis.                                   │
│ --num-routes              <int range> [1<=x<=50]    Max number of retrosynthesis routes to generate. [default: 1]                        │
│ --time-limit              <int range> [60<=x<=600]  Max allowed time in seconds for a retrosynthesis Job. [default: 60]                  │
│ --reaction-limit          <int range> [1<=x<=25]    Max times a reaction can be used in retrosynthesis routes. [default: 10]             │
│ --block-limit             <int range> [1<=x<=25]    Max times a building block can be used in retrosynthesis routes. [default: 10]       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro delete-batch`

```
 Usage: pendingai retro delete-batch [OPTIONS] {BATCH_ID}

 Delete a retrosynthesis Batch.

 This operation is not reversible.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    BATCH_ID      <str>  A retrosynthesis Batch ID. [required]                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --force  -f        Force the command to run, skip confirmation prompts.                                                                  │
│ --help             Show this message and exit.                                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro export-batch`

```
 Usage: pendingai retro export-batch [OPTIONS] {BATCH_ID}

 Export results from a retrosynthesis Batch to file.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    BATCH_ID      <str>  A retrosynthesis Batch ID. [required]                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <file>               A filepath to save any command results to.                                                        │
│ --format          <json|yaml|csv|tsv>  Result format to use for exporting retrosynthesis batch results. [default: json]                  │
│ --force   -f                           Force the command to run, skip confirmation prompts.                                              │
│ --help                                 Show this message and exit.                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai retro list-batches`

```
 Usage: pendingai retro list-batches [OPTIONS]

 Retrieve a list of retrosynthesis Batches.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --page    -p      <int range> [1<=x<=1000000]  Page number being fetched. [default: 1]                                                   │
│ --limit   -l      <int range> [1<=x<=100]      Number of results per page. [default: 10]                                                 │
│ --after           <str>                        Cursor for results after a specific resource ID.                                          │
│ --before          <str>                        Cursor for results before a specific resource ID.                                         │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai generator`

```
 Usage: pendingai generator [OPTIONS] COMMAND [ARGS]...

 Powerful and efficient solution for creating novel, diverse, drug-like molecules. For more information refer to the documentation with
 <pendingai docs>.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-models   List molecule generator models.                                                                                            │
│ version       Retrieve the deployed generator API version.                                                                               │
│ sample        Sample molecules from a generator model and save as SMILES to file.                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Batch Operations ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create-batch  Create a Sample Batch, splitting one large sampling request into                                                           │
│               independently-processed chunks.                                                                                            │
│ batch         Retrieve a Sample Batch and its live processing status.                                                                    │
│ list-batches  List Sample Batches.                                                                                                       │
│ export-batch  Export every completed chunk's generated SMILES from a Sample Batch to                                                     │
│               a file, one SMILES per line.                                                                                               │
│ delete-batch  Delete a Sample Batch.                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator list-models`

```
 Usage: pendingai generator list-models [OPTIONS]

 List molecule generator models.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator version`

```
 Usage: pendingai generator version [OPTIONS]

 Retrieve the deployed generator API version.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator sample`

```
 Usage: pendingai generator sample [OPTIONS]

 Sample molecules from a generator model and save as SMILES to file.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output       -o      <file>              A filepath to save any command results to.                                                    │
│ --num-samples  -n      <int range> [x>=1]  Number of molecules to sample. [default: 500]                                                 │
│ --model        -m      <str>               Model ID to use for molecule sampling.                                                        │
│ --append                                   Append to the output file without prompting.                                                  │
│ --force        -f                          Force the command to run, skip confirmation prompts.                                          │
│ --help                                     Show this message and exit.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator create-batch`

```
 Usage: pendingai generator create-batch [OPTIONS]

 Create a Sample Batch, splitting one large sampling request into independently-processed chunks.

 Unlike 'sample', chunks are generated asynchronously in the background
 -- check on them with 'list-batches' and 'batch', and retrieve results
 with 'export-batch' once complete.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --num-samples  -n      <int range> [x>=1]  Number of molecules to sample. [default: 500]                                                 │
│ --model        -m      <str>               Model ID to use for molecule sampling.                                                        │
│ --help                                     Show this message and exit.                                                                   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator batch`

```
 Usage: pendingai generator batch [OPTIONS] {batch_id}

 Retrieve a Sample Batch and its live processing status.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator list-batches`

```
 Usage: pendingai generator list-batches [OPTIONS]

 List Sample Batches.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator export-batch`

```
 Usage: pendingai generator export-batch [OPTIONS] {batch_id}

 Export every completed chunk's generated SMILES from a Sample Batch to a file, one SMILES per line.

 Chunks that haven't completed yet (or failed) are skipped -- check
 'batch' first to see how many chunks are still outstanding.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <file>  A filepath to save any command results to.                                                                     │
│ --force   -f              Force the command to run, skip confirmation prompts.                                                           │
│ --help                    Show this message and exit.                                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai generator delete-batch`

```
 Usage: pendingai generator delete-batch [OPTIONS] {batch_id}

 Delete a Sample Batch.

 The batch stops appearing in 'list-batches'/'batch' immediately, but
 archiving its chunks happens in the background afterward. This
 operation is not reversible.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --force  -f        Force the command to run, skip confirmation prompts.                                                                  │
│ --help             Show this message and exit.                                                                                           │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

### `pendingai synth`

```
 Usage: pendingai synth [OPTIONS] COMMAND [ARGS]...

 PAI Synth: fast retrosynthetic route search.

 A synth job searches for routes to one target molecule and returns the routes found within its time limit, with vendor pricing for each
 building block. 'search' creates a job and waits for it; batches run jobs for many molecules in the background. Jobs and batches have the
 same shape as retrosynthesis jobs and batches.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ list-engines    List synth engines and their queue lengths.                                                                              │
│ list-libraries  List building block libraries for synth jobs.                                                                            │
│ version         Retrieve the deployed synth API version.                                                                                 │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Operations ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ search          Search for synthetic routes to a target molecule and wait for them.                                                      │
│ job             Retrieve a synth job and its routes.                                                                                     │
│ list            List synth jobs, newest first.                                                                                           │
│ delete          Delete a synth job.                                                                                                      │
│ export          Export one or more finished synth jobs to file.                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Batch Operations ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ create-batch    Create a batch of synth jobs from a SMILES file.                                                                         │
│ create-batches  Create as many synth batches as a large SMILES file needs.                                                               │
│ batch           Retrieve a synth batch and a page of its jobs.                                                                           │
│ list-batches    List synth batches, newest first.                                                                                        │
│ export-batch    Export every job in a synth batch to file.                                                                               │
│ delete-batch    Delete a synth batch and its jobs.                                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth search`

```
 Usage: pendingai synth search [OPTIONS] {SMILES}

 Search for synthetic routes to a target molecule and wait for them.

 Creates a synth job and waits for it to finish. If it takes too long,
 the job's ID is printed so it can be fetched later with 'synth job'.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES      <str>  A SMILES molecule to perform retrosynthesis on. [required]                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine      -e                     <str>                        Synth engine id, from 'synth list-engines'. The default synth engine   │
│                                                                   if omitted.                                                            │
│ --max-price                          <float range> [1<=x<=50000]  Leave out building blocks dearer than this, in USD per gram.           │
│                                                                   [default: 10000]                                                       │
│ --max-depth                          <int range> [1<=x<=20]       Most reaction steps a route may have. [default: 12]                    │
│ --timeout                            <int range> [2<=x<=15]       Each search's time limit, in seconds. [default: 10]                    │
│ --early-exit      --no-early-exit                                 Stop each search at the first route found, rather than searching for   │
│                                                                   the full time limit.                                                   │
│                                                                   [default: early-exit]                                                  │
│ --max-routes                         <int range> [1<=x<=50]       Most routes to keep for each molecule; every route found if omitted.   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth job`

```
 Usage: pendingai synth job [OPTIONS] {job_id}

 Retrieve a synth job and its routes.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    job_id      <str>  [required]                                                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --wait        <int range> [0<=x<=25]  Seconds the API may hold the request open for the job to finish (0 to 25). [default: 0]            │
│ --help                                Show this message and exit.                                                                        │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list`

```
 Usage: pendingai synth list [OPTIONS]

 List synth jobs, newest first.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth delete`

```
 Usage: pendingai synth delete [OPTIONS] {job_id}

 Delete a synth job.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    job_id      <str>  [required]                                                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth export`

```
 Usage: pendingai synth export [OPTIONS] {JOB_IDS}

 Export one or more finished synth jobs to file.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    JOB_IDS      <str>  One or more retrosynthesis Job IDs. [required]                                                                  │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <directory>       A directory to save any command results to.                                                          │
│                                     [default: ./out]                                           │
│ --format          <json|yaml|html>  Result format to use for exporting retrosynthesis results. [default: json]                           │
│ --depict                            Whether to open route depictions in HTML reports in the webbrowser.                                  │
│ --help                              Show this message and exit.                                                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth create-batch`

```
 Usage: pendingai synth create-batch [OPTIONS] {SMILES_FILE}

 Create a batch of synth jobs from a SMILES file.

 Each SMILES in the file becomes its own job, with the same search
 options. The jobs run in the background: check on them with
 'list-batches' and 'batch'.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine      -e                     <str>                        Synth engine id, from 'synth list-engines'. The default synth engine   │
│                                                                   if omitted.                                                            │
│ --max-price                          <float range> [1<=x<=50000]  Leave out building blocks dearer than this, in USD per gram.           │
│                                                                   [default: 10000]                                                       │
│ --max-depth                          <int range> [1<=x<=20]       Most reaction steps a route may have. [default: 12]                    │
│ --timeout                            <int range> [2<=x<=15]       Each search's time limit, in seconds. [default: 10]                    │
│ --early-exit      --no-early-exit                                 Stop each search at the first route found, rather than searching for   │
│                                                                   the full time limit.                                                   │
│                                                                   [default: early-exit]                                                  │
│ --max-routes                         <int range> [1<=x<=50]       Most routes to keep for each molecule; every route found if omitted.   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth create-batches`

```
 Usage: pendingai synth create-batches [OPTIONS] {SMILES_FILE}

 Create as many synth batches as a large SMILES file needs.

 The file is split to respect the per-batch size limit, and each part is
 created as its own batch. Use 'create-batch' for a file that fits in one.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    SMILES_FILE      <file>  A filepath containing line-delimited SMILES molecules. [required]                                          │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --name         -n      <str>  An optional name for a retrosynthesis Batch.                                                               │
│ --description  -d      <str>  An optional description for a retrosynthesis Batch.                                                        │
│ --skip-errors                 Skip any errors encountered during command execution.                                                      │
│ --help                        Show this message and exit.                                                                                │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Search Parameters ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --engine      -e                     <str>                        Synth engine id, from 'synth list-engines'. The default synth engine   │
│                                                                   if omitted.                                                            │
│ --max-price                          <float range> [1<=x<=50000]  Leave out building blocks dearer than this, in USD per gram.           │
│                                                                   [default: 10000]                                                       │
│ --max-depth                          <int range> [1<=x<=20]       Most reaction steps a route may have. [default: 12]                    │
│ --timeout                            <int range> [2<=x<=15]       Each search's time limit, in seconds. [default: 10]                    │
│ --early-exit      --no-early-exit                                 Stop each search at the first route found, rather than searching for   │
│                                                                   the full time limit.                                                   │
│                                                                   [default: early-exit]                                                  │
│ --max-routes                         <int range> [1<=x<=50]       Most routes to keep for each molecule; every route found if omitted.   │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth batch`

```
 Usage: pendingai synth batch [OPTIONS] {batch_id}

 Retrieve a synth batch and a page of its jobs.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list-batches`

```
 Usage: pendingai synth list-batches [OPTIONS]

 List synth batches, newest first.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Pagination Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --limit   -l      <int range> [1<=x<=100]  Number of results per page. [default: 10]                                                     │
│ --after           <str>                    Cursor for results after a specific resource ID.                                              │
│ --before          <str>                    Cursor for results before a specific resource ID.                                             │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth export-batch`

```
 Usage: pendingai synth export-batch [OPTIONS] {batch_id}

 Export every job in a synth batch to file.

 Jobs are fetched 100 at a time, so a large batch can take a while.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --output  -o      <file>               A filepath to save any command results to.                                                        │
│ --format          <json|yaml|csv|tsv>  Export format. CSV and TSV have one row per job, with its route count and cheapest route price;   │
│                                        JSON and YAML have every route.                                                                   │
│                                        [default: json]                                                                                   │
│ --force   -f                           Force the command to run, skip confirmation prompts.                                              │
│ --help                                 Show this message and exit.                                                                       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth delete-batch`

```
 Usage: pendingai synth delete-batch [OPTIONS] {batch_id}

 Delete a synth batch and its jobs.

╭─ Arguments ──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    batch_id      <str>  [required]                                                                                                     │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list-engines`

```
 Usage: pendingai synth list-engines [OPTIONS]

 List synth engines and their queue lengths.

 Pass --watch to keep refreshing and see each queue's rate of change.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --watch                                   Keep refreshing and show each engine's queue rate of change (messages/second), from            │
│                                           consecutive samples.                                                                           │
│ --interval        <float range> [x>=1.0]  Seconds between refreshes with --watch. [default: 3.0]                                         │
│ --help                                    Show this message and exit.                                                                    │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth list-libraries`

```
 Usage: pendingai synth list-libraries [OPTIONS]

 List building block libraries for synth jobs.

 Synth engines search their own building blocks, so this is usually
 empty.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```

#### `pendingai synth version`

```
 Usage: pendingai synth version [OPTIONS]

 Retrieve the deployed synth API version.

╭─ Options ────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help          Show this message and exit.                                                                                              │
╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
```
