landfall CLI
The landfall CLI is open source at landfalls-ai/landfall-cli, and its README is the authoritative, always-current reference. This page is the short map of its commands, their flags, and the environment variables it reads.
Install and upgrade
brew tap landfalls-ai/landfall
brew install landfall
brew upgrade landfall # later, to pick up new releasesThe Homebrew cask lives in the public tap at landfalls-ai/homebrew-landfall. Builds exist for macOS and Linux on amd64 and arm64; the Quickstart shows the download-only install.
Authenticating
landfall login opens your browser and signs this machine in the same way you already sign in to Landfall on the web: password, or your organization's own identity provider if it has one connected. The CLI never needs to know which: your browser resolves that, and hands a working, org-pinned session back to the terminal that asked for it. There is nothing different to configure for an organization with SSO; the same command works either way.
That session renews itself silently in the background from then on: no re-prompt, no flag to turn on. You only see the browser again if you explicitly landfall logout, or an organization admin revokes all sessions.
For anywhere login's browser handoff can't reach, such as a CI job, a cron job or a headless machine with no browser to open, create a personal API key under Your settings, API keys (steps on Organization and personal settings). The full key is shown exactly once, at creation; store it wherever your script or CI system keeps secrets. Present it as a bearer token on any request:
curl -H "Authorization: Bearer lf_key_…" \ https://api.landfalls.ai/o/<your-org-slug>/incidents
A key is scoped to the one organization it was created for and to your own account's access within it, never more. Revoke it any time from the same tab; revocation takes effect on the very next request. Up to 10 active keys per organization, so keys for different machines or jobs can be told apart and rotated independently.
Commands
landfall --help prints the command list in the terminal.
Sign-in, instance and version
| Command | What it does |
|---|---|
| landfall login [--url <address>] [--save] [--json] | Sign this machine in via a passwordless browser handoff. Needed once, before install. --url signs in to a specific Landfall; --save also makes it the default for later commands; --json prints the outcome as JSON lines (see Console and read commands). |
| landfall logout | Clear the cached session from this machine and ask the server to revoke it. |
| landfall instance | Show the web, API and docs addresses the CLI uses, and which setting chose them. |
| landfall instance set <address> | Make that address the default Landfall. Sign in again afterwards. |
| landfall instance reset | Go back to the hosted default. |
| landfall version | Print this build's version and exit. --version and -v do the same. |
Harness and hook setup
| Command | What it does |
|---|---|
| landfall install [--yes] [--only <ids>] [--dry-run] | Detect the coding harnesses on this machine and register the landfall MCP server with each one you select. Signs in first when there is no session. Idempotent and conflict-safe. --yes takes every detected harness without a prompt; --only takes a comma-separated list of claude-code, codex, vscode, cursor, claude-desktop and windsurf; --dry-run reports what it would do and writes nothing. |
| landfall uninstall [--yes] [--only <ids>] | Remove the registrations install created. Only deletes an entry that still matches exactly what was written; anything modified is left in place and reported. |
| landfall hooks install [--only <ids>] [--dry-run] | Register lifecycle hooks in every hook host it detects (claude-code, codex, cursor), plus the status line in Claude Code. No sign-in needed. What each hook does is on Using Claude Code. |
| landfall hooks uninstall [--only <ids>] | Remove only Landfall's hook entries (and its Claude Code status line). An entry someone edited by hand stays. |
| landfall hooks policy [--init] | Print the local production allow-list and exactly what each rule would report. --init writes a documented starter file and never overwrites an existing one. |
| landfall hooks stop [--block] | What the registered Stop hook runs; you do not type it. By default it tells you room news is waiting and never makes your agent take another turn. --block (or LANDFALL_STOP_HOOK=block) makes it refuse a conclusion while the room holds news the agent has not seen. |
| landfall connect aws | Connect your AWS account with your own aws CLI. See AWS. |
Rooms
| Command | What it does |
|---|---|
| landfall serve [--link <URL>] | Run the MCP Edge Bridge on stdio: join the incident and expose the twelve war-room tools to whatever agent started it. It is the default command, so a bare landfall or a bare URL runs it. Harnesses invoke this themselves via the registration. --link (or LANDFALL_LINK) pre-joins from a share link; after landfall login, a plain incident URL joins as you with no share link. If the bridge's local queue cannot be opened, serve logs once and falls back to a direct surface of nineteen tools: the publish and vetting verbs (post_finding, note, post_widget, stage_claim, corroborate_claim, contest_claim, flag_context) and record_activity appear directly, and share_with_room is absent. |
| landfall join [URL] | Join an incident and keep presence alive without exposing MCP tools; Ctrl-C to leave. |
| landfall note "…" | Post a one-off finding to the room straight from your terminal, then exit. |
| landfall leave | Leave the incident. |
| landfall status | One line of room status (the room, new items, held shares, votes awaited), for a Claude Code status line. Prints nothing when no session is in a room, and always exits 0. |
| landfall rooms [--json] | The rooms this machine has open, their agent sessions, and who is reading each, with each reader's position. |
| landfall daemon, landfall daemon stop | The room daemon: one per user on each machine, holding each room's connection and a separate reading position per reader. serve starts it in the background; landfall daemon runs it in the foreground and daemon stop stops it. |
Working-directory hold
A share that names your working directory is held on your machine until you release it. None of these is an MCP tool, so an agent cannot call them.
| Command | What it does |
|---|---|
| landfall held [--room <incidentId>] | List what is held for this checkout's room. |
| landfall held drop <id> | Discard one held share. |
| landfall allow-cwd [--room <incidentId>] | Let working-directory content into that room and release every held share. They publish from your agent's session within a few seconds. |
Console and read commands
These commands exist mainly for the Claude Code mod and its/landfall console (see Using Claude Code and Using the Claude desktop app), which draws what they print. Most print one JSON object on one line and exit 0 even when they fail, as {"ok":false,"error":"..."} with a sentence a person can act on, so a caller reads ok rather than an exit code. watch prints a line per change, and whoami prints text unless you pass --json. landfall --help lists them, and you can run any of them yourself, for example landfall incidents | jq ..
The commands that read a room take --room (a room key, an incident id or a display id like 168) when this folder reads more than one room, and --host to name the agent host they run for. By default they read this folder's room; a folder in no room answers that it is not in a war room. Reads that the server resolves per viewer run as you, with your own sign-in; the rest use the room's own session.
| Command | What it does |
|---|---|
| landfall whoami [--json] | Say whether this machine is signed in, without any network call. With --json: signedIn, the organization, the Landfall address, when the sign-in expires and whether it can renew itself. When it is not signed in, reason is none, expired or other-instance (the sign-in is for a different Landfall). |
| landfall login --json | The same sign-in as landfall login (it takes --url and --save too), but it prints the sign-in address and then the outcome as JSON lines on stdout, so a program can show the link itself. The console's sign-in button runs this. |
| landfall join --incident <incidentId> | Join an incident's room from your own sign-in, with no share link. It mints a share link with your sign-in, redeems it as landfall join <link> does, and attaches this folder, so the band, status line and hooks see the room at once. Prints one JSON line. The console's Join button runs this; your agent adopts the room on its next tool call. |
| landfall incidents [--all] | Your organization's open incidents, the rooms you are in first. --all also lists incidents resolved in the last 24 hours. Needs landfall login. |
| landfall brief | The room's shared context: the established and open items, who is here, the scope and focus, and the organization's instructions version, as text and as structured fields. The text is what your agent reads from get_brief. |
| landfall artifacts | The files shared in the room, with type, size, who shared them and when. |
| landfall artifact <id> [--max-chars <n>] [--bytes] | One shared file. A text file comes back as text up to --max-chars characters (20,000 by default), with how much was cut. --bytes also returns the file as base64 when it is 256 KB or smaller. |
| landfall timeline [--kind <kind>] [--limit <n>] [--before <seq>] | The room's timeline. --kind is all (the default), findings, status, beacon, people or other. --limit is how many rows (50 by default, 200 at most); --before pages back from a row's number. |
| landfall wall [--person <id|me>] | The room's shared wall: its widgets, with their data read again as you, so a widget you cannot read is listed as unavailable with the reason. --person reads one person's own dashboard instead; me is yours, and the answer lists everyone who has one. |
| landfall lb [--lb <name or ARN>] [--minutes <n>] | Load balancers read through the room's AWS connection: targets by zone with their health, and 5xx per target group (CloudWatch reports 5xx per target group, not per target). --lb picks one; --minutes is the window (60 by default, 360 at most). At most three load balancers are read. |
| landfall vote --claim <seq> --position <corroborate|contest> [--reason "<text>"] | Record your position on a staged finding, as you and never as your agent, with your own sign-in. --claim is the finding's number; --reason is one line of why, which the console asks for when you contest. The answer says whether your vote admitted the finding. |
| landfall lines claim --label "<text>" landfall lines release --claim <claimId> | Claim a line of investigation so two people do not chase the same lead, or hand one back. A line is held by a person, never an agent, so both run on your own sign-in. Two people who claim the same words claim the same line, and the second is told who has it. |
| landfall comms | The stakeholder updates drafted for the room, newest first, each as draft, approved, sent or failed. Read only: approving stays in the war room. |
| landfall brain [--q "<words>"] | The Company second brain. Without --q, what the brain holds for this room; with it, a search across your organization's brain (ten matches at most; needs landfall login). |
| landfall open <url> | Open an address in your browser, only when it is on the web host of the Landfall this CLI points at. Anything else is refused. |
| landfall watch [--tick-ms <n>] | A stream, not a one-off: it prints one JSON line whenever what you would see in the room changes (the status line, the rooms, the votes asked of you), following the room daemon's own push. The mod starts it once per session. It marks nothing as read, and it ends when its parent process is gone or its output closes. |
| landfall chart --query '<json>' | Put a metric your agent just read on the room's dashboard as a chart. --query is the read as query_signals took it (source, operation, params, connection, account, title). The mod's add-chart key runs this. Unlike the others it exits 1 when nothing was queued. |
For what the bridge actually does inside a session (the tools, the realtime loop, the Claude Code plugin), see Using Claude Code.
Environment variables
| Variable | What it does |
|---|---|
| LANDFALL_WEB_URL | The web address to sign in at. Wins over every other setting, together with LANDFALL_BASE_URL. |
| LANDFALL_BASE_URL | The API address. Wins over every other setting. |
| LANDFALL_URL | One address for both web and API, like login --url. Below the two variables above, above the saved default. |
| LANDFALL_LINK | The share link to use when none is given on the command line. |
| LANDFALL_DAEMON | Set to 0 and serve neither starts nor uses the room daemon; it keeps its own connection and its own reading position. |
| LANDFALL_STOP_HOOK | Set to block and the Stop hook refuses a conclusion while the room holds unseen news, instead of only telling you. |
Issues and contributions
Found a bug, or a harness we don't support yet? Open an issue on the GitHub repo; the CLI is developed in the open.