> 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

Our platform CLI tool allows integrating the different Pending AI services directly from your terminal. The documentation for different commands are described below and interface with the offered APIs with the convenience of wrapper logic provided for authentication and other access requirements:

* [PAI Generator](/pai-generator/cli-reference.md)
* [PAI Retro](/pai-retro/cli-reference.md)
* [PAI Synth](https://app.gitbook.com/s/Noz9zcbf7tt9zePqh6Qv/pai-synth)

### Authentication

Access to the Pending AI platform requires privileged access for the listed services. Creating cached sessions via the CLI is made possible via the [`pendingai auth`](#pendingai-auth) commands.

```bash
pendingai auth login      # Create a new session
pendingai auth refresh    # Refresh session access
```

***

## <mark style="color:$primary;">`pendingai`</mark>

The main entry point for the Pending AI platform CLI. Leverage the different capabilities offered via an authenticated session using `pendingai auth --help` for more information (or [see above](#authentication)). Ensure you have an active subscription with the different services.

***

#### **Synopsis**

```bash
pendingai [OPTIONS] COMMAND [ARGS] ...
```

**Commands**:

* `docs`: Open the Pending AI documentation in your web browser.
* `auth`: Authenticate with the Pending AI platform.
* `generator`: Interface with the [PAI Generator](/pai-generator/cli-reference.md) service.
* `retro`: Interface with the [PAI Retro](/pai-retro/cli-reference.md) service.
* `synth`: Interface with the [PAI Synth](https://app.gitbook.com/s/Noz9zcbf7tt9zePqh6Qv/pai-synth) service.

***

#### **Options**

| Option (Short) | Option (Long) | Description                            | Default |
| -------------- | ------------- | -------------------------------------- | ------- |
|                | `--version`   | Show the application version and exit. | `n/a`   |
|                | `--help`      | Show this message and exit.            | `n/a`   |

### <mark style="color:$primary;">`pendingai docs`</mark>

Open the Pending AI documentation in your default web browser. You will be redirected shortly from your terminal to the web page.

***

#### **Synopsis**

```bash
pendingai docs
```

### <mark style="color:$primary;">`pendingai auth`</mark>

Manage your authenticated session with the Pending AI platform. Access to certain products is restricted by account permissions. The session created will require you to login and routinely refresh the session access.

{% hint style="warning" %}
For changes to your account such as starting a new subscription, ensure you re-login to a new session. Permissions will be refreshed from the cached access information which may cause issues.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai auth [OPTIONS] COMMAND [ARGS] ...
```

***

**Commands**:

* `login`: Login to your Pending AI account.
* `logout`: Logout of your Pending AI account.
* `refresh`: Refresh an authenticated session.
* `status`: Show active session information.
* `token`: Get the access token of the current session.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai auth login`</mark>

Login to your Pending AI account. You will be prompted with a login 6-digit code to enter when redirected to your web browser. From there you can login or **create a new account**. Once logged in, return to your terminal with a newly authenticated session - information will cached on your device to allow for repeated CLI commands.

***

#### **Synopsis**

```bash
pendingai auth login
```

#### <mark style="color:$primary;">`pendingai auth logout`</mark>

Logout of your Pending AI account. The cached session information will be deleted. Any future use of the CLI will require you to call `pendingai login` to continue.

***

#### **Synopsis**

```bash
pendingai auth logout
```

#### <mark style="color:$primary;">`pendingai auth refresh`</mark>

Refresh an authenticated session. Cached session information expires after **24 hours** in which you must refresh access for the session. If the session can no longer be refreshed, you will need to call `pendingai login` to create a new session.

***

#### **Synopsis**

```bash
pendingai auth refresh
```

#### <mark style="color:$primary;">`pendingai auth status`</mark>

Show active session information. If you have multiple accounts, you will be able to see which account you are currently using for the session and the remaining time before your session expires.

***

#### **Synopsis**

```bash
pendingai auth status 
```

#### <mark style="color:$primary;">`pendingai auth token`</mark>

Get the access token of the current session. The access token is used when interfacing with the Pending AI platform API containing your user information.

{% hint style="info" %}
Our API documentation allows you to test the different requests from your browser. This command allows you to easily copy the session token for testing authenticated API requests from the documentation.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai auth token
```

### <mark style="color:$primary;">`pendingai generator`</mark>

Interface with the [PAI Generator](/pai-generator/cli-reference.md) service. Use Generative AI models for sample novel and diverse drug-like molecules to explore new chemical spaces efficiently and quickly.

***

#### **Synopsis**

```bash
pendingai generator [OPTIONS] COMMAND [ARGS] ...
```

***

#### **Description**

**Commands**:

* `models`: List the available Generative AI models for sampling molecules.
* `sample`: Generate samples of molecules from a model.
* `create-batch`: Create a Sample Batch, splitting one large sampling request into asynchronously-processed chunks.
* `batch`: Retrieve a Sample Batch and its live processing status.
* `list-batches`: List Sample Batches.
* `export-batch`: Export the generated SMILES from a Sample Batch's completed chunks to file.
* `delete-batch`: Delete a Sample Batch.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai generator models`</mark>

List the available Generative AI models for sampling molecules. The model `id` must be specified when sampling from a particular model. The returned data from the service can be limited to the first `--limit` results of paged data to avoid waiting for the server to respond.

***

#### **Synopsis**

```bash
pendingai generator models [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)       | Description                               | Default |
| -------------- | ------------------- | ----------------------------------------- | ------- |
| `-l`           | `--limit <INTEGER>` | Limit the number of returned models. $$$$ | `100`   |
|                | `--json`            | Render output as JSON.                    | `false` |
|                | `--help`            | Show this message and exit.               | `n/a`   |

#### <mark style="color:$primary;">`pendingai generator sample`</mark>

Generate samples of molecules from a model. Output from the CLI is directed to a file for convenience. You can specify an output file and append to an existing one. Specify the particular model for sampling if necessary.

**Note**: When the `--model` option is not provided, the first available model will be used.

***

#### **Synopsis**

```bash
pendingai generator sample [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)             | Description                                                                                                                                     | Default            |
| -------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ |
| `-o`           | `--output-file <FILE>`    | Output filepath to store sampled SMILES.                                                                                                        | `pendingai_...smi` |
| `-n`           | `--num-samples <INTEGER>` | Number of molecules to generate, minimum `1`. Requests are made in chunks of 500 until the target is reached, so there is no fixed upper limit. | `500`              |
| `-m`           | `--model <TEXT>`          | Model `id` to use for sampling.                                                                                                                 | `n/a`              |
| `-a`           | `--append`                | Append to the output file without prompting.                                                                                                    | `false`            |
|                | `--help`                  | Show this message and exit.                                                                                                                     | `n/a`              |

#### <mark style="color:$primary;">`pendingai generator create-batch`</mark>

Create a Sample Batch, splitting one large sampling request into independently-processed chunks of up to 500 molecules each. Unlike `sample`, chunks are generated asynchronously in the background and are not written to a file directly -- check on progress with `list-batches`/`batch` and retrieve results with `export-batch` once complete.

***

#### **Synopsis**

```bash
pendingai generator create-batch [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)             | Description                                                       | Default |
| -------------- | ------------------------- | ----------------------------------------------------------------- | ------- |
| `-n`           | `--num-samples <INTEGER>` | Total number of molecules to generate for the batch \[1-100,000]. | `500`   |
| `-m`           | `--model <TEXT>`          | Model `id` to use for every chunk.                                | `n/a`   |
|                | `--help`                  | Show this message and exit.                                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai generator batch`</mark>

Retrieve a Sample Batch and its live processing status, including how many of its chunks have completed or failed so far.

***

#### **Synopsis**

```bash
pendingai generator batch BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: The `id` of the Sample Batch to retrieve.

#### <mark style="color:$primary;">`pendingai generator list-batches`</mark>

List Sample Batches, most recently created first.

***

#### **Synopsis**

```bash
pendingai generator list-batches [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)       | Description                                                       | Default |
| -------------- | ------------------- | ----------------------------------------------------------------- | ------- |
| `-l`           | `--limit <INTEGER>` | Number of results per page \[1-100].                              | `10`    |
|                | `--after <TEXT>`    | An optional batch `id` value to retrieve those created after it.  | `n/a`   |
|                | `--before <TEXT>`   | An optional batch `id` value to retrieve those created before it. | `n/a`   |
|                | `--help`            | Show this message and exit.                                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai generator export-batch`</mark>

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.

***

#### **Synopsis**

```bash
pendingai generator export-batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: The `id` of the Sample Batch to export.

***

#### **Options**

| Option (Short) | Option (Long)     | Description                                   | Default            |
| -------------- | ----------------- | --------------------------------------------- | ------------------ |
| `-o`           | `--output <FILE>` | Output filepath to store the exported SMILES. | `sample_batch.smi` |
| `-f`           | `--force`         | Overwrite the output file without prompting.  | `false`            |
|                | `--help`          | Show this message and exit.                   | `n/a`              |

#### <mark style="color:$primary;">`pendingai generator delete-batch`</mark>

Delete a Sample Batch. **This operation is not reversible.** The batch stops appearing in `list-batches`/`batch` immediately, but archiving its chunks happens in the background afterward.

***

#### **Synopsis**

```bash
pendingai generator delete-batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: The `id` of the Sample Batch to delete.

***

#### **Options**

| Option (Short) | Option (Long) | Description                                   | Default |
| -------------- | ------------- | --------------------------------------------- | ------- |
| `-f`           | `--force`     | Skip the confirmation prompt before deleting. | `false` |
|                | `--help`      | Show this message and exit.                   | `n/a`   |

### <mark style="color:$primary;">`pendingai retro`</mark>

Interface with the [PAI Retro](/pai-retro/cli-reference.md) service. High-throughput deep-learning retrosynthesis: submit query molecules -- individually or as a Batch -- to an engine, monitor status, and retrieve completed routes.

***

#### **Synopsis**

```bash
pendingai retro [OPTIONS] COMMAND [ARGS] ...
```

***

**Commands**:

* `list-engines`: Retrieve a list of selectable Engines.
* `list-libraries`: Retrieve a list of selectable Libraries.
* `version`: Retrieve the deployed retrosynthesis API version.
* `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.
* `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.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro list-engines`</mark>

Retrieve a list of selectable Engines. An Engine provides the underlying architecture and procedure used for building complex multi-step synthetic routes, and its `id` is used as the `--engine` value when submitting a Job or Batch.

***

#### **Synopsis**

```bash
pendingai retro list-engines
```

#### <mark style="color:$primary;">`pendingai retro list-libraries`</mark>

Retrieve a list of selectable building block Libraries. A Library is a collection of purchasable structures used to terminate reaction trees, and its `id` is used as the `--library` value when submitting a Job or Batch.

***

#### **Synopsis**

```bash
pendingai retro list-libraries
```

#### <mark style="color:$primary;">`pendingai retro version`</mark>

Retrieve the deployed retrosynthesis API version.

***

#### **Synopsis**

```bash
pendingai retro version
```

#### <mark style="color:$primary;">`pendingai retro create`</mark>

Create a retrosynthesis Job for a query SMILES structure.

***

#### **Synopsis**

```bash
pendingai retro create [OPTIONS] SMILES
```

***

#### **Arguments**

* `<SMILES>`: A SMILES molecule to perform retrosynthesis on.

***

#### **Options**

| Option (Short) | Option (Long)                | Description                                                              | Default                                 |
| -------------- | ---------------------------- | ------------------------------------------------------------------------ | --------------------------------------- |
| `-e`           | `--engine <TEXT>`            | An Engine `id` to use for retrosynthesis.                                | Most recently active available engine.  |
| `-l`           | `--library <LIST>`           | One or more Library `id`'s to use for retrosynthesis.                    | All available building block libraries. |
|                | `--num-routes <INTEGER>`     | Max number of retrosynthesis routes to generate \[1-50].                 | `1`                                     |
|                | `--time-limit <INTEGER>`     | Max allowed time in seconds for a retrosynthesis Job \[60-600].          | `60`                                    |
|                | `--reaction-limit <INTEGER>` | Max times a reaction can be used in retrosynthesis routes \[1-25].       | `10`                                    |
|                | `--block-limit <INTEGER>`    | Max times a building block can be used in retrosynthesis routes \[1-25]. | `10`                                    |
|                | `--help`                     | Show this message and exit.                                              | `n/a`                                   |

#### <mark style="color:$primary;">`pendingai retro status`</mark>

Retrieve status information for a retrosynthesis Job.

***

#### **Synopsis**

```bash
pendingai retro status JOB_ID
```

***

#### **Arguments**

* `<JOB_ID>`: A retrosynthesis Job ID.

#### <mark style="color:$primary;">`pendingai retro delete`</mark>

Delete a retrosynthesis Job and any calculated results. This operation is not reversible.

***

#### **Synopsis**

```bash
pendingai retro delete JOB_ID
```

***

#### **Arguments**

* `<JOB_ID>`: A retrosynthesis Job ID.

#### <mark style="color:$primary;">`pendingai retro export`</mark>

Export results for one or more retrosynthesis Jobs to file, one file per Job.

***

#### **Synopsis**

```bash
pendingai retro export [OPTIONS] JOB_IDS...
```

***

#### **Arguments**

* `<JOB_IDS>`: One or more retrosynthesis Job IDs.

***

#### **Options**

| Option (Short) | Option (Long)                 | Description                                                | Default |
| -------------- | ----------------------------- | ---------------------------------------------------------- | ------- |
| `-o`           | `--output <DIRECTORY>`        | A directory to save any command results to.                | `./out` |
|                | `--format <json\|yaml\|html>` | Result format to use for exporting retrosynthesis results. | `json`  |
|                | `--depict`                    | Open route depictions in HTML reports in the web browser.  | `false` |
|                | `--help`                      | Show this message and exit.                                | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro list`</mark>

Retrieve a list of retrosynthesis Jobs, most recently created first.

***

#### **Synopsis**

```bash
pendingai retro list [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)       | Description                                       | Default |
| -------------- | ------------------- | ------------------------------------------------- | ------- |
| `-p`           | `--page <INTEGER>`  | Page number being fetched.                        | `1`     |
| `-l`           | `--limit <INTEGER>` | Number of results per page \[1-100].              | `10`    |
|                | `--after <TEXT>`    | Cursor for results after a specific resource ID.  | `n/a`   |
|                | `--before <TEXT>`   | Cursor for results before a specific resource ID. | `n/a`   |
|                | `--help`            | Show this message and exit.                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro create-batch`</mark>

Create a retrosynthesis Batch from a single file of line-delimited SMILES molecules. Duplicate SMILES are removed before submission, and the retrosynthesis parameters below are shared across every Job in the Batch.

{% hint style="info" %}
A Batch is limited to a maximum number of Jobs and total request size -- use `create-batches` instead for a SMILES file too large to fit in a single Batch; it will be split automatically.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro create-batch [OPTIONS] SMILES_FILE
```

***

#### **Arguments**

* `<SMILES_FILE>`: A filepath containing line-delimited SMILES molecules.

***

#### **Options**

| Option (Short) | Option (Long)                | Description                                                              | Default                                 |
| -------------- | ---------------------------- | ------------------------------------------------------------------------ | --------------------------------------- |
| `-n`           | `--name <TEXT>`              | An optional name for the Batch.                                          | `n/a`                                   |
| `-d`           | `--description <TEXT>`       | An optional description for the Batch.                                   | `n/a`                                   |
| `-e`           | `--engine <TEXT>`            | An Engine `id` to use for retrosynthesis.                                | Most recently active available engine.  |
| `-l`           | `--library <LIST>`           | One or more Library `id`'s to use for retrosynthesis.                    | All available building block libraries. |
|                | `--num-routes <INTEGER>`     | Max number of retrosynthesis routes to generate \[1-50].                 | `1`                                     |
|                | `--time-limit <INTEGER>`     | Max allowed time in seconds for a retrosynthesis Job \[60-600].          | `60`                                    |
|                | `--reaction-limit <INTEGER>` | Max times a reaction can be used in retrosynthesis routes \[1-25].       | `10`                                    |
|                | `--block-limit <INTEGER>`    | Max times a building block can be used in retrosynthesis routes \[1-25]. | `10`                                    |
|                | `--skip-errors`              | Skip any invalid SMILES lines instead of failing.                        | `false`                                 |
|                | `--help`                     | Show this message and exit.                                              | `n/a`                                   |

#### <mark style="color:$primary;">`pendingai retro create-batches`</mark>

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.

***

#### **Synopsis**

```bash
pendingai retro create-batches [OPTIONS] SMILES_FILE
```

***

#### **Arguments**

* `<SMILES_FILE>`: A filepath containing line-delimited SMILES molecules.

***

#### **Options**

Same options as [`create-batch`](#pendingai-retro-create-batch), above.

#### <mark style="color:$primary;">`pendingai retro delete-batch`</mark>

Delete a retrosynthesis Batch. **This operation is not reversible.**

***

#### **Synopsis**

```bash
pendingai retro delete-batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: A retrosynthesis Batch ID.

***

#### **Options**

| Option (Short) | Option (Long) | Description                                   | Default |
| -------------- | ------------- | --------------------------------------------- | ------- |
| `-f`           | `--force`     | Skip the confirmation prompt before deleting. | `false` |
|                | `--help`      | Show this message and exit.                   | `n/a`   |

#### <mark style="color:$primary;">`pendingai retro export-batch`</mark>

Export results from a retrosynthesis Batch to file.

***

#### **Synopsis**

```bash
pendingai retro export-batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: A retrosynthesis Batch ID.

***

#### **Options**

| Option (Short) | Option (Long)                     | Description                                       | Default            |
| -------------- | --------------------------------- | ------------------------------------------------- | ------------------ |
| `-o`           | `--output <FILE>`                 | Output filepath to store the exported results.    | `results.<format>` |
|                | `--format <json\|yaml\|csv\|tsv>` | Result format to use for exporting Batch results. | `json`             |
| `-f`           | `--force`                         | Overwrite the output file without prompting.      | `false`            |
|                | `--help`                          | Show this message and exit.                       | `n/a`              |

#### <mark style="color:$primary;">`pendingai retro list-batches`</mark>

Retrieve a list of retrosynthesis Batches, most recently created first.

***

#### **Synopsis**

```bash
pendingai retro list-batches [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)       | Description                                       | Default |
| -------------- | ------------------- | ------------------------------------------------- | ------- |
| `-p`           | `--page <INTEGER>`  | Page number being fetched.                        | `1`     |
| `-l`           | `--limit <INTEGER>` | Number of results per page \[1-100].              | `10`    |
|                | `--after <TEXT>`    | Cursor for results after a specific resource ID.  | `n/a`   |
|                | `--before <TEXT>`   | Cursor for results before a specific resource ID. | `n/a`   |
|                | `--help`            | Show this message and exit.                       | `n/a`   |

### <mark style="color:$primary;">`pendingai synth`</mark>

Interface with the [PAI Synth](https://app.gitbook.com/s/Noz9zcbf7tt9zePqh6Qv/pai-synth) service. High-throughput retrosynthetic tree search: a single request runs a complete tree search for one target molecule and returns every validated route found within the requested time budget, along with vendor pricing for the building blocks involved. There is no separate submit/poll/retrieve cycle -- `search` runs synchronously; `create-batch`/`create-batches` instead split many target molecules into asynchronously-processed Plans.

***

#### **Synopsis**

```bash
pendingai synth [OPTIONS] COMMAND [ARGS] ...
```

***

**Commands**:

* `search`: Run a retrosynthetic tree search for a target SMILES molecule.
* `create-batch`: Create a Batch of retrosynthetic tree search Plans from a SMILES file.
* `create-batches`: Create multiple Batches of retrosynthetic tree search Plans from one large SMILES file.
* `batch`: Retrieve a Batch and a page of the Plans it contains.
* `list-batches`: List Batches of retrosynthetic tree search Plans.
* `export-batch`: Export every Plan from a Batch to file.
* `delete-batch`: Delete a Batch of retrosynthetic tree search Plans.
* `plan`: Retrieve a single Plan by its ID, including its tree search result.
* `list-engines`: List retrosynthesis engines available for a Plan's tree search.
* `list-libraries`: List building-block libraries available for a Plan's tree search.
* `version`: Retrieve the deployed synth API version.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--help`      | Show this message and exit. | `n/a`   |

#### <mark style="color:$primary;">`pendingai synth search`</mark>

Run a retrosynthetic tree search for a target SMILES molecule.

***

#### **Synopsis**

```bash
pendingai synth search [OPTIONS] SMILES
```

***

#### **Arguments**

* `<SMILES>`: A SMILES molecule to perform retrosynthesis on.

***

#### **Options**

| Option (Short) | Option (Long)                                        | Description                                                                                                     | Default                   |
| -------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------- |
|                | `--early-exit / --no-early-exit`                     | Stop as soon as one validated solution route is found, rather than searching for the full time budget.          | `--early-exit`            |
|                | `--max-seconds <FLOAT>`                              | Maximum wall-clock time in seconds to run the tree search.                                                      | `4.0`                     |
|                | `--max-depth <INTEGER>`                              | Maximum number of reaction steps (tree depth) to search \[1-50].                                                | `5`                       |
|                | `--mask-trivial-solution / --allow-trivial-solution` | Exclude the trivial zero-step solution where the target molecule is itself a purchasable building block.        | `--mask-trivial-solution` |
|                | `--mask-bblocks-mw-gte <FLOAT>`                      | Exclude building blocks with molecular weight (daltons) greater than or equal to this value.                    | `n/a`                     |
|                | `--mask-usd-pricing-gte <FLOAT>`                     | Exclude building blocks priced at or above this normalised USD-per-gram cost.                                   | `10000.0`                 |
|                | `--ships-to <TEXT>`                                  | ISO country code used to scope pricing and lead-time annotations to a specific delivery region.                 | `US`                      |
|                | `--mask-lead-times-gte <FLOAT>`                      | Exclude building blocks with a lead time (days) to the `--ships-to` region greater than or equal to this value. | `n/a`                     |
|                | `--max-backbone-groups <INTEGER>`                    | Maximum number of distinct synthetic route backbones to return.                                                 | `5`                       |
|                | `--max-backbone-group-size <INTEGER>`                | Maximum number of building-block variations to keep per backbone.                                               | `10`                      |
|                | `--limit-backbone-group-size-by-cost`                | Keep the cheapest building-block variations first when truncating to `--max-backbone-group-size`.               | `false`                   |
| `-e`           | `--engine <thieme\|pistachio>`                       | Retrosynthesis engine to run the tree search on.                                                                | `thieme`                  |
|                | `--help`                                             | Show this message and exit.                                                                                     | `n/a`                     |

#### <mark style="color:$primary;">`pendingai synth create-batch`</mark>

Create a Batch of retrosynthetic tree search Plans from a SMILES file. Each SMILES structure in the file is created as its own, independently trackable Plan, sharing the same tree search parameters. Unlike `search`, plans run asynchronously in the background -- check on them with `list-batches` and `batch`.

{% hint style="info" %}
A Batch is limited to a maximum number of Plans and total request size -- use `create-batches` instead for a SMILES file too large to fit in a single Batch; it will be split automatically.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai synth create-batch [OPTIONS] SMILES_FILE
```

***

#### **Arguments**

* `<SMILES_FILE>`: A filepath containing line-delimited SMILES molecules.

***

#### **Options**

| Option (Short) | Option (Long)          | Description                                       | Default |
| -------------- | ---------------------- | ------------------------------------------------- | ------- |
| `-n`           | `--name <TEXT>`        | An optional name for the Batch.                   | `n/a`   |
| `-d`           | `--description <TEXT>` | An optional description for the Batch.            | `n/a`   |
|                | `--skip-errors`        | Skip any invalid SMILES lines instead of failing. | `false` |

Plus all of the tree search parameters described under [`search`](#pendingai-synth-search), above (`--early-exit`/`--no-early-exit`, `--max-seconds`, `--max-depth`, `--mask-trivial-solution`/`--allow-trivial-solution`, `--mask-bblocks-mw-gte`, `--mask-usd-pricing-gte`, `--ships-to`, `--mask-lead-times-gte`, `--max-backbone-groups`, `--max-backbone-group-size`, `--limit-backbone-group-size-by-cost`, `-e`/`--engine`), plus `--help`.

#### <mark style="color:$primary;">`pendingai synth create-batches`</mark>

Create multiple Batches of retrosynthetic tree search Plans 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 trackable Batch resource. Use `create-batch` instead for a file that already fits in a single Batch.

***

#### **Synopsis**

```bash
pendingai synth create-batches [OPTIONS] SMILES_FILE
```

***

#### **Arguments**

* `<SMILES_FILE>`: A filepath containing line-delimited SMILES molecules.

***

#### **Options**

Same options as [`create-batch`](#pendingai-synth-create-batch), above.

#### <mark style="color:$primary;">`pendingai synth batch`</mark>

Retrieve a Batch and a page of the Plans it contains. A batch can have up to 100,000 plans, so this only shows one page at a time (most recently created first) -- use `--limit`/`--after`/`--before` to page through the rest.

***

#### **Synopsis**

```bash
pendingai synth batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: A synth Batch ID.

***

#### **Options**

| Option (Short) | Option (Long)       | Description                                       | Default |
| -------------- | ------------------- | ------------------------------------------------- | ------- |
| `-l`           | `--limit <INTEGER>` | Number of results per page \[1-100].              | `10`    |
|                | `--after <TEXT>`    | Cursor for results after a specific resource ID.  | `n/a`   |
|                | `--before <TEXT>`   | Cursor for results before a specific resource ID. | `n/a`   |
|                | `--help`            | Show this message and exit.                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai synth list-batches`</mark>

List Batches of retrosynthetic tree search Plans, most recently created first.

***

#### **Synopsis**

```bash
pendingai synth list-batches [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)       | Description                                       | Default |
| -------------- | ------------------- | ------------------------------------------------- | ------- |
| `-l`           | `--limit <INTEGER>` | Number of results per page \[1-100].              | `10`    |
|                | `--after <TEXT>`    | Cursor for results after a specific resource ID.  | `n/a`   |
|                | `--before <TEXT>`   | Cursor for results before a specific resource ID. | `n/a`   |
|                | `--help`            | Show this message and exit.                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai synth export-batch`</mark>

Export every Plan from a Batch of retrosynthetic tree search Plans to file. A batch can have up to 100,000 plans, fetched 100 at a time -- this can take a while for a very large batch.

***

#### **Synopsis**

```bash
pendingai synth export-batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: A synth Batch ID.

***

#### **Options**

| Option (Short) | Option (Long)                     | Description                                             | Default            |
| -------------- | --------------------------------- | ------------------------------------------------------- | ------------------ |
| `-o`           | `--output <FILE>`                 | Output filepath to store the exported results.          | `results.<format>` |
|                | `--format <json\|yaml\|csv\|tsv>` | Result format to use for exporting synth batch results. | `json`             |
| `-f`           | `--force`                         | Overwrite the output file without prompting.            | `false`            |
|                | `--help`                          | Show this message and exit.                             | `n/a`              |

#### <mark style="color:$primary;">`pendingai synth delete-batch`</mark>

Delete a Batch of retrosynthetic tree search Plans. The batch stops appearing in `list-batches`/`batch` immediately, but archiving its plans happens in the background afterward -- a large batch's plans can take a while to finish archiving. **This operation is not reversible.**

***

#### **Synopsis**

```bash
pendingai synth delete-batch [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: A synth Batch ID.

***

#### **Options**

| Option (Short) | Option (Long) | Description                                   | Default |
| -------------- | ------------- | --------------------------------------------- | ------- |
| `-f`           | `--force`     | Skip the confirmation prompt before deleting. | `false` |
|                | `--help`      | Show this message and exit.                   | `n/a`   |

#### <mark style="color:$primary;">`pendingai synth plan`</mark>

Retrieve a single Plan by its ID, including its tree search result. The result is only populated once the plan's status is `completed` -- check `batch` first if you're not sure it's done yet.

***

#### **Synopsis**

```bash
pendingai synth plan PLAN_ID
```

***

#### **Arguments**

* `<PLAN_ID>`: A synth Plan ID.

#### <mark style="color:$primary;">`pendingai synth list-engines`</mark>

List retrosynthesis engines available for a Plan's tree search, along with each engine's current queue length.

**Note**: Unlike `retro list-engines`, this is a fixed set of engines -- only the queue length is read live.

***

#### **Synopsis**

```bash
pendingai synth list-engines [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long)        | Description                                                                                                       | Default |
| -------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------- | ------- |
|                | `--watch`            | Keep refreshing and show each engine's queue rate of change (messages/second), computed from consecutive samples. | `false` |
|                | `--interval <FLOAT>` | Seconds between refreshes when using `--watch`.                                                                   | `3.0`   |
|                | `--help`             | Show this message and exit.                                                                                       | `n/a`   |

#### <mark style="color:$primary;">`pendingai synth list-libraries`</mark>

List building-block libraries available for a Plan's tree search.

***

#### **Synopsis**

```bash
pendingai synth list-libraries
```

#### <mark style="color:$primary;">`pendingai synth version`</mark>

Retrieve the deployed synth API version.

***

#### **Synopsis**

```bash
pendingai synth version
```