Skip to content
My Docs My Docs Letta Docs
Sign up
Development tools
Community tools
lettactl

lettactl

Use a community-built CLI to manage Letta agents with declarative YAML and git-friendly workflows.

lettactl is a CLI that brings kubectl-style declarative management to Letta agents. It’s designed for deploying and managing fleets of agents at scale—whether you’re orchestrating dozens of specialized agents across environments or maintaining a single agent with version-controlled configuration.

You define agents in YAML, keep those files in git, and apply changes to your Letta project from the command line. This enables infrastructure-as-code practices for your AI agent deployments: reproducible builds, code-reviewed changes, and consistent rollouts across dev, staging, and production.

Installation

Section titled “Installation”
Terminal window
npm install -g lettactl

Quick Start

Section titled “Quick Start”

1. Create a configuration file

Section titled “1. Create a configuration file”

Create a file named letta.yaml that defines your agent fleet:

agents:
  # Customer-facing support agent
  - name: support-agent
    model: gpt-4o
    memory_blocks:
      - label: persona
        file: ./blocks/support-persona.md
      - label: guidelines
        file: ./blocks/support-guidelines.md
    tools:
      - web_search
      - send_email


  # Internal sales assistant agent
  - name: sales-agent
    model: gpt-4o
    memory_blocks:
      - label: persona
        file: ./blocks/sales-persona.md
      - label: product_catalog
        file: ./blocks/product-catalog.md
      - label: pricing
        file: ./blocks/pricing-tiers.md
    tools:
      - web_search
      - schedule_meeting
      - lookup_crm

2. Apply the configuration

Section titled “2. Apply the configuration”

Deploy your entire agent fleet with a single command:

Terminal window
lettactl apply -f letta.yaml

lettactl will create or update all agent definitions in Letta based on the contents of the YAML file and any referenced memory block files. It intelligently diffs your local configuration against the remote state, applying only what has changed.

Fleet Deployment Model

Section titled “Fleet Deployment Model”

lettactl treats your agents as a fleet—a collection of agents that are deployed, versioned, and managed together. This model provides several advantages:

CapabilityDescription
Atomic deploymentsApply changes to multiple agents in a single operation
Shared memory blocksPoint multiple agents at the same source file for consistent behavior
Environment promotionUse the same YAML across dev → staging → prod with environment-specific overrides
Rollback supportRevert to any previous git commit to restore agent configurations
Audit trailEvery change to your agent fleet is tracked in version control

Key Features

Section titled “Key Features”
  • Declarative configuration — Define your entire agent fleet in YAML files
  • Automatic diffing — Only applies changes to memory blocks and agent definitions that have actually changed
  • Shared memory blocks — Multiple agents can reference the same source file for consistent personas, guidelines, or knowledge
  • Git-friendly — Agent definitions live in your repository for code review, history, and collaboration
  • Fleet-scale operations — Manage tens or hundreds of agents with the same tooling

Common Use Cases

Section titled “Common Use Cases”

CI/CD Pipelines for Agent Deployment

Section titled “CI/CD Pipelines for Agent Deployment”

Integrate lettactl into your deployment pipeline to automatically apply agent changes when PRs are merged:

# Example GitHub Actions workflow
- name: Deploy agent fleet
  run: lettactl apply -f letta.yaml
  env:
    LETTA_API_KEY: ${{ secrets.LETTA_API_KEY }}

Managing Agent Fleets Across Environments

Section titled “Managing Agent Fleets Across Environments”

Maintain environment-specific configurations while sharing common definitions:

agents/
├── base.yaml           # Shared agent definitions
├── dev.yaml            # Dev-specific overrides
├── staging.yaml        # Staging configuration
└── prod.yaml           # Production configuration

Team Collaboration

Section titled “Team Collaboration”

Enable your team to collaborate on agent behavior through familiar git workflows:

  • Create branches for experimental persona changes
  • Review memory block updates through pull requests
  • Track who changed what and when through commit history

Resources

Section titled “Resources”