Shell commands

Most agents spend their time in a terminal, and not every agent has lasso's MCP server configured. These subcommands give a shell the same tools, with the same behavior and the same descriptions, by talking to the running lasso server:

Finding the server#

lasso mcp, lasso notify and lasso open are MCP clients of /mcp. They find it, and authenticate, from the environment:

/mcp is open on lasso's loopback listener by default, so on lasso's own machine none of these is usually needed. From another machine, point LASSO_URL at lasso's tailnet address (-tailnet). These commands send no Cloudflare Access headers, so they cannot pass Access, nor a lasso started with the deprecated -require-access-header.

A per-host token also decides what "your own host" means for tools that default host. Without one, the caller is unidentified and the default host is lasso's own box. On a remote machine with no per-host credential, pass -host <alias> where a tool takes one. -host takes lasso's own box by its hostname (-host titan) or as local, the same as the tools do.

lasso mcp#

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

Examples:

lasso mcp list-hosts
lasso mcp list-agents -host myhost
lasso mcp create-agent -type git -repo ~/src/app -prompt "fix the flaky test" -agent codex
lasso mcp get-agent -to "Fix the push flow"
lasso mcp shared-browser -start=false
lasso mcp browser-list-pages -browser work

• The flags come from the server. Each tool's flags are built from the input schema the running server advertises, not from a table in the binary. The lasso you type may be older or newer than the one answering (after a lasso update, or with LASSO_URL pointing at another machine), and the flags always match the server. Plugin tools (<plugin>__<tool>) show up the same way.
• Either spelling works, for tool names and flags: list-hosts or list_hosts, -agent-id or -agent_id. Listings use the kebab-case form.
• Omitted flags are absent from the call, not sent as zero values, so the tool's own default applies. This matters: an omitted host and an empty host are different requests.
• Booleans can be written bare (-focus) or explicitly (-focus=false). A list parameter takes its flag once per element. An object parameter takes JSON.
• Required parameters are checked locally before the call, mirroring the server's own validation.

Flags before the tool name:

Output. Every lasso tool returns structured output, and that JSON is what is printed: indented on a terminal, compact when piped, so | jq needs no flag.

Exit codes. 0 on success. 1 when the tool refused (its error on stderr) or when the server could not be reached. 2 for a usage error, such as an unknown tool or a bad flag. -h prints help to stdout and exits 0.

lasso notify#

lasso notify [flags] <message...>
<command> | lasso notify [flags]        read the message from stdin

With no message argument it reads one from stdin (up to 8 KiB), so make test 2>&1 | tail -5 | lasso notify works. A terminal on stdin with no message is a usage error rather than a hang.

It reaches a locked phone, so use it when you actually need the human: a decision only they can make, a question that blocks you, a long job finishing while they are away.

Exit codes are the contract:

The whole round trip is bounded at 45 seconds. See Notifications for setting up a device.

lasso open#

lasso open [flags] <path> [flags]

Flags may come before or after the path. One path at a time.

• A relative path is resolved against this shell's working directory, on the machine the command runs on, before the call. A ~/ path is passed through and expanded against the target host's home.
• A directory opens the web sidebar's file tree there instead of the viewer. The Mac app opens nothing for one.
• The host defaults to your own host. Without a per-host credential (LASSO_MCP_TOKEN) that is lasso's own box, which -host also takes by its hostname or as local. On a remote fleet machine without one, pass -host <alias>, or the path is looked for on the lasso host.

Exit codes: 0 when at least one lasso tab or Mac app received it (prints opened file <path> on <host> in N lasso tabs or in N Mac apps), 1 when the app it was meant for is not open (nobody saw it; reason on stderr) or the call failed, 2 for a usage error. The round trip is bounded at 30 seconds.

lasso closeme#

lasso closeme

Closes the lasso agent this shell runs in: it kills the agent process and closes its herdr pane, the same teardown as close_agent. It takes no arguments. It reads $HERDR_PANE_ID, which herdr exports into every pane, and fails if that is unset (you are not in a lasso-managed pane).

Unlike the other three, closeme is not an MCP client. It POSTs the pane id to the local lasso's /api/agent/close:

• It always talks to a lasso on this machine: LASSO_LISTEN (default 127.0.0.1:8090) over plain http. LASSO_URL and LASSO_MCP_TOKEN are not used.
• It sends the UI_AUTH basic credentials when that is set.
• The pane is always closed, and the git worktree is kept.
• If the agent was spawned on this machine by a different lasso, the local lasso picks up that peer's record for the pane and closes it.

Closing your own pane kills the shell the command runs in, so the connection may drop before the reply arrives. Only a failure to reach the server, or an error status from it, is reported.