# 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 Retro](https://docs.pending.ai/pai-retro)
* [PAI Generator](https://docs.pending.ai/pai-generator)

### 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.
* `retro`: Interface with the [PAI Retro](https://docs.pending.ai/pai-retro) service.
* `generator`: Interface with the [PAI Generator](https://docs.pending.ai/pai-generator) 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 retro`</mark>

Interface with the [PAI Retro](https://docs.pending.ai/pai-retro) service. Build high-throughput screening pipelines to perform low and high-throughput Retrosynthesis to find new and diverse reaction pathways and assess the synthetic accessibility of structures.

***

#### **Synopsis**

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

***

**Commands**:

* `engines`: List available retrosynthesis engines.
* `libraries`: List available building block libraries.
* `job`: A set of commands supporting submitting and exploring individual Retrosynthesis jobs.
* `batch`: A set of commands supporting large molecule library screening Retrosynthesis jobs.

***

#### **Options**

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

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

List available retrosynthesis engines. An engine provides the underlying architecture and functional procedure used for building complex multi-step synthetic routes. It is required when submitting molecules for retrosynthesis to specific an engine `id` parameter.

***

#### **Synopsis**

```bash
pendingai retro engines [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

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

List available building block libraries. Building block libraries are collections of structures used to facilitate terminating different reaction trees with purchasable information. It is required when submitting molecules for retrosynthesis to specific a list of library `id` parameters.

***

#### **Synopsis**

```bash
pendingai retro libraries [OPTIONS]
```

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

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

A set of commands supporting submitting and exploring individual Retrosynthesis jobs.

***

#### **Synopsis**

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

***

**Commands**:

* `submit`: Submit a job to a retrosynthesis engine.
* `status`: Get the status of a retrosynthesis job.
* `result`: Retrieve results for one or more jobs.
* `list`: Retrieve a list of retrosynthesis jobs.
* `delete`: Delete a retrosynthesis job.
* `routes`: Visualise generated routes from the Pending AI UI.
* `depict`: Visualise generated route from local HTML pages.

***

#### **Options**

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

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

Submit a single query molecule `SMILES` retrosynthesis job. Provide additional optional parameters to control the synthesis process. More information about these parameters is available in the [PAI Retro](https://docs.pending.ai/api-reference/pai-retro/synthesis-jobs#post-jobs) documentation.

{% hint style="info" %}
To provide multiple values for a `<LIST>` option, it should be provide in the following format `--option [VALUE] --option [VALUE]`.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro job submit [OPTIONS] SMILES
```

***

#### **Arguments**

* `<SMILES>`: A single query molecule in SMILES format to be submitted for retrosynthesis.

***

#### **Options**

| Option (Short) | Option (Long)                | Description                                                                               | Default                                 |
| -------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------- |
|                | `--engine <TEXT>`            | The engine `id` to perform retrosynthesis on.                                             | Most recently active available engine.  |
|                | `--library <LIST>`           | All library `id`'s to be used for retrosynthesis.                                         | All available building block libraries. |
|                | `--num-routes <INTEGER>`     | Maximum number of routes to generate \[1-50].                                             | `20`                                    |
|                | `--time-limit <INTEGER>`     | Maximum processing time in seconds \[60-600].                                             | `300`                                   |
|                | `--reaction-limit <INTEGER>` | Maximum number of times a reaction can appear in generated routes \[1-20].                | `3`                                     |
|                | `--block-limit <INTEGER>`    | Maximum number of times a building block molecule can appear in generated routes \[1-20]. | `3`                                     |
|                | `--json`                     | Render output as JSON.                                                                    | `false`                                 |
|                | `--help`                     | Show this message and exit.                                                               | `n/a`                                   |

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

Get the status of a retrosynthesis job.

***

#### **Synopsis**

```bash
pendingai retro job status [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

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

Retrieve results for one or more retrosynthesis jobs by a single `id` or line-delimited file of multiple job `id` values. Results return back a collection of JSON routes per query molecule. More information about the response model is available [here](https://docs.pending.ai/api-reference/pai-retro/synthesis-jobs#get-jobs-job_id).

{% hint style="info" %}
This command is slower than batch-based screening as it retrieves results individually. For simple molecule screening of synthetic accessibility, it is recommended to use batched Retrosynthesis.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro job result [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long)          | Description                                                | Default                                      |
| -------------- | ---------------------- | ---------------------------------------------------------- | -------------------------------------------- |
| `-o`           | `--output-file <FILE>` | Output filepath for writing results.                       | Auto-generated file in your local directory. |
| `-i`           | `--input-file <FILE>`  | Optional input filepath of line-delimited job `id` values. | `n/a`                                        |
|                | `--help`               | Show this message and exit.                                | `n/a`                                        |

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

Retrieve a list of retrosynthesis jobs. A paged view is made available to retrieve jobs across individual result pages. Filtering results is made available with `--status`.

***

#### **Synopsis**

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

***

#### **Options**

| Option (Short) | Option (Long)           | Description                                                                   | Default |
| -------------- | ----------------------- | ----------------------------------------------------------------------------- | ------- |
|                | `--page <INTEGER>`      | Page number being fetched.                                                    | `1`     |
|                | `--page-size <INTEGER>` | Number of results per page \[1-25].                                           | `25`    |
|                | `--status <TEXT>`       | Optional filter for status: `completed`, `failed`, `submitted`, `processing`. | `n/a`   |
|                | `--json`                | Render output as JSON.                                                        | `false` |
|                | `--help`                | Show this message and exit.                                                   | `n/a`   |

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

Delete a retrosynthesis job. The results will no longer be available and the action cannot be undone.

***

#### **Synopsis**

```bash
pendingai retro job delete [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long) | Description                 | Default |
| -------------- | ------------- | --------------------------- | ------- |
|                | `--json`      | Render output as JSON.      | `false` |
|                | `--help`      | Show this message and exit. | `n/a`   |

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

Visualise generated routes in the Pending AI UI. You will be redirected to your web browser.

***

#### **Synopsis**

```bash
pendingai retro job routes [JOB_ID]
```

***

#### **Arguments**

* `<JOB_ID>`: An `id` for a retrosynthesis job.

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

Visualise generated routes in the locally generated HTML pages. Results will be retrieved and HTML pages will be generated containing visualisations for each route. Note that the depictions can take up significant storage space if retrieved in large batches.

***

#### **Synopsis**

```bash
pendingai retro job depict [OPTIONS] [JOB_ID]
```

***

#### **Arguments**

* `[JOB_ID]`: An `id` for a retrosynthesis job.

***

#### **Options**

| Option (Short) | Option (Long)              | Description                                                | Default                                           |
| -------------- | -------------------------- | ---------------------------------------------------------- | ------------------------------------------------- |
| `-o`           | `--output-dir <DIRECTORY>` | Directory to save generated HTML depiction files.          | Auto-generated directory in your local directory. |
| `-i`           | `--input-file <FILE>`      | Optional input filepath of line-delimited job `id` values. | `n/a`                                             |
|                | `--help`                   | Show this message and exit.                                | `n/a`                                             |

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

A set of commands supporting large molecule library screening Retrosynthesis jobs.

***

#### **Synopsis**

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

***

**Commands**:

* `submit`: Submit a batch of retrosynthesis jobs.
* `status`: Check the processing status of a batch.
* `result`: Retrieve results for all jobs in a batch.
* `list`: List all submitted retrosynthesis batches.
* `delete`: Delete a completed batch of jobs.

***

#### **Options**

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

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

Submit multiple retrosynthesis jobs as a single batch. Parameters that are provided will be shared across all retrosynthesis jobs in the batch. Any duplicate SMILES will also be removed to avoid running the same job multiple times.

{% hint style="info" %}
To provide multiple values for a `<LIST>` option, it should be provide in the following format `--option [VALUE] --option [VALUE]`.
{% endhint %}

***

#### **Synopsis**

```bash
pendingai retro batch submit [OPTIONS] SMILES_FILE
```

***

#### **Arguments**

* `<SMILES_FILE>`: An input filepath containing line-delimited molecules belonging to the batch.

***

#### **Options**

| Option (Short) | Option (Long)                | Description                                                                               | Default                                 |
| -------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------- |
|                | `--engine <TEXT>`            | The engine `id` to perform retrosynthesis on.                                             | Most recently active available engine.  |
|                | `--library <LIST>`           | All library `id`'s to be used for retrosynthesis.                                         | All available building block libraries. |
|                | `--num-routes <INTEGER>`     | Maximum number of routes to generate \[1-50].                                             | `20`                                    |
|                | `--time-limit <INTEGER>`     | Maximum processing time in seconds \[60-600].                                             | `300`                                   |
|                | `--reaction-limit <INTEGER>` | Maximum number of times a reaction can appear in generated routes \[1-20].                | `3`                                     |
|                | `--block-limit <INTEGER>`    | Maximum number of times a building block molecule can appear in generated routes \[1-20]. | `3`                                     |
|                | `--help`                     | Show this message and exit.                                                               | `n/a`                                   |

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

Check the status of a retrosynthesis batch. The batch is considered complete once all of its jobs have finished processing.

***

#### **Synopsis**

```bash
pendingai retro batch status BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: An `id` for a retrosynthesis batch.

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

Retrieve results for all retrosynthesis jobs in a batch. The batch returns a different result summary compared to `pendingai retro job result` containing a summary of the screening results for all targets in the batch. See the [documentation](https://docs.pending.ai/api-reference/pai-retro/batch-screening#get-batches-batch_id-result) for more information about the response data.

**Note**: Results can be retrieved while the batch is in progress with jobs yet to be processed with `completed=false`.&#x20;

***

#### **Synopsis**

```bash
pendingai retro batch result [OPTIONS] BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: An `id` for a retrosynthesis batch.

***

#### **Options**

| Option (Short) | Option (Long)          | Description                                                           | Default                                      |
| -------------- | ---------------------- | --------------------------------------------------------------------- | -------------------------------------------- |
| `-o`           | `--output-file <FILE>` | Output filepath for writing results.                                  | Auto-generated file in your local directory. |
|                | `--summarise`          | Return a summary statistic to assess the overall result of the batch. | `false`                                      |
|                | `--help`               | Show this message and exit.                                           | `n/a`                                        |

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

List all submitted batches in a paginated format.

***

#### **Synopsis**

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

***

#### **Options**

| Option (Short) | Option (Long)      | Description                                                       | Default |
| -------------- | ------------------ | ----------------------------------------------------------------- | ------- |
|                | `--before <TEXT>`  | An optional batch `id` value to retrieve those created before it. | `n/a`   |
|                | `--after <TEXT>`   | An optional batch `id` value to retrieve those created after it.  | `n/a`   |
| `-s`           | `--size <INTEGER>` | Number of results returned by the list \[1-100].                  | `50`    |
|                | `--help`           | Show this message and exit.                                       | `n/a`   |

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

Delete a batch and all of its attached retrosynthesis jobs.

***

#### **Synopsis**

```bash
pendingai retro batch delete BATCH_ID
```

***

#### **Arguments**

* `<BATCH_ID>`: An `id` for a retrosynthesis batch.

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

Interface with the [PAI Generator](https://docs.pending.ai/pai-generator) 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.

***

#### **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 samples to generate \[1-1000000].  | `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`              |