CLI reference

Essential commands

You’ll likely want to use the following essential commands when using Letta Code:

Command	What it does	Example
letta	Start interactive mode	letta
letta -p "query"	Run a query in headless mode	letta -p "commit the changes and push"
shift-tab	Toggle permission modes	Press Shift+Tab
/init	Run deep memory initialization (or re-init)	> /init
/doctor	Audit and refine memory structure	> /doctor
/remember	Teach your agent something	> /remember always use pnpm
/memory	View your agent’s memory	> /memory
/model	Switch the LLM model	> /model
/login	Sign in to Constellation	> /login
/search	Search past messages	> /search auth bug
/clear	Clear context window (messages buffer)	> /clear
/context-limit	Set or reset the max context window	> /context-limit 200000
/new	Start a new conversation	> /new
/pin	Pin agent for easy access	> /pin
/agents	Swap between agents	> /agents
/feedback	Report issues or give feedback	> /feedback
/title	Configure the terminal window title	> /title
!	Enter bash mode to run a bash command directly	! git status
exit or Ctrl+C	Exit Letta Code	> exit

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 --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 --import <path>	Create new agent from an AgentFile (.af) or registry (@author/name)
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

Backend selection

Letta Code can use either the Letta API backend or the embedded local backend. See Local mode for the full guide.

Flag	Description
--backend api	Use the Letta API backend for Letta Cloud agents and remote access workflows
--backend local	Use the embedded local backend with agent state stored on your machine
--backend <backend>	Overrides the saved first-run backend preference for this invocation

Use letta backend to show the saved default, letta backend api or letta backend local to change it, and letta setup to re-run the interactive setup menu.

Model and configuration

Flag	Description
--model <model>, -m	Specify model (e.g., sonnet, auto, 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)
--toolset <name>	Force toolset: default, codex, or gemini
--skills <path>	Custom skills directory
--skill-sources <csv>	Skill sources: all,bundled,global,agent,project
--no-skills	Disable all skill sources
--no-bundled-skills	Disable bundled skills only
--no-system-info-reminder	Disable first-turn environment reminder (device/git/cwd context)
--reflection-trigger <mode>	Sleeptime trigger: off, step-count, compaction-event
--reflection-behavior <mode>	Deprecated - accepted for compatibility but ignored
--reflection-step-count <n>	Sleeptime step-count interval (positive integer)

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.

To resume your usual working thread, just run letta. For parallel work, use --new. To reopen a specific thread, use --conversation <id> or --resume in interactive mode.

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
--include-partial-messages	Emit stream_event wrappers for each chunk (stream-json only)
--yolo	Set permission mode to unrestricted
--permission-mode <mode>	Set permission mode: unrestricted, standard, acceptEdits, memory
--disable-memory-guard	Disable the cross-agent memory guard for this parent process
--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)
--tags <csv>	Comma-separated tags for agent organization (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")
--base-tools <names>	Comma-separated base tools to attach when using --new-agent
--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 this agent
--no-memfs	Disable Memory Filesystem for this agent

Maintenance

Flag	Description
letta update	Manually check and install updates
letta server [options]	Register this environment as a cloud listener
letta remote [options]	Alias for letta server
letta connect <provider> [options]	Connect provider auth from CLI (same provider flow as /connect)

Scheduling

Use letta cron to register one-time or recurring prompts for an agent. Tasks are stored locally and fire while letta server is connected. See Scheduling for the full guide.

This is a server-mode feature, not a replacement for shell cron or the Letta API schedules feature.

Command	Description
letta cron add --name <name> --description <text> --prompt <text> --every <interval> [options]	Create a recurring task from an interval like 5m, 2h, or 1d
letta cron add --name <name> --description <text> --prompt <text> --at <time> [options]	Create a one-time task for a time like "3:00pm" or "in 45m"
letta cron add --name <name> --description <text> --prompt <text> --cron "<expr>" [options]	Create a recurring task from a raw 5-field cron expression
letta cron list [--agent <id>] [--conversation <id>]	List tasks, optionally filtered by agent or conversation
letta cron get <id>	Show task details
letta cron delete <id>	Delete one task
letta cron delete --all --agent <id>	Delete all tasks for an agent

--agent defaults to LETTA_AGENT_ID when available. --conversation defaults to LETTA_CONVERSATION_ID or default.

Recurring tasks remain active until explicitly deleted. --every 1d fires daily at local midnight, so use --cron for a fixed time of day.

Subcommands (JSON-only)

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

Command	Description
letta memory status --agent <id>	Show memory repository status for an agent
letta memory diff --agent <id>	Show memory conflicts and metadata-only changes
letta memory pull --agent <id>	Pull the latest memory repository state
letta memory backup --agent <id>	Back up memory to a timestamped directory
letta memory backups --agent <id>	List memory backups
letta memory restore --agent <id> --from <backup> --force	Restore memory from a backup (destructive)
letta memory export --agent <id> --out <dir>	Export an agent’s memory filesystem to a directory
letta memory tokens [--agent <id>] [--memory-dir <path>]	Estimate token usage for the always-loaded system/ memory directory
letta agents create [options]	Create a memfs-enabled agent
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 Memory and MemFS for memory details, and Skills for how skills use these commands. The legacy letta memfs subcommand remains an alias for letta memory.

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_LOCAL_BACKEND_DIR	Storage directory for the embedded local backend. Defaults to ~/.letta/lc-local-backend
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
MEMORY_DIR	Absolute path to the agent’s memory directory (set automatically in shell tools)
AGENT_ID	Current agent ID (set automatically in shell tools)
CONVERSATION_ID	Current conversation ID (set automatically in shell tools)

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
Ctrl+D	Hold or release queued messages while the agent is working

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.