AI CLI Usage

Once the AI CLI is installed, you're ready to take advantage of its powerful features for managing AI clusters and jobs.

Securely Logging into the AI Server

ai login

Initiates authentication to an AI server. This command will prompt you to enter the server's address and proceed with the server-specific login procedure. Once authenticated, your credentials are securely stored for future interactions.

The login command will request you to enter your CodeDepot username, email, and password. Ensure you have created an account on our web app (opens in a new tab) prior to logging in.

Successful authentication results in storing server details and user credentials in ~/.ai/config.json for subsequent server interactions.

Important Note: User authentication is a prerequisite for executing additional AI commands.

Managing your Cloud Provider

Configuring your Cloud Provider

Important Note: We currently only support Lambda (opens in a new tab) for cloud services. If you need integration with a different cloud provider, please reach out to us at

Step 1: Create a .yaml and a .json file for the cloud provider at the root of your project.

The .yaml file for the cloud provider must contain the following fields:

  • name: The cloud provider name for future reference.
  • provider_type: The type of the cloud provider. As of now, we only support lambda as a cloud provider.
  • credentials: The path to the credentials file for the cloud provider.

Example of a [provider-yaml] file for the Lambda cloud provider:

name: lambda-provider
provider_type: lambda
credentials: lambda-creds.json

The .json file will be the configuration file containing a token, which needs to be a valid Lambda API Key. To generate a Lambda token, please refer to: Lambda API Key Generation (opens in a new tab)

The lambda-creds.json file must contain the following fields:

  • token: The Lambda API Key.

Example of a lambda-creds.json file:

  "token": "your-lambda-api-key"

Step 2: Open your terminal and run:

ai provider create [provider-yaml]

Creates a new cloud provider using the configuration details provided in the [provider-yaml] file. This process stores the provider credentials on the AI server.

To verify the validity of the credentials you provided, run the ai provider list command.

Listing Available Cloud Providers

ai provider list

Lists all accessible cloud providers along with details such as the provider's name, type, and credential status.

Managing the Cluster

Creating a Cluster

Step 1: Create a cluster .yaml file at the root of your project.

The .yaml file for the cluster must contain the following fields:

  • name: The cluster name for future reference.
  • provider: The cloud provider to use. This must match the name specified in the name field of the .yaml when creating the cloud provider.
  • nodes: A list of the IP addresses for the nodes in the cluster. You can retrieve these IP addresses from the cloud provider's dashboard.
  • key_file: The path to the private key file to use to connect to the nodes in the cluster.

Example of a [cluster-yaml] file for a Lambda cluster:

name: lambda-cluster
provider: lambda-provider
key_file: key.pem

Step 2: Open your terminal and run:

ai cluster create [cluster-yaml]

Creates a cluster using the configuration details provided in the [cluster-yaml] file, which includes specifications such as the number and addresses of nodes and the cloud/cloud manager in use.

Successfully created clusters have their information stored on the AI server, enabling command executions within the cluster. To check for the cluster's status, you can use the ai cluster list command.

Listing Clusters

ai cluster list

Lists all clusters along with their active status.

Managing Jobs on the Cluster

Creating a Job

Create a .jobfile.yaml file at the root of your project.

The .jobfile.yaml file must contain the following fields:

  • name: The job name for future reference.
  • command: The command to run on the cluster. This command must be a list of strings, where the first element is the command to run and the rest of the elements are the arguments to the command.

Example of a .jobfile.yaml file that runs the command python on the cluster:

name: model-training
command: ["python", ""]

Starting a Job

Open your terminal and run:

ai job run [cluster-name]

Starts a job on the designated cluster, guided by the instructions inside the repositories's .jobfile.yaml file.

It clones the current repository on the current commit onto the cluster, and then starts the job with a command defined by the user.

Before you run the command:

  • Prepare Repository:

    Ensure your local repository is up to date and committed as this command will clone the current commit to the cluster.

After you run the command:

  • SSH Key Verification:

    • If your repository is hosted on CodeDepot: The command checks if the cluster has a valid CodeDepot SSH key. If not, it will automatically generate and register a new SSH key for you.
    • If your repository is not on CodeDepot: Ensure that an SSH key, known to work with your repository, exists. If no valid SSH key is found, you will be prompted to add one to continue.
  • Monitor your job:

    • Check Job Status: Use ai job list to view the current status of all jobs.
    • View Job Logs: Use ai job log [job-name] to access logs of a specific job.

Listing Active Jobs

ai job list

Provides a list of all active jobs on the cluster that the current user has the permissions to view, giving a snapshot of the cluster's operational status.

Monitoring Jobs

ai job log [job-name]

Returns the output of the job's stdout, as well as information related to [ai]'s internal runner.

Terminating Jobs and Cleaning Resources

ai job stop [job-name]

Stops all processes and eliminates all volumes associated with [job-name] on the cluster, ensuring a clean and orderly environment post-job execution.

Managing Remote SSH Keys

Adding an SSH Key

ai key create [name] [path]

Creates an SSH key on the AI server with the name [name], using the private and public keys located at path and, respectively. Both keys are stored on the AI server. The keys used must not be protected by a password.

Deleting an SSH Key

ai key delete [name]

Removes the key with name [name] from the AI server. After this operation is completed, the AI server will not be able to use this key to clone repositories.

Listing SSH Keys

ai key list

Lists all SSH keys stored on the AI server, indicating which keys were ai-managed (automatically created) and which were created by the user.

Updating AI-managed Keys

ai key refresh_managed

Creates or recreates the AI-managed SSH key used to access CodeDepot repositories. This command is useful if the user has removed the AI-managed SSH key from their account on the CodeDepot website.