lash-cli is a Host Application: it selects reusable Lash SDK crates and owns the executable's composition, configuration, presentation, operational policy, and releases.
The CLI depends on one reviewed Lash Git revision. Lash exposes runtime, protocol, provider, plugin, persistence, tracing, and language crates. The CLI turns those pieces into a terminal product.
+Argument parsing, setup and stored configuration, provider materialization, concrete plugin wiring, execution-mode selection, TUI state, autonomous JSON/RPC surfaces, session navigation, export, update policy, installer assets, profiling, and binary releases.
The reusable runtime and facade, protocol implementations, provider factories, generic tools and plugins, stores, durable process machinery, Lashlang, trace contracts, and embedding documentation.
Every local crate is private to the terminal application unless another consumer justifies promoting a capability into the Lash SDK.
Binary bootstrap, configuration, providers, plugin composition, commands, session flows, autonomous modes, and terminal application state.
Terminal input, frame lifecycle, and rendering primitives.
Host-owned UI extension contracts and activity presentation.
FFF-backed local search and the optional Lashlang search surface.
Ignore-aware file walking, filesystem notifications, and fuzzy file completion.
Session-tree HTML and JSON export for CLI persistence and traces.
CLI-owned applied workflow plugin and terminal extension.
The debug CLI harness and CLI performance helpers exercise product behavior without becoming runtime SDK contracts.
arguments + ~/.lash/config.json
+ │
+ ▼
+provider factories + plugin factories + store
+ │
+ ▼
+ LashCore / LashSession
+ │
+ ┌──────┴────────┐
+ ▼ ▼
+interactive TUI --print / JSON / RPCExecution modes such as standard and rlm are Lash protocol plugins. The CLI chooses and configures one for a session; it does not implement protocol semantics itself.
lash-cli may depend on published or Git-pinned Lash SDK crates. Lash must not depend back on CLI crates. A second application that needs CLI-private code is evidence for extracting a focused SDK capability—not for making applications depend on one another.
A mockup of the html exporter's two-edge model: continue_as renders as an inline AgentFrame divider, and spawn_agent renders as a drill-in card. Click any node to follow the call tree. This page is a design exploration: everything below is static, hand-written sample data, not a render produced by lash-export. The continue_as inline AgentFrame-switch divider now ships in lash-export's multi-session tree view; the spawn_agent drill-in card shown here stays illustrative — the real exporter presents subagents as sibling views.
Root session of the run. Two parallel spawn_agent children gather inventory, then a continue_as AgentFrame switch carries the synthesis into frame s4·e51a.
Audit the codebase: list every file under src/auth/ that handles session tokens, summarise schema migrations since v3, and produce a single ordered list of the riskiest places to land a compliance fix.
Take the auth-file inventory and the migration summary; produce a single ranked list of compliance touchpoints. Each item gets a one-line rationale and an effort estimate. Stop when the list is < 12 items.
+ +Take the auth-file inventory and the migration summary; produce a single ranked list of compliance touchpoints…
+1. cookie_jar.rs: refresh-token rotation lands in the same write as session_secret; partition first. ~½ day
2. token_store.rs: v5 adds refresh_token_hash, but the read path still falls back to plaintext on cache miss. ~1 day
3. …
Subagent spawned from root at e2. Same shape as the root view: full transcript, full controls, full minimap. Use the breadcrumb above to return.
List files under src/auth/ that handle session tokens, with the read paths grouped by entry point.
Subagent that itself spawned a deeper child (migration_v5). Drill in further to see depth 2.
Grandchild, spawned from db_migrations, which itself was spawned from root. The breadcrumb traces the whole way back.
continue_as is linear. The new frame's entries flow in the same view, behind a sodium-bracketed divider that names the seam: task, seed (projected vs global), parent context %, the new frame id. One scroll, one document.
Spawn_agent becomes a card you click into. The subagent gets its own full view: same hero, same controls, same minimap as the root. No nesting hacks, no width-cascade problems, no awkward squeeze.
+The top bar shows where you are: root > db_migrations > migration_v5. Click any segment to jump back. Browser back works (history.pushState). The lineage strip below shows the whole tree as a sibling-aware map.
Every view is just a session render. The exporter already does that for one .db; we just iterate per descendant session, link them with the breadcrumb, and bake them all into one self-contained html file.
+The trace exporter renders one persisted lash session (plus any child sessions created by spawn_agent) into a single self-contained HTML document. The visual language matches the rest of the docs (warm-iron / fast-amber). The forensic affordance is two-edge-aware: continue_as AgentFrame switches are linear seams inside the same session view; subagents are drill-in cards into child-session views.
continue_as and spawn_agent both create a visible boundary, but only spawn_agent creates another session. continue_as appends an AgentFrame record inside the same session; spawn_agent creates a child session with SessionRelation::Child. Flattening those under one shape is what made the previous exporter feel wrong, so the renderer mirrors the runtime distinction.
| Edge | +Tool | +Cardinality | +Lifecycle | +Visual treatment | +
|---|---|---|---|---|
| AgentFrameSwitch | +continue_as |
+ 1 → 1 terminal | +Current frame ends; the new frame takes over with seed and task. |
+ Inline divider. The frame's entries continue in the same session view, behind a sodium-bracketed seam that names the boundary. | +
| Subagent | +spawn_agent |
+ 1 → N blocking | +Parent waits for the child to finish, then resumes. | +Drill-in card. Click into the subagent's own full view (same hero, same controls). Breadcrumb tracks the path back. | +
Continue_as is linear, so the natural reading is one transcript that crosses an AgentFrame boundary inside the same session. The seam is a full-width band with sodium hairlines top and bottom: the task in display type, the seed broken into projected vs global entries, and a hairline-divided stat strip. Those four pieces of state show the reader what was carried forward and what was left behind.
+Take the auth-file inventory and the migration summary; produce a single ranked list of compliance touchpoints. Each item gets a one-line rationale and an effort estimate. Stop when the list is < 12 items.
+Spawn_agent is blocking but its result is a separate unit of work. Inlining the child transcript inside the parent's tool entry would force a width-cascade and lose the subagent's full hero / controls / minimap. Instead, the exporter gives the subagent its own full view reached by click-through navigation. The card below shows the affordance; in the shipped exporter the lineage strip and breadcrumb carry the [data-go] targets. The lichen accent keeps the child visually subordinate to the sodium AgentFrame switch seam.
Summarise migrations/ schema changes since v3. Flag any change that touches identity, session, or token columns.
The breadcrumb is the primary "where am I" affordance, sticky at the top of the viewport so navigation context never scrolls away. It shows the lineage from root through any subagents the reader has drilled into. The separator is a quiet ash ›; sodium-tinted arrows are reserved for the lineage strip's actual edge glyphs (↪, ▾) one row down, so the two bars don't compete for the same accent.
An end-to-end mockup with three views (root → db_migrations → migration_v5) backed by synthetic but realistic content. Click any drill-in card or breadcrumb step to navigate. Browser back works through history.pushState. Resize the iframe to see responsive behavior.
The renderer is additive; single-session export still works as it always did. Child-session detection is automatic, and AgentFrame dividers come from the owning session's tool-control records.
+Given a root .db path and a trace JSONL, tree::load_tree_from_paths scans the sessions directory, keeps every child store reachable through parent_session_id chains, and partitions LlmPromptSnapshots by context.session_id. Child sessions are classified from persisted SessionRelation::Child metadata and anchored back to the parent's spawn_agent tool call when possible. continue_as no longer participates in tree discovery because its AgentFrame records live inside the same session store.
A view is one persisted session: the root or a spawned subagent. html::tree::write_view writes one <section class="view"> per session: hero, lineage strip, minimap spine, and transcript. continue_as AgentFrame switches stay inline in that session's transcript (they never split the view), and spawned subagents are reachable through [data-go] navigation in the lineage strip and breadcrumb that targets child-session views.
Each view is rendered up-front and toggled by a tiny IIFE that reads window.__lashTraceTree (a serialized list of {id, label, sid, parent}, one entry per view head (root and each subagent), not one per session; id and parent are view IDs, sid is the head session's short id). Click handlers on [data-go] elements (drill-in cards, breadcrumb segments, lineage pills) call history.pushState and swap the active .view. The browser back button does the right thing through popstate.
Sodium is reserved for the active edge: AgentFrame switch seams, the breadcrumb's current step, the user's intent. Lichen marks the subagent affordance: drill rails, drill arrows, child status pills. Filter chips read as quiet chalk by default and gain a sodium strikethrough only when the user has actively filtered something off, so the controls strip never floods the page with accent. Ash structural lines do everything else.
+Single self-contained HTML; tokens, fonts, CSS, and JS all inlined.
+lash-exportTree discovery and edge classification. Returns a LoadedSessionTree with one LoadedSessionNode per discovered session; each carries its own chronological projection, partitioned LLM prompts, and the list of subagent edges anchored by parent call_id.
lash-exportThe public render_tree(tree, format) is the multi-view entry point; the writers in the html::tree submodule (write_crumb_bar, write_view, write_view_hero, write_lineage, and render_tree_data_script) own the multi-view elements, while render_node_entries reuses the existing message/tool/RLM-step renderers unchanged.
lash-exportTokens are appended at the bottom under "multi-view: breadcrumb, lineage, drill, AgentFrame switch". The base trace stylesheet stays intact for single-session exports; multi-view rules only activate when the page contains .view sections.
lash-exportThe view-switcher IIFE at the bottom reads window.__lashTraceTree, wires [data-go] click handlers, renders the breadcrumb, and listens for popstate. It exits cleanly if the tree global is absent (single-session export).
The lash binary runs an interactive terminal UI by default, autonomous single-shot modes under --print, a JSONL event stream under --mode json, an stdin/stdout RPC loop under --mode rpc, and administrative flows like --export and --reset. This repository owns the executable and its user-visible contract.
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 TUIRe-run the wizard at any time with lash --provider. Use /provider from inside a session to switch providers without restarting.
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] | Open a compaction Agent Frame seeded by a summary |
/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 | /status | /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 the session's execution mode (standard / rlm); it is locked for the session, so changing it requires a new session started with --execution-mode |
/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 [id-or-name] | Search sessions or resume by id/name (interactive picker if no arg) |
/skills | — | /skills | Browse loaded skills |
/help | /? | /help | Open the commands and shortcuts overlay |
/exit | /quit | /exit | Quit |
The TUI uses a small, consistent set of shortcuts. The full list is also available in-session via /controls.
LASH_COPY_BINDING if the default conflicts with your terminal.A running process shows running; a terminal one shows its outcome — success, error, cancelled, or abandoned. abandoned (ADR 0019) means the owner was lost without recording an outcome and renders in the failure style, like error. A detached command (shell.start with detach: true) never appears in the dock: it returns immediately with status: "detached" and is owned by the host/OS, not tracked as a session process.
Run lash --help for the full list. The most common flags, grouped by purpose:
--provider--model <name>--variant <name>high, max, xhigh).--api-key <key>--base-url <url>--tavily-api-key <key> (env TAVILY_API_KEY)--execution-mode <mode>standard (default) or rlm.-c, --context-approach <approach>rolling_history or observational_memory.--rlm-var name=<json>--rlm-vars-file <path>--rlm-termination <mode>natural (default) or require an explicit structured finish with finish-required.--resume <id_or_name>.db filename.--resume-prompt <prompt>-p, --print <prompt>--mode <interactive|json|rpc>interactive is the TUI default; json requires --print and writes JSONL events to stdout; rpc reads LF-delimited requests from stdin and writes LF-delimited records to stdout.--await-background-work--turn-usage-json <path>--debug--trace-level <standard|extended>standard.--debug-ui-trace trace.json--debug-ui-trace-interval-ms <ms>--om-observation-message-tokens <tokens>--om-observation-buffer-tokens <tokens>--om-observation-block-after-tokens <tokens>--om-observation-max-tokens-per-batch <tokens>--om-previous-observer-tokens <tokens>--om-reflection-observation-tokens <tokens>--om-reflection-buffer-activation-percent <percent>--om-reflection-block-after-tokens <tokens>--reset~/.lash/ and ~/.cache/lash/ and exit.--info--check-update / --update--export <db>--export-format html|json, --export-trace <jsonl>, and --export-out <path>.lash --print "<prompt>" runs Lash autonomously: it boots, executes the prompt, prints the settled TurnFinish::AssistantMessage prose to stdout, and exits. Print mode runs without a TUI; status and tool output go to stderr. An autonomous system prompt is injected so the assistant completes the task without asking for input.
Each completed tool call prints a one-line status marker to stderr: [tool] <name> · <status> · <duration>, where status is ok, error, or cancelled and the duration is dropped when it is negligible. The <name> is the runtime tool name (exec_command, not the shell.exec surface path); see the Lash SDK's reporting contract.
$ lash --print "Summarise this branch's changes in two bullets."
+# Assistant prose to stdout, tool/lifecycle logs to stderr:
+# [tool] exec_command · ok · 41ms
+# [tool] read_file · ok
+
+$ lash --print "Investigate the latest test failure." \
+ --await-background-work \
+ --turn-usage-json out/usage.json--mode json and --mode rpc are machine-facing CLI surfaces. They do not enter the TUI and they reserve stdout for LF-delimited JSON records. The stream is versioned: the opening turn_start record (and the RPC ready record) carries protocol_version: 1, so a consumer can pin the wire shape before parsing the rest.
$ lash --mode json --print "Summarise this repository."
+{"type":"turn_start","protocol_version":1,"stream_id":1}
+{"type":"event","stream_id":1,"activity":{"id":"a1","correlation_id":"c1","type":"model_request_started","protocol_iteration":0}}
+{"type":"event","stream_id":1,"activity":{"id":"a2","correlation_id":"call-3","type":"tool_call_completed","call_id":"call-3","name":"exec_command","args":{"...":"..."},"output":{"...":"..."},"duration_ms":41}}
+{"type":"turn_finish","stream_id":1,"ok":true,"cancelled":false,"assistant_text":"...","outcome":{...},"usage":{...},"children_usage":[],"errors":[],"execution":{...},"tool_calls":[...]}Each event wraps one TurnActivity: an id, a correlation_id, and a flattened TurnEvent tagged by type. Tool events report the runtime tool name (exec_command), not the shell.exec surface path; see the Lash SDK's event vocabulary and stability contract.
RPC mode starts a reusable session and reads one JSON object per line from stdin. It opens with a ready record ({"type":"ready","protocol_version":1,"protocol":"lash.rpc.v1","methods":["prompt","ping","shutdown"]}). A prompt request streams turn_start, event, and turn_finish records tagged with the request id, then writes a final response.
{"id":1,"method":"prompt","params":{"prompt":"List the top-level crates."}}
+{"id":2,"method":"shutdown"}Configuration lives at ~/.lash/config.json (overridable via the LASH_HOME environment variable). The schema is defined by LashConfig in lash-cli and uses serde(deny_unknown_fields), so unknown top-level fields are rejected to catch typos.
{
+ "active_provider": "openai",
+ "providers": {
+ "openai": { "type": "openai", "api_key": "sk-..." },
+ "anthropic": {
+ "type": "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. |
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/). |
OPENAI_API_KEY / OPENAI_COMPATIBLE_API_KEY | Provider API keys used during setup or one-shot sessions when no stored key is configured. |
OPENROUTER_API_KEY | OpenRouter API key accepted as an OpenAI-compatible shortcut when --base-url points at https://openrouter.ai/api/v1. |
TAVILY_API_KEY | Tavily API key for the bundled web search tool. Alternative to --tavily-api-key and the config file. |
LASH_GOOGLE_CLIENT_ID / LASH_GOOGLE_CLIENT_SECRET | Override the OAuth client credentials used by the Google / Code Assist provider. |
CODE_ASSIST_ENDPOINT / CODE_ASSIST_API_VERSION | Override the Google Code Assist API endpoint and version for provider integration testing. |
LASH_COPY_BINDING | Override the copy keystroke: ctrl-shift-c (default) or ctrl-y. Ctrl+C stays reserved for cancel semantics, so ctrl-c falls back to the default. |
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. |
LASH_TOKIO_STACK_BYTES | Override the worker-thread stack size used by the CLI Tokio runtime. |
GOOGLE_CLOUD_PROJECT[_ID] | Google Cloud project ID for the Gemini / Code Assist provider. |
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. The picker hides zero-turn sessions when any non-empty session exists; direct /resume <id-or-name> may still target any session.
/fork branches the current session at the current message and opens the fork in a new terminal window. Lash resolves the launcher from the running executable and falls back to finding lash on $PATH if that binary isn't launchable. The launched fork runs lash --resume <new-session-id> in the new terminal.
CLI releases are manual, reproducible GitHub releases cut only from a green commit on main. They are independent from Lash SDK releases.
main after required CI passes.Release-Notes: commit section.release_sha blank for current main, or provide a green ancestor commit.Do not create release tags or upload artifacts by hand.
+lash-linux-x86_64.tar.gz, lash-linux-aarch64.tar.gz, and lash-macos-aarch64.tar.gz.
SHA256SUMS covers the binary archives. install_lash.sh is rendered for the exact release tag and installs the matching asset.
The CLI records one exact Lash Git revision in its root Cargo.toml. Updating that revision is an explicit compatibility change with its own checks. CLI and SDK version numbers do not need to advance together.