lash guide

using/cli

The lash binary is shipped by the lash-cli crate. It runs an interactive terminal UI by default, an autonomous single-shot mode under --print, and a handful of administrative flows like --export and --reset. This page enumerates the user-visible surface: flags, slash commands, key bindings, the setup wizard, the config file, and the environment variables it reads.

First Run

If ~/.lash/config.json does not exist, lash launches the setup wizard. The wizard provisions an active provider, collects credentials, and writes the config file before dropping you into the TUI.

$ lash
# Setup wizard:
# 1. Choose a provider (Anthropic, OpenAI, OpenAI-compatible, Codex, Google OAuth)
# 2. Paste API key (or run OAuth / device-code flow)
# 3. Optionally paste a Tavily API key for the built-in web-search tool
# 4. Drop into the interactive TUI

Re-run the wizard at any time with lash --provider. Use /provider from inside a session to switch providers without restarting.

Slash Commands

Type a / at the start of the prompt to invoke a command. Tab-completion is available. Skill names registered in ~/.lash/skills/ or .agents/lash/skills/ appear as additional /<skill> commands.

Command	Aliases	Usage	Description
`/clear`	`/new`	`/clear`	Reset conversation
`/compact`	—	`/compact [focus instructions]`	Summarize older messages to free up context
`/controls`	—	`/controls`	Show keyboard shortcuts
`/fork`	—	`/fork`	Open a forked session in a new terminal
`/tree`	—	`/tree`	Browse and switch branches in the current session
`/version`	—	`/version`	Show `lash-cli` and `lash-sansio` versions
`/info`	—	`/info`	Show current session/runtime info
`/model`	—	`/model [name]`	Show or switch the LLM model
`/variant`	—	`/variant [name]`	Show or switch the model variant (e.g. `high`, `max`)
`/mode`	—	`/mode [name]`	Show or switch execution mode (`standard` / `rlm`)
`/provider`	`/login`	`/provider`	Switch, add, or re-authenticate providers
`/logout`	—	`/logout`	Remove stored credentials for active provider
`/retry`	—	`/retry`	Replay the previous turn payload
`/resume`	`/continue`	`/resume [name]`	Browse or load a previous session (interactive picker if no arg)
`/skills`	—	`/skills`	Browse loaded skills
`/tools`	—	`/tools ...`	Inspect or edit the tool registry
`/reconfigure`	—	`/reconfigure ...`	Apply or inspect pending runtime reconfigure
`/help`	`/?`	`/help`	Show commands and shortcuts
`/exit`	`/quit`	`/exit`	Quit

Keyboard Shortcuts

The TUI uses a small, consistent set of shortcuts. The full list is also available in-session via /controls.

History navigation

Ctrl+U / Ctrl+D: Scroll history up / down half a page.
PageUp / PageDown: Scroll history a full page.
↑ / ↓: Single-line scroll when not editing the prompt.

Prompt editing

Enter: Submit the prompt, or pick from a picker.
Tab: Accept an autocomplete suggestion or toggle a multi-select option.
Ctrl+← / Ctrl+→: Move the cursor by word.
Home / End: Jump to the start / end of the prompt.

Selection & clipboard

Ctrl+C: Copy the current selection (or the last assistant response if no selection). Configure via LASH_COPY_BINDING if the default conflicts with your terminal.
Esc: Close pickers and cancel modal flows.
Ctrl+C (idle): Quit lash when no selection is active.

Pickers & multi-select

↑ / ↓ or k / j: Move selection.
Space: Toggle a multi-select option when supported.
Tab / BackTab: Add / remove a note on a selection when supported.

CLI Flags

Run lash --help for the full list. The most common flags, grouped by purpose:

Provider & model

--provider: Re-run the provider setup wizard.
--model <name>: Override the default model for this session.
--variant <name>: Override the provider-native model variant (e.g. high, max, xhigh).
--api-key <key>: One-shot API key for OpenAI or OpenAI-compatible providers.
--base-url <url>: Base URL for the LLM API (OpenAI-compatible).
--tavily-api-key <key> (env TAVILY_API_KEY): Tavily key for the bundled web-search tool.

Execution

-em, --execution-mode <mode>: standard (default) or rlm.
-c, --context-approach <approach>: For standard mode: rolling_history or observational_memory.
--rlm-var name=<json>: Repeatable. Project a read-only bound variable into the RLM autonomous turn.
--rlm-vars-file <path>: Same as above but load the projections from a JSON object file.

Session

--resume <id_or_name>: Resume by session id, name, or legacy .db filename.
--resume-prompt <prompt>: Queue and send a prompt right after resume.

Output modes

-p, --print <prompt>: Autonomous: run the prompt once, write the answer to stdout, exit. See Print mode below.
--await-background-work: In autonomous mode, wait for plugin background work before exiting.
--turn-usage-json <path>: In autonomous mode, write per-turn and cumulative usage JSON to a file.

Debug & tracing

--debug: Detailed lifecycle/debug logs plus per-session LLM traces.
--trace-level <standard|extended>: Trace detail. Default standard.
--debug-ui-trace trace.json: Record the live TUI session as a replayable UI trace plus a final snapshot.

Admin

--reset: Delete ~/.lash/ and ~/.cache/lash/ and exit.
--info: Print current config / runtime info and exit.
--check-update / --update: Check / install the latest release.
--export <db>: Export a persisted session database. Combine with --export-format html|json, --export-trace <jsonl>, and --export-out <path>.

Print Mode

lash --print "<prompt>" runs Lash autonomously: it boots, executes the prompt, prints the assistant's prose to stdout, and exits. There is no TUI; status and tool output go to stderr. An autonomous system prompt is injected so the assistant completes the task without asking for input.

$ lash --print "Summarise this branch's changes in two bullets."
# Assistant prose to stdout, tool/lifecycle logs to stderr.

$ lash --print "Investigate the latest test failure." \
       --await-background-work \
       --turn-usage-json out/usage.json

Config File

Configuration lives at ~/.lash/config.json (overridable via the LASH_HOME environment variable). The schema is owned by LashConfig in lash-cli/src/config.rs and uses serde(deny_unknown_fields) — unknown top-level fields are rejected to catch typos.

{
  "active_provider": "openai",
  "providers": {
    "openai": { "kind": "openai", "api_key": "sk-..." },
    "anthropic": {
      "kind": "anthropic",
      "api_key": "sk-ant-...",
      "options": {
        "cache_retention": "long",
        "max_output_tokens": 16384
      }
    }
  },
  "auxiliary_secrets": {
    "tavily_api_key": "tvly-..."
  },
  "mcp_servers": {
    "docs": {
      "transport": "stdio",
      "command": "uvx",
      "args": ["mcp-server-docs"]
    }
  },
  "agent_models": {},
  "model_defaults": {
    "openai": { "model": "openai/gpt-5.5", "variant": "medium" }
  }
}

Field	Type	Purpose
`active_provider`	string	Key of the currently active provider; must exist in `providers`.
`providers`	map	Per-provider credentials and metadata, keyed by provider kind. Shared provider tuning lives under `options`, including `cache_retention` (`none` \| `short` \| `long`) and `max_output_tokens`.
`auxiliary_secrets`	object	Secrets for non-LLM services. Currently `tavily_api_key`.
`mcp_servers`	map	MCP server configs by name. Discriminated by `transport`: `stdio`, `streamable_http`, or `sse`.
`agent_models`	map	User-overridable model names per subagent capability.
`model_defaults`	map	Fresh-session model + variant default per provider kind. Session resumes ignore this and use the persisted head.

Environment Variables

The CLI reads a small set of environment variables — most are overrides for paths or behavior the config file doesn't cover.

Variable	Purpose
`LASH_HOME`	Override the root data directory (defaults to `~/.lash/`).
`TAVILY_API_KEY`	Tavily API key for the bundled web search tool. Alternative to `--tavily-api-key` and the config file.
`LASH_COPY_BINDING`	Override the copy keystroke (`ctrl-c`, `ctrl-shift-c`, or `ctrl-y`).
`LASH_LOG`	`tracing-subscriber` log filter (e.g. `debug`, `warn`, `lash=trace`).
`LASH_NO_OSC52`	Disable OSC 52 clipboard escape sequences.
`LASH_INSTALL_DIR`	Override the install dir used by `--update`.
`LASH_REPO`	Override the GitHub repo used by `--check-update` / `--update`.
`GOOGLE_CLOUD_PROJECT[_ID]`	Google Cloud project ID for the Gemini / Code Assist provider.

Resume & Fork

Every session has a UUID and a generated human-readable name. --resume <id_or_name> accepts either, plus the legacy .db filename for old sessions. Without an argument, /resume opens an interactive picker showing the 50 most recent sessions sorted by recency.

/fork branches the current session at the current message and opens the fork in a new terminal window. Lash resolves the launcher using the running binary's $PATH entry and falls back to the executable directory if needed. The launched fork runs lash --resume <new-session-id> in the new terminal.

PreviousAgent Service NextPlugins

Source anchors: lash-cli/src/main.rs, lash-cli/src/command.rs, lash-cli/src/config.rs, lash-cli/src/setup.rs, lash-cli/src/paths.rs, lash-cli/src/interactive/input_handling.rs.