CLI

The lasso binary is both the server and its own control surface. A bare lasso, or any invocation whose first argument starts with -, runs the server in the foreground. Any other first word is a subcommand; an unknown one prints the usage and exits 2.

lasso -h          # the subcommand list (also: lasso help, lasso --help)
lasso serve -h    # every server flag

Summary#

Running the server#

lasso and lasso serve#

Run the server in the foreground, logging to stderr. Both take the server flags listed in Configuration. The server prints a UI: http://<addr> line once it has bound its port.

lasso start / lasso up#

Starts lasso serve detached in its own session, with any flags you pass forwarded to it, so the background server honors the same flags as a foreground one:

lasso start -listen 127.0.0.1:8090 -theme ocai

It writes the server's PID to ~/.lasso/lasso.pid and its output to ~/.lasso/lasso.log (truncated on each start), then waits up to five seconds for the UI: line and prints the URL. If a live PID is already recorded, it says so and does nothing. These two files are always under ~/.lasso, even when LASSO_DIR points elsewhere.

lasso stop / lasso down#

Sends SIGTERM to the recorded PID, waits up to five seconds for it to exit, and removes the PID file. A stale PID file is cleaned up and reported as "not running".

lasso restart#

lasso stop (when a server is running) followed by lasso start with the flags you pass.

lasso status#

Prints lasso: running (pid N) → <url> or lasso: stopped. The URL is the last UI: line in ~/.lasso/lasso.log. It only knows about a server started with lasso start; a systemd-supervised lasso reads as stopped.

Maintenance#

lasso update#

How it updates depends on how lasso was installed:

• A release binary (the install script, or a mise ubi: install): downloads the latest GitHub release for this platform, verifies it against the release's checksums.txt, and atomically replaces the running binary. It then restarts the lasso start daemon if its PID file is live, or, on Linux, any systemd service whose main process is this binary. When already up to date, it still restarts a systemd-run lasso left on an old binary by an earlier --no-restart.
• A systemd-supervised git checkout (a source checkout with a .git, run by an active systemctl --user unit): runs git pull --ff-only in the checkout and systemctl --user restart <unit>, which rebuilds from source. The checkout defaults to the binary's directory (LASSO_SRC_DIR overrides it) and the unit to lasso (LASSO_SYSTEMD_UNIT overrides it).

See Updating for the details.

lasso doctor#

Takes no flags. Prints one line per check, marked ✓ (pass), ⚠ (warn) or ✗ (fail), and exits 1 if any check failed. Only a missing herdr and an unwritable state directory are failures; everything else warns.

doctor does not check for ttyd, and it looks only at the default socket and port.

lasso telemetry#

lasso telemetry off turns lasso's anonymous usage analytics off, lasso telemetry on turns them back on, and a bare lasso telemetry says which it is and whether DO_NOT_TRACK or LASSO_TELEMETRY in the current environment would hold them off. It writes lasso.db directly, so it needs no running lasso; a running one notices within 30 seconds. The installer runs it with your answer.

lasso version#

Prints the version. lasso --version and lasso -v do the same.

For agents and scripts#

These subcommands are clients of a running lasso. They find it the same way:

lasso closeme, lasso skill and the plugin commands differ slightly; see their sections.

lasso connect#

Registers lasso's streamable-HTTP MCP servers with every supported agent CLI found on this machine (Claude Code, Codex, OpenCode, omp): lasso at <url>/mcp, which carries the browser_* tools too, and lasso-herdr at <url>/herdr-mcp. It probes the server first: /mcp must answer or nothing is registered, and lasso-herdr is registered only when /herdr-mcp lists herdr's tools. When lasso reports that its browser tools can't run, it says why. Every run also removes an entry named lasso-browser wherever it finds one, since lasso serves no /browser-mcp. Re-running it is safe: an identical entry is left alone and a different one is replaced.

Behind Cloudflare Access, a remote machine also needs a service token:

lasso connect -url https://lasso.example.com \
  -header 'CF-Access-Client-Id: <id>.access' \
  -header 'CF-Access-Client-Secret: <secret>'

Each CLI is registered through its own mcp add command where it has one. Claude Code and OpenCode take headers only on that command line, so header values are briefly visible in the process list while those commands run. Codex and omp get their headers written straight into their config files (config.toml, ~/.omp/agent/mcp.json), and lasso's first rewrite of a config file leaves a .bak copy beside it. Secrets are masked in everything connect prints. CLAUDE_CONFIG_DIR, CODEX_HOME and XDG_CONFIG_HOME are honored. See Connecting agents.

lasso mcp#

Calls lasso's MCP tools from a shell.

lasso mcp                      # list the tools this lasso serves
lasso mcp <tool> -h            # one tool's flags
lasso mcp <tool> [flags]       # call it
lasso mcp -json <tool> ...     # print the whole MCP result envelope

Tool names take either spelling (list-hosts or list_hosts), and flags take kebab or snake case. The flags come from the input schema the running server advertises, so they include plugin tools and follow the server automatically; a flag you leave out is absent from the call, not zero. Output is indented on a terminal and compact when piped. The exit code is 1 when the tool reports an error. See lasso mcp and friends.

lasso notify#

Pushes a notification to the human running lasso, through the notify MCP tool.

lasso notify "the migration drops 2 columns. Safe to run on prod?"
make test 2>&1 | tail -5 | lasso notify     # message from stdin (up to 8 KiB)

Exits 0 only when a device actually took the notification. When nothing is subscribed it prints the reason on stderr and exits 1, so a script can tell "delivered" from "nobody was listening". It waits up to 45 seconds. See Notifications.

lasso open#

Shows a file in the sidebar file viewer of every visible lasso tab (-app web) or in a window of the Lasso Mac app (-app mac), through the open_file MCP tool. Flags may come before or after the path.

lasso open -app web notes.md -line 40

A relative path is resolved against this shell's working directory before the call. A ~/ path is passed through and expanded against the target host's home. A directory opens the file tree there instead of the viewer. Without a per-host credential (LASSO_MCP_TOKEN), "your own host" is lasso's own machine, so on a remote machine pass -host. Exits 1 when the app it was meant for is not open to show it.

lasso closeme#

Closes the agent this command runs in: it POSTs $HERDR_PANE_ID to the local lasso's /api/agent/close, which performs the same soft close as the UI and the close_agent tool (stop the agent process, then close its pane). Takes no arguments. Fails if $HERDR_PANE_ID is unset.

It always talks to http://$LASSO_LISTEN (default 127.0.0.1:8090) on the same machine, sending UI_AUTH as basic auth when set. It does not read LASSO_URL or LASSO_MCP_TOKEN.

lasso skill#

Prints lasso's agent skill, the SKILL.md that /mcp also serves over the Skills extension. With a path, it prints that file of the skill instead, by the same relative path SKILL.md links it with: lasso skill docs/mcp/tools.md. Only SKILL.md and the Markdown in docs/ are there.

It reads the copy built into the binary, so it needs no running lasso and always matches the installed version.

lasso channel#

The stdio MCP server that delivers a bot's jobs into its session as a Claude Code channel. lasso writes it into every bot's .lasso/mcp.json, and claude starts it. For a bot on lasso's own machine it runs with LASSO_URL and LASSO_CHANNEL_TOKEN in its environment and long-polls lasso. For a bot on another host it is that host's lasso with --spool <folder>/.lasso/channel: it delivers the events lasso writes into inbox/ over SSH, moves each to done/, and rewrites the seen heartbeat, and never connects to lasso. Run by hand with neither the variables nor --spool, it prints its usage and exits 2.

Credentials and groups#

mcp-client and mcp-group only matter when the server runs with MCP_OAUTH set: with it unset, /mcp is open and every caller sees the whole fleet. Both write lasso.db directly, so they work whether or not the server is running. Their flags use two dashes. The full model is in Agent scope.

lasso mcp-client#

lasso mcp-client add --host <alias> [--fleet] [--name <label>]
lasso mcp-client list                         # alias: ls
lasso mcp-client token <client_id> [--ttl <duration>]
lasso mcp-client rm <client_id>               # aliases: remove, revoke

add prints a client_id and client_secret once, for the client_credentials grant; the secret is stored hashed. token mints a bearer token directly, for pasting into an MCP client that cannot run a grant. rm deletes the client and every token issued to it.

lasso mcp-group#

lasso mcp-group add <name>
lasso mcp-group rm <name>                     # aliases: remove, delete
lasso mcp-group list                          # alias: ls
lasso mcp-group add-member <group> <host|@group>...
lasso mcp-group rm-member <group> <host|@group>      # alias: remove-member
lasso mcp-group grant <from-group> <to-group>
lasso mcp-group revoke <from-group> <to-group>
lasso mcp-group reach <host>

Members are hosts (an ssh-config alias or local), or another group written with a leading @. Every host in a group may reach every other host in it, nested groups included. grant A B lets A's hosts reach B's and not the reverse, and grants do not chain. reach prints every host a given host can address and the rule that allows it.

lasso plugin#

Manages plugins. Alias: lasso plugins. Unlike mcp-client, these talk to the running server's /api/plugins (enabling a plugin starts a process only the server can own), found through LASSO_URL or LASSO_LISTEN and sending UI_AUTH when set. Flags accept one or two dashes.

See Plugins.