Use Llamactl A Cli Tool For Llamaagents

Use llamactl - a CLI tool for LlamaAgents

llamactl is a CLI tool for developing and deploying LlamaIndex workflows as LlamaAgents. It provides commands to initialize projects, run local development servers, and manage cloud deployments.

Prerequisites

Before using llamactl, ensure you have:

• `uv` - Python package manager and build tool
• Node.js - Required for UI development (supports npm, pnpm, or yarn)
• llama-index-workflows and llamactl installed in your environment

Installation

Install llamactl globally using uv:

uv tool install -U llamactl
llamactl --help

Or try it without installing:

uvx llamactl --help

Initialize a Project

Create a new LlamaAgents project with starter templates:

llamactl init

This creates a Python module with LlamaIndex workflows and an optional UI frontend. Configuration is managed in pyproject.toml, where you define workflow instances, environment settings, and UI build options.

Local Development

Start the local development server:

llamactl serve

This command:

1. Installs dependencies 2. Serves workflows as an API (configured in pyproject.toml) 3. Starts the frontend development server

The server automatically detects file changes and can resume in-progress workflows.

Deploy to LlamaCloud

Push your code to a git repository:

git remote add origin https://github.com/org/repo
git add -A
git commit -m 'Set up new app'
git push -u origin main

Create a cloud deployment:

llamactl deployments create

This opens an interactive Terminal UI to configure:

• Deployment name
• Git repository (supports private GitHub repos via the LlamaDeploy GitHub app)
• Git branch/tag/commit
• Environment secrets

Manage Deployments

• View deployment status: llamactl deployments get
• Update secrets or branch: llamactl deployments edit
• Deploy new version: llamactl deployments update

For detailed configuration options, see the Deployment Config Reference.

llamactl reference

auth-env

Manage environments (distinct control plane API URLs). Environments determine which profiles are shown and where auth/project actions apply.

Usage

llamactl auth env [COMMAND] [options]

Commands:

• list: List known environments and mark the current one
• add <API_URL> [--interactive/--no-interactive]: Probe the server and upsert the environment
• switch [API_URL] [--interactive/--no-interactive]: Select the current environment (prompts if omitted)
• delete [API_URL] [--interactive/--no-interactive]: Remove an environment and its associated profiles

Notes:

• Probing reads requires_auth and min_llamactl_version from the server version endpoint.
• Switching environment filters profiles shown by llamactl auth list and used by other commands.

Commands

List

llamactl auth env list

Shows a table of environments with API URL, whether auth is required, and the current marker.

Add

llamactl auth env add <API_URL>

Probes the server at <API_URL> and stores discovered settings. Interactive mode can prompt for the URL.

Switch

llamactl auth env switch [API_URL]

Sets the current environment. If omitted in interactive mode, you’ll be prompted to select one.

Delete

llamactl auth env delete [API_URL]

Deletes an environment and all associated profiles. If the deleted environment was current, the current environment is reset to the default.

See also

• Profiles and tokens: `llamactl auth`
• Getting started: Introduction
• Deployments: `llamactl deployments`

auth

Authenticate and manage profiles for the current environment. Profiles store your control plane API URL, project, and optional API key.

Usage

llamactl auth [COMMAND] [options]

Commands:

• token [--project-id ID] [--api-key KEY] [--interactive/--no-interactive]: Create profile from API key; validates token and selects a project
• login: Login via web browser (OIDC device flow) and create a profile
• list: List login profiles in the current environment
• switch [NAME] [--interactive/--no-interactive]: Set currently logged in user/token
• logout [NAME] [--interactive/--no-interactive]: Delete a login and its local data
• project [PROJECT_ID] [--interactive/--no-interactive]: Change the active project for the current profile

Notes:

• Profiles are filtered by the current environment (llamactl auth env switch).
• Non-interactive token requires both --api-key and --project-id.

Commands

Token

llamactl auth token [--project-id ID] [--api-key KEY] [--interactive/--no-interactive]

• Interactive: Prompts for API key (masked), validates it by listing projects, then lets you choose a project. Creates an auto‑named profile and sets it current.
• Non‑interactive: Requires both --api-key and --project-id.

Login

llamactl auth login

Login via your browser using the OIDC device flow, select a project, and create a login profile set as current.

List

llamactl auth list

Shows a table of profiles for the current environment with name and active project. The current profile is marked with *.

Switch

llamactl auth switch [NAME] [--interactive/--no-interactive]

Set the current profile. If NAME is omitted in interactive mode, you will be prompted to select one.

Logout

llamactl auth logout [NAME] [--interactive/--no-interactive]

Delete a profile. If the deleted profile is current, the current selection is cleared.

Project

llamactl auth project [PROJECT_ID] [--interactive/--no-interactive]

Change the active project for the current profile. In interactive mode, select from server projects. In environments that don't require auth, you can also enter a project ID.

See also

• Environments: `llamactl auth env`
• Getting started: Introduction
• Deployments: `llamactl deployments`

deployments

Deploy your app to the cloud and manage existing deployments. These commands operate on the project configured in your profile.

Usage

llamactl deployments [COMMAND] [options]

Commands:

• list: List deployments for the configured project
• get [DEPLOYMENT_ID] [--non-interactive]: Show details; opens a live monitor unless --non-interactive
• create: Interactively create a new deployment
• edit [DEPLOYMENT_ID]: Interactively edit a deployment
• delete [DEPLOYMENT_ID] [--confirm]: Delete a deployment; --confirm skips the prompt
• update [DEPLOYMENT_ID]: Pull latest code from the configured branch and redeploy

Notes:

• If DEPLOYMENT_ID is omitted, you’ll be prompted to select one.
• All commands accept global options (profile, host, etc.).

Commands

List

llamactl deployments list

Shows a table of deployments with name, id, status, repo, deployment file, git ref, and secrets summary.

Get

llamactl deployments get [DEPLOYMENT_ID] [--non-interactive]

• Default behavior opens a live monitor with status and streaming logs.
• Use --non-interactive to print details to the console instead of opening the monitor.

Create (interactive)

llamactl deployments create

Starts an interactive flow to create a deployment. You can provide values like repository, branch, deployment file path, and secrets. (Flags such as --repo-url, --name, --deployment-file-path, --git-ref, --personal-access-token exist but creation is currently interactive.)

Edit (interactive)

llamactl deployments edit [DEPLOYMENT_ID]

Opens an interactive form to update deployment settings.

Delete

llamactl deployments delete [DEPLOYMENT_ID] [--confirm]

Deletes a deployment. Without --confirm, you’ll be asked to confirm.

Update

llamactl deployments update [DEPLOYMENT_ID]

Refreshes the deployment to the latest commit on the configured branch and shows the resulting Git SHA change.

See also

• Getting started: Introduction
• Configure names, env, and UI: Deployment Config Reference
• Local dev server: `llamactl serve`

init

Create a new app from a starter template, or update an existing app to the latest template version.

Usage

llamactl init [--template <id>] [--dir <path>] [--force]
llamactl init --update

Templates

• basic-ui: A basic starter workflow with a React Vite UI
• extraction-review: Extraction Agent with Review UI (Llama Cloud integration; review/correct extracted results)

If omitted, you will be prompted to choose interactively.

Options

• --update: Update the current app to the latest template version. Ignores other options.
• --template <id>: Template to use (basic-ui, extraction-review).
• --dir <path>: Directory to create the new app in. Defaults to the template name.
• --force: Overwrite the directory if it already exists.

What it does

• Copies the selected template into the target directory using `copier`
• Adds assistant docs: AGENTS.md and symlinks CLAUDE.md/GEMINI.md
• initializes a Git repository if git is available
• Prints next steps to run locally and deploy

Examples

• Interactive flow:

llamactl init

• Non‑interactive creation:

llamactl init --template basic-ui --dir my-app

• Overwrite an existing directory:

llamactl init --template basic-ui --dir ./basic-ui --force

• Update an existing app to the latest template:

llamactl init --update

See also: Getting Started guide.

serve

Serve your app locally for development and testing. Reads configuration from your project (e.g., pyproject.toml or llama_deploy.yaml) and starts the Python API server, optionally proxying your UI in dev.

See also: Deployment Config Reference and UI build and dev integration.

Usage

llamactl serve [DEPLOYMENT_FILE] [options]

• DEPLOYMENT_FILE defaults to . (current directory). Provide a path to a specific deployment file or directory if needed.

Options

• --no-install: Skip installing Python and JS dependencies
• --no-reload: Disable API server auto‑reload on code changes
• --no-open-browser: Do not open the browser automatically
• --preview: Build the UI to static files and serve them (production‑like)
• --port <int>: Port for the API server
• --ui-port <int>: Port for the UI proxy in dev

Behavior

• Prepares the server environment (installs dependencies unless --no-install)
• In dev mode (default), proxies your UI dev server and reloads on change
• In preview mode, builds the UI to static files and serves them without a proxy