lettactl

Manage Letta AI agent fleets declaratively with kubectl-style CLI. Use when creating, updating, or managing multiple Letta agents with shared configurations, memory blocks, tools, and folders.

⭐20stars🔀1forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

lettactl is a powerful, kubectl-style CLI and SDK designed for the declarative management of Letta AI agent fleets. It enables developers to define, deploy, and scale multiple AI agents using YAML configurations, ensuring consistency across shared memory blocks, tools, and system prompts. By treating AI agents as managed infrastructure, it simplifies complex workflows such as bulk updates, template application, and programmatic fleet orchestration, making it an essential tool for building production-grade agentic systems.

Use Cases

  • Declarative Fleet Deployment: Define your entire AI agent infrastructure in a single fleet.yaml file and deploy it with a single command to ensure reproducible environments.
  • Bulk Configuration Management: Update system prompts, LLM settings, or tool access across multiple agents simultaneously using pattern-matching templates and three-way merge logic.
  • Automated Memory Orchestration: Programmatically manage and attach shared memory blocks to multiple agents to provide a unified context or company-wide knowledge base.
  • CI/CD for AI Agents: Integrate the lettactl CLI or TypeScript SDK into DevOps pipelines to automate the lifecycle of AI agents from development to production.
  • Fleet Observability: Use the CLI to monitor agent health, inspect context window usage, and manage message history across large-scale deployments.
namelettactl
descriptionManage Letta AI agent fleets declaratively with kubectl-style CLI. Use when creating, updating, or managing multiple Letta agents with shared configurations, memory blocks, tools, and folders.
licenseMIT

lettactl

kubectl-style CLI for managing Letta AI agent fleets declaratively.

When to Use

  • Deploying multiple agents with shared configurations
  • Managing agent memory blocks, tools, and folders
  • Applying templates to existing agents
  • Programmatic fleet management via SDK

Core Workflow

  1. Define agents in fleet.yaml
  2. Apply with lettactl apply -f fleet.yaml
  3. Verify with lettactl get agents and lettactl describe agent <name>

Fleet YAML Structure

shared_blocks:
  - name: company-context
    description: Shared company knowledge
    limit: 5000
    from_file: ./context/company.md

agents:
  - name: support-agent
    description: Customer support assistant
    system_prompt:
      from_file: ./prompts/support.md
    llm_config:
      model: gpt-4o
      context_window: 128000
    memory_blocks:
      - name: persona
        description: Agent personality
        limit: 2000
        value: "You are a helpful support agent."
    shared_blocks:
      - company-context
    tools:
      - send_email
      - search_docs

See reference/fleet-config.md for full schema.

CLI Commands

Apply Configuration

lettactl apply -f fleet.yaml              # Create/update agents
lettactl apply -f fleet.yaml --dry-run    # Preview changes
lettactl apply -f fleet.yaml --match "*-draper"  # Template mode

Inspect Resources

lettactl get agents                    # List all agents
lettactl get agents -o wide            # With details
lettactl get blocks --shared           # Shared blocks only
lettactl get tools --orphaned          # Unused tools
lettactl describe agent <name>         # Full agent details

Messaging

lettactl send <agent> "Hello"          # Send message
lettactl send <agent> "Hi" --stream    # Stream response
lettactl messages list <agent>         # View history
lettactl messages reset <agent>        # Clear history

Observability

lettactl health                        # Server connectivity
lettactl files <agent>                 # Attached files
lettactl context <agent>               # Context window usage

See reference/cli-commands.md for all options.

Template Mode

Apply configuration to existing agents matching a pattern:

lettactl apply -f template.yaml --match "*-draper"

Uses three-way merge: preserves user-added resources while updating managed ones. See reference/template-mode.md.

SDK Usage

import { LettaCtl } from 'lettactl';

const ctl = new LettaCtl({ lettaBaseUrl: 'http://localhost:8283' });

await ctl.deployFromYaml('./fleet.yaml');
await ctl.deployFromYaml('./template.yaml', { match: '*-prod' });

See reference/sdk-usage.md for full API and reference/cli-commands.md for environment variables.