Skip to main content

CLI Reference

This reference provides detailed information about the Agenta Command Line Interface (CLI), including commands, options, and usage.

agenta init​

Initializes a new Agenta project.

Synopsis​

agenta init [OPTIONS]

Description​

The agenta init command initializes a new Agenta project. It prompts the user for the application name and allows selection of the Agenta platform host (local, cloud, or remote). This command creates a blank project in the backend and generates a project.toml configuration file in the current directory.

Options​

  • --app-name NAME
    Specifies the application name directly, bypassing the prompt.

  • --backend-host URL
    Specifies the Agenta backend host URL.

  • --help
    Displays help information for the command.

Behavior​

  • Creates a project.toml file containing project configuration.
  • If options are not provided, prompts the user for necessary information.

Prompts​

  1. Project Name

    ? Please enter the app name:

  2. Agenta Host Selection

    ? Where are you running Agenta? (Use arrow keys)
      ▸ On Agenta Cloud
        On my local machine
        On a remote machine

    Depending on the selection:

    • On Agenta Cloud: Prompts for API key (retrievable from Agenta Cloud Settings).
    • On a remote machine: Prompts for the remote machine URL.

Example​

Initialize a new app named test-app for Agenta Cloud:

agenta init --app-name test-app --backend-host https://cloud.agenta.ai/

agenta variant list​

Lists all variants of an application.

Synopsis​

agenta variant list

Description​

Displays all the variants associated with your application currently available in the backend.

Requirements​

  • Must be executed in a directory containing the project.toml file generated by agenta init.

Behavior​

  • Reads project configuration from project.toml.
  • Retrieves and lists all variants for the application.

Example​

List all variants:

agenta variant list

agenta variant remove​

Removes a variant from an application.

Synopsis​

agenta variant remove

Description​

Removes a specified variant from your application or project. The command lists all existing variants and prompts you to select one for removal.

Requirements​

  • Must be executed in a directory containing the project.toml file generated by agenta init.

Behavior​

  • Lists all variants associated with the application.
  • Prompts the user to select a variant to remove.
  • Deletes the selected variant from the backend.

Example​

Remove a variant:

agenta variant remove

Follow the on-screen prompts to select the variant to remove.

agenta variant serve​

Deploys an application variant to the Agenta platform.

Synopsis​

agenta variant serve [OPTIONS] FILE_NAME

Description​

The agenta variant serve command packages and deploys your application code to the Agenta platform. It processes the specified Python file along with any additional files in the same directory. Once deployed, the variant becomes accessible in the web UI and can be further deployed to staging or production environments as an API endpoint.

Options​

  • --file_name FILE_NAME
    Specifies the Python file containing the variant code.

  • --overwrite
    Overwrites the existing variant if it already exists.

  • --help
    Displays help information for the command.

Requirements​

  • Must be executed in a directory containing the project.toml file generated by agenta init.

Behavior​

  • Builds a Docker image from the specified Python file.
  • Deploys the variant to the Agenta backend.
  • The variant is initially named app_name.default, where app_name is derived from the Python file name.
  • Additional configurations can create new variants named app_name.someconfig.

Examples​

Deploy a variant from myapp.py:

agenta variant serve myapp.py

Overwrite an existing variant:

agenta variant serve --file_name myapp.py --overwrite