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:
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 commands.
pendingai auth login # Create a new session
pendingai auth refresh # Refresh session accesspendingai
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). Ensure you have an active subscription with the different services.
Synopsis
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 service.retro: Interface with the PAI Retro service.synth: Interface with the PAI Synth service.
Options
--version
Show the application version and exit.
n/a
--help
Show this message and exit.
n/a
pendingai docs
Open the Pending AI documentation in your default web browser. You will be redirected shortly from your terminal to the web page.
Synopsis
pendingai auth
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.
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.
Synopsis
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
--help
Show this message and exit.
n/a
pendingai auth login
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
pendingai auth logout
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
pendingai auth refresh
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
pendingai auth status
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
pendingai auth token
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.
Synopsis
pendingai generator
Interface with the PAI Generator service. Use Generative AI models for sample novel and diverse drug-like molecules to explore new chemical spaces efficiently and quickly.
Synopsis
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
--help
Show this message and exit.
n/a
pendingai generator models
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
Options
-l
--limit <INTEGER>
Limit the number of returned models.
100
--json
Render output as JSON.
false
--help
Show this message and exit.
n/a
pendingai generator sample
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
Options
-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
pendingai generator create-batch
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
Options
-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
pendingai generator batch
Retrieve a Sample Batch and its live processing status, including how many of its chunks have completed or failed so far.
Synopsis
Arguments
<BATCH_ID>: Theidof the Sample Batch to retrieve.
pendingai generator list-batches
List Sample Batches, most recently created first.
Synopsis
Options
-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
pendingai generator export-batch
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
Arguments
<BATCH_ID>: Theidof the Sample Batch to export.
Options
-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
pendingai generator delete-batch
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
Arguments
<BATCH_ID>: Theidof the Sample Batch to delete.
Options
-f
--force
Skip the confirmation prompt before deleting.
false
--help
Show this message and exit.
n/a
pendingai retro
Interface with the PAI Retro service. High-throughput deep-learning retrosynthesis: submit query molecules -- individually or as a Batch -- to an engine, monitor status, and retrieve completed routes.
Synopsis
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
--help
Show this message and exit.
n/a
pendingai retro list-engines
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
pendingai retro list-libraries
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
pendingai retro version
Retrieve the deployed retrosynthesis API version.
Synopsis
pendingai retro create
Create a retrosynthesis Job for a query SMILES structure.
Synopsis
Arguments
<SMILES>: A SMILES molecule to perform retrosynthesis on.
Options
-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
pendingai retro status
Retrieve status information for a retrosynthesis Job.
Synopsis
Arguments
<JOB_ID>: A retrosynthesis Job ID.
pendingai retro delete
Delete a retrosynthesis Job and any calculated results. This operation is not reversible.
Synopsis
Arguments
<JOB_ID>: A retrosynthesis Job ID.
pendingai retro export
Export results for one or more retrosynthesis Jobs to file, one file per Job.
Synopsis
Arguments
<JOB_IDS>: One or more retrosynthesis Job IDs.
Options
-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
pendingai retro list
Retrieve a list of retrosynthesis Jobs, most recently created first.
Synopsis
Options
-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
pendingai retro create-batch
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.
Synopsis
Arguments
<SMILES_FILE>: A filepath containing line-delimited SMILES molecules.
Options
-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
pendingai retro create-batches
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
Arguments
<SMILES_FILE>: A filepath containing line-delimited SMILES molecules.
Options
Same options as create-batch, above.
pendingai retro delete-batch
Delete a retrosynthesis Batch. This operation is not reversible.
Synopsis
Arguments
<BATCH_ID>: A retrosynthesis Batch ID.
Options
-f
--force
Skip the confirmation prompt before deleting.
false
--help
Show this message and exit.
n/a
pendingai retro export-batch
Export results from a retrosynthesis Batch to file.
Synopsis
Arguments
<BATCH_ID>: A retrosynthesis Batch ID.
Options
-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
pendingai retro list-batches
Retrieve a list of retrosynthesis Batches, most recently created first.
Synopsis
Options
-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
pendingai synth
Interface with the 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
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
--help
Show this message and exit.
n/a
pendingai synth search
Run a retrosynthetic tree search for a target SMILES molecule.
Synopsis
Arguments
<SMILES>: A SMILES molecule to perform retrosynthesis on.
Options
--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
pendingai synth create-batch
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.
Synopsis
Arguments
<SMILES_FILE>: A filepath containing line-delimited SMILES molecules.
Options
-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, 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.
pendingai synth create-batches
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
Arguments
<SMILES_FILE>: A filepath containing line-delimited SMILES molecules.
Options
Same options as create-batch, above.
pendingai synth batch
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
Arguments
<BATCH_ID>: A synth Batch ID.
Options
-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
pendingai synth list-batches
List Batches of retrosynthetic tree search Plans, most recently created first.
Synopsis
Options
-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
pendingai synth export-batch
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
Arguments
<BATCH_ID>: A synth Batch ID.
Options
-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
pendingai synth delete-batch
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
Arguments
<BATCH_ID>: A synth Batch ID.
Options
-f
--force
Skip the confirmation prompt before deleting.
false
--help
Show this message and exit.
n/a
pendingai synth plan
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
Arguments
<PLAN_ID>: A synth Plan ID.
pendingai synth list-engines
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
Options
--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
pendingai synth list-libraries
List building-block libraries available for a Plan's tree search.
Synopsis
pendingai synth version
Retrieve the deployed synth API version.