# 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.
{% hint style="warning" %} Jobs including their results will automatically be deleted **30 days** after completion. It is your responsibility to retrieve any results before this time. {% endhint %} ## 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](broken://pages/79SanmFt6Ukc91gX4WUo) access by including it in the `Authorization` header of each API request (e.g., `Authorization: Bearer `). {% 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.
## 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: ```bash # Display available retrosynthesis engines pendingai retro engines # Display available building block libraries pendingai retro libraries ``` {% hint style="info" %} The specific engines and libraries available depend on your Pending AI Platform account configuration. Please contact support at `support@pending.ai` if you want discuss generally available and customized engines and building block libraries. {% endhint %} ## 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. {% stepper %} {% step %} **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` : {% code title="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 ``` {% endcode %} {% file src="/files/FvnuAnV9dCshCOUJJrLk" %} To submit the batch, use the `pendingai retro batch submit` command, providing the path to your SMILES file as an argument: ```bash 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](#batch-submission-parameters) section below for details. If no options are provided, sensible defaults will be used.
{% endstep %} {% step %} **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: ```bash # 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. {% endstep %} {% step %} **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: ```bash # 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: ```bash # 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.
{% endstep %} {% step %} **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: ```bash # 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: ```bash # Retrieve multiple job results from file and save to another file pendingai retro job result -i specific_jobs.ids -o specific_jobs_results.json ``` {% endstep %} {% step %} **5. Depict Routes** Routes can be depicted for multiple jobs listed in an input file: ```bash # Generate depictions for jobs listed in specific_jobs.ids pendingai retro job depict -i specific_jobs.ids ``` By default, PDF files named `job_.pdf` are created in the current directory. You can optionally specify a different output directory using `-o` or `--output-dir`: ```bash # Save depictions to a specific directory pendingai retro job depict 6800a125c14660367f058a90 -o ./depictions/ ``` Use `--force` to overwrite existing PDF files without prompting. {% hint style="info" %} Route depiction is an experimental feature. Feedback is welcome via `support@pending.ai`. 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. {% endhint %} {% endstep %} {% step %} **6. List Submitted Batches** To view a list of batches you have previously submitted, use the `pendingai retro batch list` command: ```bash pendingai retro batch list ``` This provides a paginated overview including Batch IDs, creation times, and the number of jobs in each batch. {% code title="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 ``` {% endcode %} You can navigate through the list using the `--page` and `--page-size` options: ```bash # Show page 2, with 10 batches per page pendingai retro batch list --page 2 --page-size 10 ``` {% endstep %} {% step %} **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: ```bash # Delete a completed batch using its actual Batch ID pendingai retro batch delete bat_aa512a2 ``` {% hint style="warning" %} 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. {% endhint %}
{% endstep %} {% endstepper %} ## 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. {% hint style="success" %} For most use cases, the **default parameter values** are expected to yield good results. We encourage users to start with these defaults. {% endhint %} Customizable parameters for the `submit` command are explained below. A concise description of all options can also be printed to the terminal with: ```bash 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: ```bash pendingai retro engines ``` {% hint style="info" %} 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. {% endhint %} ### 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. ```bash # Example using two specific libraries pendingai retro batch submit mols.smi --library library_A --library library_B ``` {% hint style="info" %} If no `--library` option is provided, **all building block libraries** available to the user will be used by default. {% endhint %} ### 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. {% hint style="success" %} 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. {% endhint %} {% stepper %} {% step %} **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. ```bash # 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](#single-job-submission-parameters) section below for details. If only the SMILES is provided, sensible defaults are used. {% hint style="warning" %} Remember that jobs and their results are automatically deleted **30 days** after completion. {% endhint %} {% endstep %} {% step %} **2. Check Job Status** Use the `pendingai retro job status` command along with the Job ID to track the progress of an individual job: ```bash # 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. {% endstep %} {% step %} **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: ```bash # 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: ```bash # 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: ```bash # 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 ``` {% hint style="info" %} 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. {% endhint %} {% endstep %} {% step %} **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: ```bash # Generate route depiction for a single job pendingai retro job depict 6800a125c14660367f058a90 ``` Or for multiple jobs listed in an input file: ```bash # Generate depictions for jobs listed in specific_jobs.ids pendingai retro job depict -i specific_jobs.ids ``` By default, PDF files named `job_.pdf` are created in the current directory. You can specify a different output directory using `-o` or `--output-dir`: ```bash # Save depictions to a specific directory pendingai retro job depict 6800a125c14660367f058a90 -o ./depictions/ ``` Use `--force` to overwrite existing PDF files without prompting. {% hint style="info" %} Route depiction is an **experimental feature**. Feedback is welcome via `support@pending.ai`. 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. {% endhint %} {% endstep %} {% step %} **5. List Submitted Jobs** To view a paginated list of your individual job submissions, use `pendingai retro job list`: ```bash pendingai retro job list ``` This command displays key information, including Job ID, status, and basic parameters. You can filter by status and control pagination: ```bash # 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. {% endstep %} {% step %} **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: ```bash # Delete a specific job pendingai retro job delete 6800a125c14660367f058a90 ``` {% hint style="warning" %} Deleting a job permanently removes it and its results from the platform. This action cannot be undone. {% endhint %} {% endstep %} {% endstepper %} ## 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. {% hint style="success" %} For most single job tests or demonstrations, the **default parameter values** are suitable. {% endhint %} Customizable parameters for the `submit` command are explained below. A concise description of all options can also be printed to the terminal with: ```bash 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. ```bash # 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 -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 ``. 3. Identify the Job IDs for the molecules you are interested in. 4. Use `pendingai retro job result ` (for one job) or `pendingai retro job result -i ` (for multiple jobs) to retrieve the detailed results, including the routes, for those specific jobs. 5. Alternatively, use `pendingai retro job depict ` or `pendingai retro job depict -i ` 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 `support@pending.ai` to discuss options to increase this limit. --- # 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-retro/cli-reference.md?ask= ``` 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.