Coding and deploying AI services with ibm-watsonx-ai-cli

Last updated: May 27, 2025

Use the ibm-watsonx-ai-cli Python package to download, edit, test, and deploy AI services from your local environment.

By using ibm-watsonx-ai-cli, depending on your needs, you can:

Test an AI service locally, without deploying it, by passing arguments to a template that was downloaded to your local environment.
Deploy an AI service in watsonx.ai and then test it locally, by passing arguments to the deployed service.
Download, deploy, and test an app that is based on an AI service.

Prerequisites:

Python 3.11
The Poetry packaging and dependency management tool must be installed in the local environment. To install Poetry, follow the instructions on the Poetry installation page.

To start working with AI service templates in your local environment, you must first install ibm-watsonx-ai-cli. To install ibm-watsonx-ai-cli, type this command on your local machine: pip install -U ibm-watsonx-ai-cli.

Important:

Some templates require a correctly prepared config file (config.toml). If a downloaded template contains config.toml with placeholders, read its description carefully and fill in the required fields.
For security reasons, it is recommended not to hard-code your API key or other secrets directly in your scripts or in the config.toml file. Instead, set them up as environment variables and then access the variables from your code. For example: WATSONX_APIKEY = os.environ.get("WATSONX_APIKEY", "").

Example flow for deploying an AI service

To deploy AI service templates by using ibm-watsonx-ai-cli, refer to this example flow:

Create the template in your IDE:
```
watsonx-ai template new
```
A list of available templates shows on your screen. Type the number that is associated with the template that you want to work with. Then type the name of the folder to be created.

Navigate to the template directory:

cd <template directory>
cp config.toml.example config.toml

Customize the template code and edit the config.toml file to update placeholder valuesFor easy access to some of the required variables, see the Developer Access page.

Test the template code:

watsonx-ai template invoke "<your query>"

Create a service:
```
watsonx-ai service new
```
When the service is deployed, ibm-watsonx-ai-cli returns the ID of the deployment. If you want this ID to be the default deployment ID when you invoke the deployed service, paste it as deployment_id in the config.toml file. If you don't do this, you must provide the deployment ID each time you invoke your deployed service.

Test the service

watsonx-ai service invoke "<your query>"

Note:

If you want to test your service locally by using a graphical user interface, install the React UI App. For more information, see watsonx.ai AI Service UI app

Example flow for creating an app that is based on an AI service template

To create apps that are based on AI service templates by using ibm-watsonx-ai-cli, refer to this example flow:

Create an app in your IDE:
```
watsonx-ai app new
```
A list of available apps shows on your screen. Type the number that is associated with the app that you want to work with. Then type the name of the folder to be created.
Navigate to the app directory and then copy your environment variable file:
```
cd <created folder with the app>
cp template.env .env
```
Edit the .env file to update placeholder values. For easy access to some of the required variables, see the Developer Access page. For the WATSONX_BASE_DEPLOYMENT_URL, use the URL to the endpoint of a deployed service.
Start the app:
```
watsonx-ai app run
```
Alternatively, if you want to make changes to the source code of the app while the app is running, start the app in development mode:
```
watsonx-ai app run --dev
```
If an app is running in development mode, each time you save your changes the app reloads.

Learn more

For more details, see

Parent topic: Deploying AI services with code

Was the topic helpful?

0/1000