# CLI Manual

### Getting Started

Usage of the Pending AI CLI requires

* an account for the **Pending AI Platform** and
* a locally installed Python version `>=3.9`.

The Pending AI CLI is available from the [Python Package Index](https://pypi.org/), the official third-party software repository for Python and can thus be easily installed using the package management system [pip](https://pip.pypa.io/):

{% code fullWidth="false" %}

```sh
pip install pendingai
```

{% endcode %}

Successful installation can be verified with

```bash
pendingai --version
```

which is expected to output the name and version of the Pending AI CLI.

### Authentication

Using the Pending AI services via the CLI requires an authenticated session. The `pendingai auth` command provides several subcommands to manage your authentication status.

#### Logging In

To initiate the login process, use the `login` subcommand:

```bash
pendingai auth login
```

This command uses device authorization, which will automatically open a web browser window. Follow the prompts in your browser to enter your Pending AI Platform credentials and authorize the CLI session.

For any account problems, contact Pending AI via email at `support@pending.ai`.

#### Checking Session Status

You can check the status of your current authenticated session, including details like the associated user and expiry time:

```bash
pendingai auth status
```

#### Refreshing a Session

Authenticated sessions have a limited lifetime for security reasons. If your session is close to expiring or has already expired, you can attempt to refresh it without needing to fully log in again:

```bash
pendingai auth refresh
```

This will extend the lifetime of your current session if it's still valid for refreshing.

#### Retrieving the Access Token

Successful authentication stores an access token locally on your machine. You can retrieve the current access token using:

```bash
pendingai auth token
```

{% hint style="info" %}
The access token retrieved via `pendingai auth token` can be used as a Bearer token for direct API access by including it in the `Authorization` header of each API request (e.g., `Authorization: Bearer <your_token>`).
{% endhint %}

#### Logging Out

To end your authenticated session and remove the locally cached authentication details, use the `logout` subcommand:

```bash
pendingai auth logout
```

This ensures that your credentials are no longer stored by the CLI on the current machine.

### Exploring Available Generative Models

{% hint style="info" %}
An overview of Pending AI's generative models and their characteristics can be found [here](broken://pages/ziuETMbI2dhFCzSib1wh). Please note that your account might have access to select models only. Reach out to our support at `support@pending.ai` if you want discuss your generative model options.
{% endhint %}

Before generating molecules, you might want to know which generative models are available to your account. Each model has a unique ID that can be provided to the `generator sample` command to select a model.

To list all available models, use the `models` command:

```bash
pendingai generator models
```

The output will be a table listing the available models, their version, and their current status. Only models with an `Online` status can be used for sampling.

**Example Output:**

```
┌─────────────────────────────────┬────────────────────────────┬───────────────┬─────────┐
│ ID                              │ Name                       │ Version       │ Status  │
├─────────────────────────────────┼────────────────────────────┼───────────────┼─────────┤
│ mod_2XF0UlNC3yWGLVhklkoYAS3vky0 │ diverse small transformer  │ 0.0.0-alpha.0 │ Online  │
│ mod_2XF0Y4tJrHbHxpWwppyfJFAiHJM │ docking tiny transformer   │ 0.0.0-alpha.0 │ Online  │
│ mod_2XEGInBPVsqDsW25vSvaNRcIfxs │ docking small transformer  │ 0.0.0-alpha.0 │ Online  │
│ mod_2XEGInBPVsqDsW25vSvaNRcIfxc │ docking medium transformer │ 0.0.0-alpha.0 │ Offline │
└─────────────────────────────────┴────────────────────────────┴───────────────┴─────────┘
```

You can also get this list in a machine-readable format using the `--json` flag.

### Guide: Sampling Molecules

To sample molecules from a generative model, use the `sample` command. You can specify the number of molecules to generate and the model to use.

**1. Basic Sampling**

To generate 1,000 molecules using any available online model and save them to a file named `samples.smi`:

```bash
pendingai generator sample --num-samples 1000 --output-file "samples.smi"
```

If an output file is not specified with `--output-file`, the results will be saved to a default file that follows the pattern `endingai_generator_sample_XXX.smi` with `XXX` starting at 001 and being incremented in steps of 1.

**2. Targeted Sampling with a Specific Model**

To generate 5,000 molecules specifically from the `diverse small transformer` model (using its ID from the `models` command), run:

```bash
pendingai generator sample --model "mod_2XF0UlNC3yWGLVhklkoYAS3vky0" --num-samples 5000 --output-file "samples.smi"
```

{% hint style="warning" %}
If you don't specify a model, the service will pick any model is available to your account and is online to generate the samples. It is **highly recommended** to always specify a model ID so that the generated molecules are suitable to the requirements of your specific task.
{% endhint %}

**3. Appending to an Existing File**

If you want to add more samples to an existing file without being prompted to overwrite it, use the `--append` flag:

```bash
pendingai generator sample --num-samples 2500 --output-file "samples.smi" --append
```

### Molecule Sampling Parameters

The following parameters can be used with the `pendingai generator sample` command:

* `-o, --output-file <FILE>`
  * Specifies the file path for storing the output SMILES molecules.
  * If not provided, it defaults to `pendingai_generator_sample_XXX.smi` in the current directory.
* `-n, --num-samples <INTEGER>`
  * The number of molecules you want to generate.
  * Must be an integer between 1 and 1,000,000.
  * Defaults to 500 if not specified.
* `-m, --model <TEXT>`
  * The unique ID of the model you want to use for sampling.
  * Use the `pendingai generator models` command to find available model IDs.
  * If not specified, the system will use any available online generator model.
* `-a, --append`
  * A flag to indicate that the generated molecules should be appended to the output file if it already exists.
  * This also suppresses the prompt that asks for confirmation before overwriting a file.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pending.ai/pai-generator/cli-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.