CLI Reference

Longhouse installs two binaries. longhouse is the native device CLI: it pairs the machine, launches managed provider sessions, and reports local health. longhouse-server runs and inspects the Runtime Host. Commands do not cross between them.

Device CLI (longhouse)

Managed provider sessions

Each of these launches the provider's own CLI in your terminal while Longhouse owns the control path, so the session stays reachable from the browser and the API after you walk away.

longhouse claude
longhouse codex
longhouse cursor
longhouse opencode
longhouse pi --prompt "summarize the failing test"
longhouse omp
longhouse antigravity

What each one can do afterwards is not uniform. The table below is generated from schemas/managed_providers.yml, the contract that also drives the runtime, so it cannot quietly disagree with the product.

Bare claude, codex, cursor-agent, opencode, pi, omp, and agy runs still import into the timeline. They stay Shadow sessions: searchable and observable, with no control path, because Longhouse never owned one.

Codex and OpenCode also take attach and stop subcommands, which reattach to or shut down a running managed session. Claude and Cursor take configure, which installs their native Longhouse hooks.

longhouse auth

Store the device credential this machine uses for every other native command. Without a token in the environment it opens the Runtime Host in a browser to approve this machine. The URL defaults to the one stored on this machine, which the installer writes from LONGHOUSE_URL.

longhouse auth
longhouse auth --url https://you.longhouse.ai
LONGHOUSE_DEVICE_TOKEN="..." longhouse auth --url https://you.longhouse.ai
longhouse auth --url http://192.168.1.20:8080 --allow-insecure-http
longhouse auth --clear

Plain http:// is accepted only for loopback and Tailscale addresses. A LAN address needs --allow-insecure-http (or LONGHOUSE_ALLOW_INSECURE_HTTP=1), which is stored with that address and warns on every use; any other address needs https://. Every native client follows the same rule, as do the longhouse-server commands that send the device token.

--clear disconnects the machine: it revokes this machine's device token on the Runtime Host, then deletes the stored credentials. If the Runtime Host cannot be reached the credentials are kept so you can retry; --clear --local-only deletes them anyway and leaves the token to be revoked under Settings → Devices.

longhouse machine

Install, repair, or restart the native Machine Agent service.

longhouse machine repair
longhouse machine repair --dry-run
longhouse machine repair --repair-service

longhouse machine scope

Choose which existing session history the Machine Agent may import. Old transcripts can hold code and secrets from any project you ever ran an agent in, so a newly connected machine that has not chosen imports only sessions that start from now on. A machine that was already shipping history before scopes existed keeps shipping all of it. Sessions you start later always ship. Changing the scope later backfills whatever became eligible.

longhouse machine scope                      # show the scope and what it leaves out
longhouse machine scope --since now          # only new sessions (the default)
longhouse machine scope --since 2026-09-01   # sessions started on or after a date
longhouse machine scope --since all          # everything on this computer
longhouse machine scope --project ~/git/app  # also the full history of a folder
longhouse machine scope --no-projects        # drop the per-folder opt-ins
longhouse machine scope --prompt             # ask (needs a terminal)

A session belongs to a folder when the working directory it recorded is that folder or below it (Claude, Codex, OpenCode, Pi, OMP and Cursor record one; Antigravity history is covered by the date rule only). A session's start is its file's creation time (last modification where the file system keeps none), or the session's own first timestamp when that is earlier. Narrowing the scope stops further imports; sessions already uploaded stay on your Runtime Host. Naming a file yourself with longhouse-server ship --file is not filtered.

longhouse uninstall

Remove Longhouse from this computer: revoke this machine's device token on the Runtime Host, stop and remove the Machine Agent service, remove the hooks Longhouse added to Claude Code and Cursor, and delete the binaries (and Longhouse.app on a Mac). It stops before removing anything if the token cannot be revoked.

longhouse uninstall --dry-run   # list what would be removed
longhouse uninstall             # asks first; --yes skips the question
longhouse uninstall --purge     # also delete local state under ~/.longhouse
longhouse uninstall --local-only  # do not revoke the token on the Runtime Host
longhouse uninstall --keep-app    # leave Longhouse.app in place (macOS)

Sessions already uploaded stay in your Runtime Host's archive until you delete them there. To cut off a machine you cannot reach, use Settings → Devices → Revoke on the Runtime Host.

longhouse local-health

The same snapshot the macOS menu bar shows: whether the machine is paired, whether the agent is running, and what it can see.

longhouse local-health --json

longhouse shipping

Inspect or discard the evidence retained for uploads that could not be shipped. discard does nothing without --confirm; it reports what it would remove.

longhouse shipping inspect
longhouse shipping inspect --json
longhouse shipping discard --source-epoch EPOCH --confirm

longhouse build-identity / verify-pair

The device CLI and the engine ship as a pair built from one commit. These print that identity and check the pairing held through install.

longhouse build-identity --json
longhouse verify-pair

Runtime Host (longhouse-server)

longhouse-server serve

Start the Runtime Host from its server environment.

longhouse-server serve                       # localhost:8080
longhouse-server serve --port 9090          # custom port
longhouse-server serve --demo               # start with sample data
longhouse-server serve --daemon             # run in background
longhouse-server serve --stop               # stop the background server

On a loopback bind auth is off for frictionless local use. On a public bind it is required — see Configuration.

longhouse-server onboard

The guided path: start a local Runtime Host, install the Machine Agent, ask what history to import, and open the timeline. --remote-url points it at a Runtime Host you already run instead.

longhouse-server onboard
longhouse-server onboard --remote-url https://you.longhouse.ai

longhouse-server ship

One-shot import of the sessions already on disk that this machine's import scope allows (see longhouse machine scope). Useful for backfilling a machine before the Machine Agent takes over.

longhouse-server ship
longhouse-server ship --file path/to/session.jsonl

longhouse-server recall

Search past sessions from the terminal.

longhouse-server recall "how did I handle rate limiting"
longhouse-server recall "deploy fix" --project longhouse --days-back 30
longhouse-server recall-context REF   # REF comes back with each recall result

longhouse-server sessions

Inspect a session, read its events, or interrupt its active turn.

longhouse-server sessions get SESSION_ID --json
longhouse-server sessions events SESSION_ID --roles user,assistant
longhouse-server sessions interrupt SESSION_ID

longhouse-server tail

Read the recent tail of a session. Tool output dominates most transcripts, so --roles user,assistant is usually what you want.

longhouse-server tail SESSION_ID
longhouse-server tail SESSION_ID --roles user,assistant -n 50

longhouse-server send / inbox / reply

Directed input between managed sessions. A send persists before any delivery attempt, so the target picks it up whenever it next reads its inbox.

longhouse-server send SESSION_ID "Check the failing test in auth.py"
longhouse-server inbox
longhouse-server reply INPUT_ID "Fixed — it was the token clock skew"

longhouse-server continue

Continue a session with a follow-up message. Both arguments are required.

longhouse-server continue SESSION_ID "Now run the integration tests"

longhouse-server peers

List other sessions working around the same repo.

longhouse-server peers
longhouse-server peers --all --days 14

longhouse-server status / config / db

Local health in one line, effective configuration with the source of each value, and SQLite diagnostics.

longhouse-server status --verbose
longhouse-server config show
longhouse-server db doctor

longhouse-server version / upgrade

longhouse-server version --check
longhouse-server upgrade

The device binaries upgrade separately, by re-running the installer: curl -fsSL https://get.longhouse.ai/install.sh | bash, then longhouse verify-pair.

Listing what is running

There is no wall subcommand on either binary. The wall is a query on the Machine API and the browser view over it — see Machine API.

curl "http://localhost:8080/api/agents/sessions/wall?project=longhouse&days=7"

Common flags