CLI reference

Basic usage

letta [options] [-p "prompt"]

Flag	Description
letta	Resume the default conversation with last-used agent
letta --new	Start a new conversation (for concurrent sessions)
letta --continue, -c	Resume last session exactly (same agent + conversation)
letta --resume, -r	Open conversation selector to browse and resume past sessions
letta --conversation <id>, --conv	Resume a specific conversation by ID
letta --default	Use agent’s default conversation (requires --agent or --name)
letta -n "Name" --default	Use default conversation of agent by name
letta --conv default --agent <id>	Same as above (explicit form)
letta --conv <agent-id>	Shorthand: use default conversation of specified agent
letta --new-agent	Force create a new agent
letta --from-af <path>	Create new agent from an AgentFile (.af)
letta --agent <id>, -a	Use a specific agent by ID
letta --name <name>, -n	Resume agent by name (matches pinned or recent agents)
letta --info	Show project info, skills directory, and pinned agents (without starting session)
letta --help	Show help
letta --version	Show version

Model and configuration

Flag	Description
--model <model>, -m	Specify model (e.g., sonnet-4.5, gpt-5-codex)
--embedding <model>	Specify embedding model for new agents
--system <preset>	Use a system prompt preset (e.g., letta-claude, codex)
--system-custom <text>	Use a custom system prompt string (for new agents)
--system-append <text>	Append text to the resolved system prompt (for new agents)
--toolset <name>	Force toolset: default, codex, or gemini
--skills <path>	Custom skills directory
--sleeptime	Enable sleeptime memory management (only for new agents)

The --model flag can be inconsistent when resuming sessions. Use the /model command instead to change models during an interactive session.

Note: When connecting to an existing agent with --agent <id>, the agent’s existing configuration (model, toolset) is preserved. Use /model or /toolset to change them during the session.

Headless mode

Run Letta Code non-interactively for automation and CI/CD. See Headless mode for detailed usage.

Flag	Description
-p "prompt"	Run a one-off prompt (headless mode)
--output-format <fmt>	Output format: text, json, or stream-json
--input-format <fmt>	Input format: stream-json for bidirectional mode
--yolo	Bypass all permission prompts
--permission-mode <mode>	Set permission mode
--tools "Tool1,Tool2"	Limit available tools
--allowedTools "..."	Allow specific tool patterns
--disallowedTools "..."	Block specific tool patterns
--from-agent <id>	Inject agent-to-agent system reminder (headless mode)

Memory configuration

Configure memory blocks when creating new agents.

Flag	Description
--init-blocks <names>	Comma-separated preset block names (e.g., "persona,project")
--memory-blocks <json>	JSON array of custom memory blocks
--block-value <label>=<value>	Set value for a preset block (can be specified multiple times)
--memfs	Enable Memory Filesystem for new agents (default: enabled)
--no-memfs	Disable Memory Filesystem for new agents

Maintenance

Flag	Description
letta update	Manually check and install updates

Subcommands (JSON-only)

These commands print JSON and are intended for scripting and automation.

Command	Description
letta memfs status --agent <id>	Show memfs status for an agent
letta memfs diff --agent <id>	Show memfs conflicts and metadata-only changes
letta memfs resolve --agent <id> --resolutions '<JSON>'	Resolve memfs conflicts
letta memfs backup --agent <id>	Backup memfs to a timestamped directory
letta memfs backups --agent <id>	List memfs backups
letta memfs restore --agent <id> --from <backup> --force	Restore memfs from a backup (destructive)
letta memfs export --agent <id> --out <dir>	Export an agent’s memfs to a directory
letta agents list [options]	List/search agents
letta messages search --query <text> [options]	Search messages (optionally across all agents)
letta messages list [options]	List messages for an agent
letta blocks list --agent <id>	List blocks for an agent
letta blocks copy --block-id <id> [options]	Copy a block to the current agent
letta blocks attach --block-id <id> [options]	Attach a block to the current agent

See /letta-code/memory for memfs details and /letta-code/skills for how skills use these commands.

Note: For user → agent headless prompts, use letta -p. For agent → agent headless prompts, use letta -p --from-agent <id>.

Environment variables

Variable	Description
LETTA_API_KEY	API key for authentication (get yours at app.letta.com/api-keys)
LETTA_BASE_URL	Base URL for self-hosted Letta server (e.g., http://localhost:8283)
LETTA_DEBUG	Set to 1 to enable debug logging
LETTA_CODE_TELEM	Set to 0 to disable anonymous telemetry
LETTA_PACKAGE_MANAGER	Override detected package manager for auto-updates (npm, bun, or pnpm)
DISABLE_AUTOUPDATER	Set to 1 to disable auto-updates

Set these in your shell profile (~/.bashrc, ~/.zshrc) or .env file:

export LETTA_API_KEY="your-key-here"
export LETTA_BASE_URL="http://localhost:8283"

Keyboard shortcuts

These shortcuts work during interactive sessions.

Shortcut	Description
/	Open command autocomplete
@	Open file autocomplete
!	Enter bash mode (run shell commands directly)
Tab	Autocomplete command or file path
Shift+Enter	Insert newline (multi-line input)
↑ / ↓	Navigate history or menu items
Esc	Cancel dialog or clear input (double press)
Ctrl+C	Interrupt operation or exit (double press)
Ctrl+V	Paste content or image

Bash mode lets you run shell commands directly without involving the agent. Press ! on an empty input line to enter bash mode (prompt changes to !), type your command, and press Enter. Press Backspace on an empty line to exit bash mode.