Letta Code SDK

Appearance

Headless Mode ​

Fresh

Source: Letta Code Headless

Overview ​

Headless mode enables non-interactive execution suitable for scripting, CI/CD integration, and UNIX tool composition.

Basic Usage ​

One-Shot Query ​

bash
letta -p "Look around this repo and write a README.md documenting it"

Piped Input ​

bash
echo "Explain this error" | letta -p

Output Formats ​

Text (Default) ​

Plain text agent responses:

bash
letta -p "What is the main entry point?"

JSON ​

Structured output with metadata:

bash
letta -p "What is the main entry point?" --output-format json | jq '.result'

JSON output includes: agent ID, conversation ID, and token usage statistics.

Stream JSON ​

Line-delimited JSON events for real-time streaming and timeout prevention:

bash
letta -p "Explain the architecture" --output-format stream-json

Each message includes otid (output turn ID) and incrementing seq_id for token-level tracking.

Bidirectional Mode ​

Enable full programmatic control via JSON on stdin/stdout:

bash
letta --input-format stream-json --output-format stream-json

Input Message Types ​

TypeDescription
User messageSend with role and content
Control requestInitialize, interrupt, etc.

Output Message Types ​

TypeDescription
System initializationSetup events
Control responsesReplies to control requests
Permission requestsTool usage approval
Streaming messagesIncremental output
ResultsFinal turn results

Interactive Tool Behavior ​

ModeAskUserQuestionEnterPlanModeExitPlanMode
One-shot (-p)ExcludedProceedsRequires approval
Bidirectionalcontrol_requestcontrol_requestcontrol_request

Agent Management ​

bash
# Use last agent, default conversation
letta -p "query"

# New conversation
letta -p "query" --new

# New agent
letta -p "query" --new-agent

# Specific agent
letta -p "query" --agent agent-123

# Specific conversation
letta -p "query" --conversation conv-456

# Resume by name
letta -p "query" -n "my-agent"

Configuration Options ​

Model Selection ​

bash
letta -p "query" --model sonnet
letta -p "query" --model auto
letta -p "query" -m gpt-5-codex

Embedding Model ​

bash
letta -p "query" --embedding letta/letta-free

Note

Embedding model can only be set when creating a new agent.

Permission Control ​

bash
# Bypass all prompts (except ExitPlanMode)
letta -p "Fix all lint errors" --yolo

# Restrict available tools
letta -p "Review code" --tools "Read,Glob,Grep"

# Set permission mode
letta -p "Refactor" --permission-mode acceptEdits
letta -p "Plan migration" --permission-mode plan

System Prompt ​

bash
# Use preset
letta -p "query" --system letta-claude

# Custom prompt
letta -p "query" --system-custom "You are a security auditor."

Memory Blocks ​

bash
letta -p "query" --init-blocks "persona,project" \
  --block-value "persona=Security specialist" \
  --block-value "project=E-commerce platform"

Advanced Features ​

Token-Level Streaming ​

bash
letta -p "Explain" --include-partial-messages --output-format stream-json

Wraps chunks in stream_event objects for real-time display.

Toolset Override ​

bash
letta -p "query" --toolset codex
letta -p "query" --toolset gemini
letta -p "query" --toolset default

AgentFile Import ​

bash
letta -p "query" --import ./my-agent.af
letta -p "query" --import @author/agent-name

Usage Examples ​

Automated Linting ​

bash
letta -p "Run the linter and fix any errors" --yolo

Structured Output for Scripts ​

bash
letta -p "What is the main entry point?" --output-format json | jq '.result'

Read-Only Analysis ​

bash
letta -p "Review for security issues" --tools "Read,Glob,Grep"

Cron Scheduling ​

bash
# Daily code review
0 9 * * 1-5 letta -p "Review yesterday's commits" --output-format json >> /var/log/reviews.json

# Weekly dependency check
0 10 * * 1 letta -p "Check for outdated dependencies" --yolo

Verification Checklist ​

  • [ ] letta -p "test" returns a response
  • [ ] JSON output parses correctly
  • [ ] Stream JSON delivers incremental events
  • [ ] --tools flag restricts available tools
  • [ ] --yolo bypasses interactive prompts
  • [ ] Agent/conversation selection works as expected

See Also ​