CLI Manual

Command-line interface for accessing Pending AI's retrosynthesis service.

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, the official third-party software repository for Python and can thus be easily installed using the package management system pip:

pip install pendingai

Successful installation can be verified with

pendingai --version

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

Jobs including their results will automatically be deleted 30 days after completion. It is your responsibility to retrieve any results before this time.

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:

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 [email protected].

Checking Session Status

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

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:

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:

pendingai auth token

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>).

Logging Out

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

pendingai auth logout

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

Explore Available Engines and Libraries

Before submitting compounds, you might want to know which retrosynthesis engines and building block libraries are available to your account. You can list them using these commands:

# Display available retrosynthesis engines
pendingai retro engines

# Display available building block libraries
pendingai retro libraries

The specific engines and libraries available depend on your Pending AI Platform account configuration. Please contact support at [email protected] if you want discuss generally available and customized engines and building block libraries.

Guide: Submitting Batch Retrosynthesis Jobs

The CLI supports submitting multiple retrosynthesis queries together as a single batch. This is ideal for running large-scale synthetic feasibility campaigns efficiently. Each query molecule within the batch is processed as an individual job, but all jobs within a batch share the same search parameters.

A synthetic accessibility summary can be obtained for all queries of a batch with a single command. The summary also contains Job IDs of individual queries of the batch. These Job IDs can then be used to retrieve detailed results including route information in JSON format and route depictions in PDF format for select queries of interest.

1

1. Prepare Input File & Submit Batch

Input files for batch jobs require line-delimited query molecules encoded as SMILES. Each line should contain a single valid SMILES string. Any repeated SMILES strings within the file will be automatically removed (deduplicated) before submission.

Here is an exemplary input file, molecules_batch_1.smi :

molecules_batch_1.smi
n1nc(n(c1)C)[C@@]1(C(=O)O)CC[C@@H]1CC
C1[C@@H](Br)CCCS([C@@H](C)C(=O)O)(=O)=O
C(C1CCN(CC1)c1ncc(Cl)cn1)N(C)C
[C@H]12C[C@@H](C[C@@H]2CCC1)C[C@@H](CC1(CCCCC1)OCC)N
[C@@H](NC[C@@H](c1occc1)C)(O)c1ccccc1OC(F)F
165B
molecules_batch_1.smi
Open

To submit the batch, use the pendingai retro batch submit command, providing the path to your SMILES file as an argument:

pendingai retro batch submit molecules_batch_1.smi

Upon successful submission, the command will output a unique Batch ID (e.g., bat_aa512a2). You will need this ID to track the batch status and retrieve results.

You can customize the search parameters (like engine, libraries, time limits) for all jobs in the batch using options with the submit command. See the Batch Submission Parameters section below for details. If no options are provided, sensible defaults will be used.

2

2. Track Batch Status

You can monitor the overall progress of the batch using the pendingai retro batch status command and the Batch ID obtained in the previous step:

# Check status using the actual Batch ID
pendingai retro batch status bat_aa512a2

This command reports the status of the batch as a whole (e.g., PENDING, RUNNING, COMPLETED, FAILED). The batch is considered completed only when all individual jobs within it have finished processing.

3

3. Retrieve Batch Results

Once the batch status is COMPLETED, you can retrieve the results for all jobs within that batch using the pendingai retro batch result command:

# Retrieve results using the actual Batch ID
pendingai retro batch result bat_aa512a2

Results are saved to a file in JSON format. If the --output-file option is not provided, a default filename is generated that starts with the Batch ID and includes a timestamp (e.g., bat_aa512a2_results_2025-05-04T16-31-47.json) in the current directory.

Use the -o or --output-file option to specify a filename:

# Retrieve results and save to a specific file
pendingai retro batch result bat_aa512a2 -o molecules_batch_1_results.json

The results include synthesizability assessments and individual job IDs which can be used with other CLI commands for more detailed route analysis.

4

4. Retrieve Detailed Job Results

Taking the Job IDs of compounds of interest from the batch detailed results for multiple jobs can be retrieved by providing a file containing one Job ID per line using the -i or --input-file option:

# Create a file with Job IDs (e.g., specific_jobs.ids)
# 6800a125c14660367f058a90
# 6800a125c14660367f058aa0

# Retrieve results for jobs listed in the file
pendingai retro job result -i specific_jobs.ids

Results are returned in JSON format and by default saved to an automatically generated timestamped filename in the current working directory. Use the -o or --output-file option to optionally specify a path and filename:

# Retrieve multiple job results from file and save to another file
pendingai retro job result -i specific_jobs.ids -o specific_jobs_results.json
5

5. Depict Routes

Routes can be depicted for multiple jobs listed in an input file:

# Generate depictions for jobs listed in specific_jobs.ids
pendingai retro job depict -i specific_jobs.ids

By default, PDF files named job_<job_id>.pdf are created in the current directory. You can optionally specify a different output directory using -o or --output-dir:

# Save depictions to a specific directory
pendingai retro job depict 6800a125c14660367f058a90 -o ./depictions/

Use --force to overwrite existing PDF files without prompting.

Route depiction is an experimental feature. Feedback is welcome via [email protected]. This command can also be used effectively with Job IDs extracted from a batch result output to visualize routes for specific molecules of interest within a large campaign.

6

6. List Submitted Batches

To view a list of batches you have previously submitted, use the pendingai retro batch list command:

pendingai retro batch list

This provides a paginated overview including Batch IDs, creation times, and the number of jobs in each batch.

Example Output
┌─────────────┬───────────────────────────┬──────────────┬───────┐
│ Batch ID    │ Created                   │ Filename     │  Jobs │
├─────────────┼───────────────────────────┼──────────────┼───────┤
│ bat_aa512a2 │ 2025-04-30 16:59:52+10:00 │ targets_smi  │ 10000 │
│ bat_cd0db05 │ 2025-04-30 16:59:45+10:00 │ targets_smi  │ 10000 │
│ bat_41ddb92 │ 2025-04-30 16:59:39+10:00 │ targets_smi  │ 10000 │
└─────────────┴───────────────────────────┴──────────────┴───────┘
                          Page 1 of N

You can navigate through the list using the --page and --page-size options:

# Show page 2, with 10 batches per page
pendingai retro batch list --page 2 --page-size 10
7

7. Delete a Batch

If you no longer need a batch and its associated job data, you can delete it using the pendingai retro batch delete command, provided it has completed processing:

# Delete a completed batch using its actual Batch ID
pendingai retro batch delete bat_aa512a2

Batches that are still PENDING or PROCESSING cannot be deleted. Deleting a batch permanently removes all associated job results from the platform. This action cannot be undone.

Batch Submission Parameters

The command pendingai retro batch submit SMILES_FILE is used to submit a batch of retrosynthesis jobs, where SMILES_FILE is the mandatory path to your input file.

If no other options are provided, sensible default values are used for the job parameters applied to all jobs within the batch.

For most use cases, the default parameter values are expected to yield good results. We encourage users to start with these defaults.

Customizable parameters for the submit command are explained below. A concise description of all options can also be printed to the terminal with:

pendingai retro batch submit --help

Input File (Positional Argument)

Argument: SMILES_FILE

This is a mandatory positional argument specifying the path to the input file. The file must contain one molecule SMILES per line. SMARTS features are not supported.

Engine

Option: --engine TEXT

Specifies the identifier (TEXT) of the retrosynthesis engine to be used for executing all jobs in the batch.

You can list the names and identifiers of available retrosynthesis engines using:

pendingai retro engines

If there is only one engine available for your Pending AI Platform account it will automatically be used if the --engine option is not specified during batch submission. If your account has access to more than one engine this option is mandatory.

Building Block Library

Option: --library TEXT

Specifies the identifier (TEXT) of a building block library to be used for the jobs in this batch. This option can be repeated to include multiple specific libraries.

# Example using two specific libraries
pendingai retro batch submit mols.smi --library library_A --library library_B

If no --library option is provided, all building block libraries available to the user will be used by default.

Number of Routes

Option: --num-routes INTEGER

Default: 20

Range: [1, 50]

Controls the maximum number of potential retrosynthetic routes the software will attempt to generate for each job in the batch. The actual number of returned routes for any given job might be lower due to factors like target molecule complexity, building block availability, processing time limits, etc.

Processing Time Limit

Option: --time-limit INTEGER

Default: 300

Range: [60, 600]

Specifies the maximum processing time in seconds that the retrosynthesis engine will spend on each individual job within the batch. The actual time spent might be lower, even if fewer routes than requested are found.

Reaction Limit

Option: --reaction-limit INTEGER

Default: 3

Range: [1, 20]

Specifies the maximum number of times a particular reaction template can appear across all generated retrosynthetic routes for a single job in the batch.

Building Block Limit

Option: --block-limit INTEGER

Default: 3

Range: [1, 20]

Specifies the maximum number of times a particular building block molecule can appear within a single generated retrosynthetic route for any job in the batch.

Guide: Managing Individual Retrosynthesis Jobs

While batch submission (pendingai retro batch) is recommended for synthetic accessibility campaigns, the CLI also provides commands under pendingai retro job to operate on individual retrosynthesis jobs.

These job commands are primarily intended for testing, demonstration purposes, or retrieving detailed results for specific jobs identified from a batch analysis. For processing multiple molecules, using the batch commands is strongly recommended.

1

1. Submit a Single Job

To submit a single molecule for retrosynthesis, use the pendingai retro job submit command, providing the molecule's SMILES string as a mandatory argument.

# Submit a job with default parameters
pendingai retro job submit "CN(C(=O)C(Cl)Cl)c1ccc(O)cc1"

Upon successful submission, the command will output a unique Job ID (e.g., 6800a125c14660367f058a90). You need this ID for subsequent steps like checking status or retrieving results.

You can customize the search parameters (engine, libraries, limits, etc.) using options. See the Single Job Submission Parameters section below for details. If only the SMILES is provided, sensible defaults are used.

Remember that jobs and their results are automatically deleted 30 days after completion.

2

2. Check Job Status

Use the pendingai retro job status command along with the Job ID to track the progress of an individual job:

# Check status using the actual Job ID
pendingai retro job status 6800a125c14660367f058a90

This will display the current status (e.g., SUBMITTED, PROCESSING, COMPLETED, FAILED). You can also request the output in JSON format using the --json flag.

3

3. Retrieve Detailed Job Results

Once a job's status is COMPLETED, you can retrieve its detailed results, including the generated retrosynthetic routes, using the pendingai retro job result command.

You can retrieve results for a single job by providing its ID:

# Retrieve results for a single job ID
pendingai retro job result 6800a125c14660367f058a90

Alternatively, you can retrieve results for multiple jobs by providing a file containing one Job ID per line using the -i or --input-file option:

# Create a file with Job IDs (e.g., specific_jobs.ids)
# 6800a125c14660367f058a90
# 6800a125c14660367f058aa5

# Retrieve results for jobs listed in the file
pendingai retro job result -i specific_jobs.ids

Results are returned in JSON format. Use the -o or --output-file option to save them directly to a file:

# Retrieve single job result and save to file
pendingai retro job result 6800a125c14660367f058a90 -o single_job_result.json

# Retrieve multiple job results from file and save to another file
pendingai retro job result -i specific_jobs.ids -o multiple_job_results.json

The pendingai retro job result command is particularly useful for getting detailed route information for specific jobs identified from a batch result file by their Job ID.

4

4. Depict Routes

For completed jobs, you can generate visual depictions of the found retrosynthetic routes as PDF files using the pendingai retro job depict command.

Similar to retrieving detailed results, you can depict routes for a single Job ID:

# Generate route depiction for a single job
pendingai retro job depict 6800a125c14660367f058a90

Or for multiple jobs listed in an input file:

# Generate depictions for jobs listed in specific_jobs.ids
pendingai retro job depict -i specific_jobs.ids

By default, PDF files named job_<job_id>.pdf are created in the current directory. You can specify a different output directory using -o or --output-dir:

# Save depictions to a specific directory
pendingai retro job depict 6800a125c14660367f058a90 -o ./depictions/

Use --force to overwrite existing PDF files without prompting.

Route depiction is an experimental feature. Feedback is welcome via [email protected]. This command can also be used effectively with Job IDs extracted from a batch result output to visualize routes for specific molecules of interest within a large campaign.

5

5. List Submitted Jobs

To view a paginated list of your individual job submissions, use pendingai retro job list:

pendingai retro job list

This command displays key information, including Job ID, status, and basic parameters. You can filter by status and control pagination:

# List only completed jobs, 10 per page
pendingai retro job list --status completed --page-size 10

Use pendingai retro job result to get the full route details for completed jobs.

6

6. Delete a Job

If you no longer need an individual job and its results, you can delete it using pendingai retro job delete and its Job ID:

# Delete a specific job
pendingai retro job delete 6800a125c14660367f058a90

Deleting a job permanently removes it and its results from the platform. This action cannot be undone.

Single Job Submission Parameters

The command pendingai retro job submit SMILES is used to submit a single retrosynthesis job, where SMILES is the mandatory SMILES string of the query molecule.

If no other options are provided, sensible default values are used for the job parameters.

For most single job tests or demonstrations, the default parameter values are suitable.

Customizable parameters for the submit command are explained below. A concise description of all options can also be printed to the terminal with:

pendingai retro job submit --help

Query Molecule (Positional Argument)

Argument: SMILES

This is a mandatory positional argument specifying the SMILES string of the single query molecule for the job. SMARTS features are not supported.

Engine

Option: --engine TEXT

Specifies the identifier of the retrosynthesis engine to execute this job. If only one engine is available for your account, it will be used automatically, making this parameter optional. You can list available engine IDs using pendingai retro engines.

Building Block Library

Option: --library TEXT

Specifies the identifier (TEXT) of a building block library to be used for this job. This option can be repeated to include multiple specific libraries. Defaults to using all available libraries if not specified. See pendingai retro libraries for available IDs.

# Example using two specific libraries for a single job
pendingai retro job submit "CCO" --library library_A --library library_B

Number of Routes

Option: --num-routes INTEGER

Default: 20

Range: [1, 50]

Controls the maximum number of potential retrosynthetic routes the software will attempt to generate for this job.

Processing Time Limit

Option: --time-limit INTEGER

Default: 300

Range: [60, 600]

Specifies the maximum processing time in seconds that the retrosynthesis engine will spend on this job.

Reaction Limit

Option: --reaction-limit INTEGER

Default: 3

Range: [1, 20]

Specifies the maximum number of times a particular reaction template can appear across all generated retrosynthetic routes for this job.

Building Block Limit

Option: --block-limit INTEGER

Default: 3

Range: [1, 20]

Specifies the maximum number of times a particular building block molecule can appear within a single generated retrosynthetic route for this job.

JSON Output

Option: --json

When submitting a job, using this flag will render the confirmation output (including the Job ID) in JSON format instead of the default text format.

FAQs

I set --num-routes 50 when submitting a job or batch, but get significantly fewer than 50 routes in my results. Why?

The --num-routes option sets the maximum number of retrosynthetic routes the engine will attempt to generate per job. It acts as an upper limit. The actual number of routes found can be lower due to several factors, including:

  • The complexity of the target molecule (some molecules are inherently harder to find routes for).

  • The contents of the selected building block library/libraries.

  • The processing time limit (--time-limit) being reached before the maximum number of routes is found.

  • Internal algorithm constraints or heuristics designed to prioritize diverse or high-quality routes.

What's the difference between a Batch ID (bat_...) and a Job ID ?

  • A Batch ID refers to the entire collection of jobs submitted together using pendingai retro batch submit. You use the Batch ID to check the overall status (batch status), retrieve summarized results for all jobs in the batch (batch result), list batches (batch list), or delete the entire batch (batch delete).

  • A Job ID refers to a single retrosynthesis calculation for one specific molecule, whether submitted individually (retro job submit) or as part of a batch. You typically obtain Job IDs from the output of pendingai retro batch result. These Job IDs are then used to get detailed results including route information (job result) or route depictions (job depict) for that specific molecule.

How do I get the detailed routes for specific molecules after running a batch?

  1. Run pendingai retro batch result <your_batch_id> -o batch_results.json to get the results for the entire batch, saving them to a file.

  2. Inspect the batch_results.json file. Each entry will contain information about a specific molecule from your input file, including its corresponding Job ID <job_id>.

  3. Identify the Job IDs for the molecules you are interested in.

  4. Use pendingai retro job result <job_id> (for one job) or pendingai retro job result -i <file_with_job_ids> (for multiple jobs) to retrieve the detailed results, including the routes, for those specific jobs.

  5. Alternatively, use pendingai retro job depict <job_id> or pendingai retro job depict -i <file_with_job_ids> to generate PDF depictions of the routes.

What happens if one job fails within a batch?

The batch processing system is designed to be robust. If an individual job within a batch fails (e.g., due to an invalid input SMILES or an unexpected engine error for that specific molecule), it typically does not stop the entire batch. Other jobs in the batch will continue to process. When you retrieve the batch results using pendingai retro batch result, the status or result entry for the failed job should indicate the failure. The overall batch status might still eventually become COMPLETED if all other jobs finish, but you should check the individual job statuses within the batch result file for any failures.

My batch submission failed immediately. What should I check?

Common reasons for immediate batch submission failure include:

  • Authentication: Ensure you are logged in (pendingai auth status). Try refreshing your session (pendingai auth refresh) or logging in again (pendingai auth login).

  • Input File: Verify the path to your SMILES file is correct and that the file exists and is readable. Check that the file contains valid SMILES strings, one per line. Invalid characters or formatting can cause errors.

  • Invalid Parameters: Double-check any options you provided (e.g., --engine, --library, numeric limits) to ensure the values are valid and available to your account. Use pendingai retro engines and pendingai retro libraries to confirm IDs.

  • Permissions: Ensure your account has permission to use the selected engine and libraries. Contact support if you suspect a permissions issue.

How many SMILES can my input file contain for a batch submission?

The number of SMILES per input file is limited to 100,000. Please reach out to our support at [email protected] to discuss options to increase this limit.

Last updated

Was this helpful?