CLI reference | Lookout Docs

The lookout command's help, as it prints it. In a terminal, lookout --help prints this sheet and lookout VERB --help one command's usage. To install the command and run it, see CLI.

Help

lookout <version>: run a prompt without the app, or Lookout on any machine of your account

usage:
  lookout exec [PROMPT] [options]      run a prompt in a workspace (default command)
  lookout resume THREAD [PROMPT]       send a follow-up to an existing thread
  lookout print THREAD                 show an existing thread (no model call)
  lookout read THREAD...               mark chats read: their finished dot clears
  lookout archive THREAD... [--restore]
                                       archive chats out of the sidebar (or restore them)
  lookout handoff CHAT... --to AGENT [--on M]
                                       hand chats to a Lookout agent: it hears and steers them
  lookout link [--json]                a one-time link that signs a browser in here
  lookout docs [TOPIC] [--md] [--open] the docs: their address and pages, or one page

prompt:
  PROMPT, or - to read it from stdin. Piped stdin with no prompt is read too;
  piped stdin beside a prompt is appended to it when it starts arriving
  within a second (an open stdin that sends nothing is not waited on).
  A single word is never a prompt on its own: lookout exec summarize.

options:
  -C, --cd DIR    workspace directory, which must exist (default: current directory; exec only)
  -m, --model ID  model id (default: the project's; resume switches the thread)
  --effort LEVEL  reasoning effort (default: the project's; resume switches it)
  --mode MODE     agent | ask | multitask (agent with Multitask on)
                  | workflows (agent at the Workflows level: a lab feature, LOOKOUT_WORKFLOWS=on)
                  (default: the project's; resume switches it)
  --json          stream JSONL events instead of human text
  --detail        a provider's failure in its own words (default: its kind and provider)
  -o, --output-last-message FILE
                  write the run's last assistant message to FILE

Questions the model asks are skipped: headless runs never wait on input.
Every run persists its thread; the footer prints its id for resume and print.
Nothing reads or archives a chat on its own: read and archive are explicit.
They go through the running Lookout, so every open window shows the change;
with none running, they change the saved chats directly.

exit codes: 0 done, 1 turn error, 2 usage, 3 quota spent, 4 sign-in needed,
  5 machine unavailable, 6 account service unreachable, 130 stopped.

machines (run Lookout on any machine of your account):
  lookout login [--account NAME | --browser | --recovery] [--no-wait] [--name NAME] [--replace MACHINE] [--share|--no-share] [--json]
      add this machine to your account: sign in with your browser, or (--account, over ssh) ask your Mac to add it; it prints a code and a link to open on your Mac
  lookout logout [--keep-providers] [--yes] [--json]
      this machine leaves your account (re-keys, revokes its session, deletes its keys, signs out of the providers your account gave it)
  lookout link [--json]
      print a one-time link that signs a browser in to the Lookout server running on this machine (works once, for 10 minutes)
  lookout devices [approve LINK|remove NAME|log] [--json]
      the devices on your account; approve one asking to join (its link), remove one, or the log
  lookout recovery-key [rotate]
      when your Recovery Key was set; rotate makes a new one
  lookout upgrade [--to VERSION] [--on M]
      install the latest signed release (never an older one unless a signed rollback names it); --to VERSION installs that one, older too; --on M parks that machine first, then upgrades it
  lookout park [--on M]
      park live chats on a machine; they resume when it next starts
  lookout providers [sync|use-account P|keep P|keep-local P|import-key P --keychain SERVICE [--keychain-account A] [--models M,...] [--budget USD]] [--json]
      this machine's providers from your account
  lookout status [--json]
      your account, this machine, and how your other devices see it
  lookout usage [PROVIDER] [--on M] [--json] | lookout usage --follow [--provider P] [--for SECONDS] [--on M]
      what each provider's plan has left, and at the last two hours' pace when it runs out and reopens; --json is lookout_usage's answer. --follow prints a line per change (an account spent or open again, a weekly or 5-hour meter past a 5-point step, the serving account, chats pinned to an excluded account; ALERT: an excluded account serving, no account under the failover line, an API key refused for credit) for --for seconds (default 1800), then a last line and exit 0; ids only, for a Shell watch or grep --line-buffered
  lookout up [--name NAME] [--port N] [--share|--no-share] [--agents-host]
      keep this machine on your account so your other devices can run chats on it (the installer's service runs this)
  lookout machines [--json]
      your machines: online, degraded, asleep, offline
  lookout rename [MACHINE] NAME [--json]
      rename this machine (or MACHINE)
  lookout remove MACHINE [--json]
      remove a machine from your account (revokes its session)
  lookout share [on|off] [--json]
      use this machine from your other devices: on or off
  lookout sessions [WORDS] [--on M] [--project ID] [--json] | from a chat: lookout sessions [--fleet|--chat ID] [--state S] [--since T] [--on M] [--json] [--detail]; lookout sessions --models [--cursor N] [--json]; lookout sessions --changes ID [--scope chat|turn|uncommitted] [--cursor N] [--on M] [--json]
      chats on a machine; WORDS keeps the ones matching any of them (a word of the title or lane key, a chat id prefix, @agent), live first, then the last 14 days. From a chat's Shell or a routine's check, no WORDS: that chat's own chats as Sessions reads them (--fleet its projects' chats, --chat one in depth, --models the models that run with their efforts and plans, --changes ID a chat's changed files and diffs; --state and --since filter; --json for scripts; --detail adds a failure's provider words)
  lookout exec --on M [PROMPT] [-C DIR] [-m MODEL] [--effort E] [--mode X] [--detach] [--json] [--detail]
      run the prompt on machine M and follow it there (questions are skipped); --detach prints the thread id and leaves it running; --detail shows a provider's failure in its own words
  lookout check THREAD [--on M] [--tail N] [--json] [--detail]
      a chat's state (working, needs you, done, idle) and its last N entries (default 40); a question it waits on, with its options; --detail shows a provider's failure in its own words
  lookout steer CHAT [TEXT] [--request] [--on M] [--json] | lookout steer --reply MESSAGE_ID [TEXT]
      send TEXT (or stdin) to a chat: a running turn takes it at its next step, an idle chat starts a turn with it
  lookout stop THREAD [--on M] [--json]
      stop a chat's running turn and its background runs (messages waiting for it stay in its queue)
  lookout set THREAD [-m MODEL] [--effort E] [--mode X] [--on M] [--json]
      change a chat's model, effort or mode
  lookout read THREAD [--on M] [--json]
      mark a chat read on machine M: its finished dot clears
  lookout answer THREAD [OPTION...] [--skip] [--on M] [--json]
      answer the question a chat waits on, one OPTION (an id or a label) per question in order; or --skip it
  lookout files ls CHAT [PATH] [--on M] [--json] | lookout files get CHAT PATH [--to FILE [--overwrite]] [--on M] | lookout files put CHAT PATH [--from FILE] [--overwrite] [--on M] [--json]
      a chat's workspace on any machine: ls a folder, get a file (to stdout, or --to FILE), put a file (--from FILE or stdin; the chat's starter or you); a credential is refused either way
  lookout doctor [--on M] [--json] | lookout doctor --head CHAT [--on M] [--json]
      preflight: providers, git identity and credentials, toolchains, capacity, disk
  lookout capacity [--on M] [--max N] [--per-project N] [--per-client N] [--memory-pressure LEVEL] [--cpu-pressure PCT] [--load-per-core N] [--mem-min MB] [--hold-paths PATH,...] [--auto-resume on|off] [--auto-update on|off] [--drain on|off] [--cordon on|off] [--agents on|off] [--agents-only on|off] [--agents-max N|default] [--reset] [--json]
      a machine's load and its limits on delegated turns (set them, hold on paths, drain it, or cordon it)
  lookout service [--on M] [--memory-max SIZE] [--memory-high SIZE] [--cpu-weight N] [--io-weight N] [--reset] [--json]
      Linux: the memory, CPU and IO limits on a machine's Lookout service and everything it starts (its systemd slice), read back from systemd
  lookout git setup [--name NAME --email EMAIL] [--host HOST --token-stdin [--user USER]] [--json]
      give this machine a git identity and a credential for a forge (the token comes on stdin)

  --on takes a machine name or id, or local/this/self for this machine
  (LOOKOUT_MACHINE sets the default for every verb, exec included; else this machine).
  exec --on this machine works in the current folder (its project, reused every run);
  on another machine -C takes a path that must exist there (absolute, or ~/...), and
  without -C every run shares one scratch project ("lookout exec").
  Where the Lookout app runs signed in, none of this needs lookout login: this machine's
  verbs go to the app, another machine's through it (devices, recovery-key and remove stay in the app).
  From a chat's Shell they go through the Lookout running the chat, as that chat.
  Flags take --flag value or --flag=value. Errors go to stderr; the exit code is the class.
  exit 5: the machine is unavailable (offline, asleep, signed out, not answering).
  exit 6: the Lookout account service is unreachable.

Words that start with a command (status, stop, check...) run it unless the prompt is quoted:
  lookout "stop the flaky test from retrying"
lookout VERB --help prints one verb's usage.
Docs: https://lookout.itoowasinarcadia.com/docs (lookout docs TOPIC prints a page's address; --md prints the page)
Help and feedback: [email protected]

Commands

lookout exec

usage: lookout exec [PROMPT] [options]
  run a prompt in a workspace (default command); the run ends when the chat goes quiet

prompt:
  PROMPT, or - to read it from stdin. Piped stdin with no prompt is read too;
  piped stdin beside a prompt is appended to it when it starts arriving
  within a second (an open stdin that sends nothing is not waited on).
  A single word is never a prompt on its own: lookout exec summarize.

options:
  -C, --cd DIR    workspace directory, which must exist (default: current directory; exec only)
  -m, --model ID  model id (default: the project's; resume switches the thread)
  --effort LEVEL  reasoning effort (default: the project's; resume switches it)
  --mode MODE     agent | ask | multitask (agent with Multitask on)
                  | workflows (agent at the Workflows level: a lab feature, LOOKOUT_WORKFLOWS=on)
                  (default: the project's; resume switches it)
  --json          stream JSONL events instead of human text
  --detail        a provider's failure in its own words (default: its kind and provider)
  -o, --output-last-message FILE
                  write the run's last assistant message to FILE

Questions the model asks are skipped: headless runs never wait on input.
Every run persists its thread; the footer prints its id for resume and print.

usage: lookout exec --on M [PROMPT] [-C DIR] [-m MODEL] [--effort E] [--mode X] [--detach] [--json] [--detail]
  run the prompt on machine M and follow it there (questions are skipped); --detach prints the thread id and leaves it running; --detail shows a provider's failure in its own words

lookout resume

usage: lookout resume THREAD [PROMPT] [options]
  send a follow-up to an existing thread and follow it until it goes quiet; a turn
  already running there takes it as steering; the thread keeps its workspace (no -C)

prompt:
  PROMPT, or - to read it from stdin. Piped stdin with no prompt is read too;
  piped stdin beside a prompt is appended to it when it starts arriving
  within a second (an open stdin that sends nothing is not waited on).
  A single word is never a prompt on its own: lookout exec summarize.

options:
  -C, --cd DIR    workspace directory, which must exist (default: current directory; exec only)
  -m, --model ID  model id (default: the project's; resume switches the thread)
  --effort LEVEL  reasoning effort (default: the project's; resume switches it)
  --mode MODE     agent | ask | multitask (agent with Multitask on)
                  | workflows (agent at the Workflows level: a lab feature, LOOKOUT_WORKFLOWS=on)
                  (default: the project's; resume switches it)
  --json          stream JSONL events instead of human text
  --detail        a provider's failure in its own words (default: its kind and provider)
  -o, --output-last-message FILE
                  write the run's last assistant message to FILE

Questions the model asks are skipped: headless runs never wait on input.
Every run persists its thread; the footer prints its id for resume and print.

lookout print

usage: lookout print THREAD [--json] [--detail]
  show an existing thread (no model call): prompts, replies, tool calls, errors, turn ends
  --json   the thread, its entries and its todos as one JSON object
  --detail a provider's failure in its own words (default: its kind and provider)

lookout read

usage: lookout read THREAD... [--json]
  mark chats read: their finished dot clears
  through the running Lookout, so every open window shows the change; with
  none running, it changes the saved chats directly

usage: lookout read THREAD [--on M] [--json]
  mark a chat read on machine M: its finished dot clears

lookout archive

usage: lookout archive THREAD... [--restore] [--json]
  archive chats out of the sidebar; --restore brings them back
  through the running Lookout, so every open window shows the change; with
  none running, it changes the saved chats directly

lookout handoff

usage: lookout handoff CHAT... --to AGENT [--on M] [--json]
       lookout handoff --lane-prefix PREFIX --to AGENT [--on M] [--json]
  hand chats (ids or lane keys, or every unarchived chat on a lane prefix) to a Lookout agent
  on this machine: they join its Sessions, it hears each once it settles, and its Steer acts
  on them; any other agent's hold on them ends. --on M: the machine that holds the chats
  (they are judged and marked there first). Any chat but an agent's own; never from a
  chat's Shell

lookout link

usage: lookout link [--json]
  print a one-time link that signs a browser in to the Lookout server running on this machine (works once, for 10 minutes)

lookout docs

usage: lookout docs [TOPIC] [--md] [--open]
  the docs' address and their pages; with TOPIC (a page's name or title), that page's address
  --md     print the page as Markdown instead (no TOPIC: every page in one file)
  --open   open it in this machine's browser

usage: lookout login [--account NAME | --browser | --recovery] [--no-wait] [--name NAME] [--replace MACHINE] [--share|--no-share] [--json]
  add this machine to your account: sign in with your browser, or (--account, over ssh) ask your Mac to add it; it prints a code and a link to open on your Mac

lookout logout

usage: lookout logout [--keep-providers] [--yes] [--json]
  this machine leaves your account (re-keys, revokes its session, deletes its keys, signs out of the providers your account gave it)

lookout devices

usage: lookout devices [approve LINK|remove NAME|log] [--json]
  the devices on your account; approve one asking to join (its link), remove one, or the log

lookout recovery-key

usage: lookout recovery-key [rotate]
  when your Recovery Key was set; rotate makes a new one

lookout upgrade

usage: lookout upgrade [--to VERSION] [--on M]
  install the latest signed release (never an older one unless a signed rollback names it); --to VERSION installs that one, older too; --on M parks that machine first, then upgrades it

lookout status

usage: lookout status [--json]
  your account, this machine, and how your other devices see it

lookout usage

usage: lookout usage [PROVIDER] [--on M] [--json] | lookout usage --follow [--provider P] [--for SECONDS] [--on M]
  what each provider's plan has left, and at the last two hours' pace when it runs out and reopens; --json is lookout_usage's answer. --follow prints a line per change (an account spent or open again, a weekly or 5-hour meter past a 5-point step, the serving account, chats pinned to an excluded account; ALERT: an excluded account serving, no account under the failover line, an API key refused for credit) for --for seconds (default 1800), then a last line and exit 0; ids only, for a Shell watch or grep --line-buffered

lookout up

usage: lookout up [--name NAME] [--port N] [--share|--no-share] [--agents-host]
  keep this machine on your account so your other devices can run chats on it (the installer's service runs this)

lookout machines

usage: lookout machines [--json]
  your machines: online, degraded, asleep, offline

lookout rename

usage: lookout rename [MACHINE] NAME [--json]
  rename this machine (or MACHINE)

lookout remove

usage: lookout remove MACHINE [--json]
  remove a machine from your account (revokes its session)

usage: lookout share [on|off] [--json]
  use this machine from your other devices: on or off

lookout providers

usage: lookout providers [sync|use-account P|keep P|keep-local P|import-key P --keychain SERVICE [--keychain-account A] [--models M,...] [--budget USD]] [--json]
  this machine's providers from your account

lookout sessions

usage: lookout sessions [WORDS] [--on M] [--project ID] [--json] | from a chat: lookout sessions [--fleet|--chat ID] [--state S] [--since T] [--on M] [--json] [--detail]; lookout sessions --models [--cursor N] [--json]; lookout sessions --changes ID [--scope chat|turn|uncommitted] [--cursor N] [--on M] [--json]
  chats on a machine; WORDS keeps the ones matching any of them (a word of the title or lane key, a chat id prefix, @agent), live first, then the last 14 days. From a chat's Shell or a routine's check, no WORDS: that chat's own chats as Sessions reads them (--fleet its projects' chats, --chat one in depth, --models the models that run with their efforts and plans, --changes ID a chat's changed files and diffs; --state and --since filter; --json for scripts; --detail adds a failure's provider words)

lookout check

usage: lookout check THREAD [--on M] [--tail N] [--json] [--detail]
  a chat's state (working, needs you, done, idle) and its last N entries (default 40); a question it waits on, with its options; --detail shows a provider's failure in its own words

lookout steer

usage: lookout steer CHAT [TEXT] [--request] [--on M] [--json] | lookout steer --reply MESSAGE_ID [TEXT]
  send TEXT (or stdin) to a chat: a running turn takes it at its next step, an idle chat starts a turn with it
From a chat's Shell, send to another of the USER's Lookout chats or agents, only when the USER asks you to:
  lookout sessions WORDS           find it: chats matching WORDS (title, lane, chat id or @agent), live first,
                                   then the last 14 days, at most 10. No WORDS: your own chats.
  lookout steer CHAT [TEXT]        send TEXT (or stdin for long text: <<'EOF' ... EOF). CHAT is a chat id, or a
                                   title or lane that matches one chat. A running chat reads it at its next step;
                                   an idle one starts a turn on it. --request: you want the result back.
  lookout steer --reply ID [TEXT]  answer the <agent_message> whose message_id is ID; no address needed.
  A chat you started takes TEXT as a follow-up from the USER; any other chat or agent reads it as a message from
  your chat. A reply arrives in your chat as an <agent_message>: don't wait, sleep or poll for it.

lookout stop

usage: lookout stop THREAD [--on M] [--json]
  stop a chat's running turn and its background runs (messages waiting for it stay in its queue)

lookout set

usage: lookout set THREAD [-m MODEL] [--effort E] [--mode X] [--on M] [--json]
  change a chat's model, effort or mode

lookout answer

usage: lookout answer THREAD [OPTION...] [--skip] [--on M] [--json]
  answer the question a chat waits on, one OPTION (an id or a label) per question in order; or --skip it

lookout files

usage: lookout files ls CHAT [PATH] [--on M] [--json] | lookout files get CHAT PATH [--to FILE [--overwrite]] [--on M] | lookout files put CHAT PATH [--from FILE] [--overwrite] [--on M] [--json]
  a chat's workspace on any machine: ls a folder, get a file (to stdout, or --to FILE), put a file (--from FILE or stdin; the chat's starter or you); a credential is refused either way

lookout doctor

usage: lookout doctor [--on M] [--json] | lookout doctor --head CHAT [--on M] [--json]
  preflight: providers, git identity and credentials, toolchains, capacity, disk

lookout capacity

usage: lookout capacity [--on M] [--max N] [--per-project N] [--per-client N] [--memory-pressure LEVEL] [--cpu-pressure PCT] [--load-per-core N] [--mem-min MB] [--hold-paths PATH,...] [--auto-resume on|off] [--auto-update on|off] [--drain on|off] [--cordon on|off] [--agents on|off] [--agents-only on|off] [--agents-max N|default] [--reset] [--json]
  a machine's load and its limits on delegated turns (set them, hold on paths, drain it, or cordon it)

lookout service

usage: lookout service [--on M] [--memory-max SIZE] [--memory-high SIZE] [--cpu-weight N] [--io-weight N] [--reset] [--json]
  Linux: the memory, CPU and IO limits on a machine's Lookout service and everything it starts (its systemd slice), read back from systemd

lookout git

usage: lookout git setup [--name NAME --email EMAIL] [--host HOST --token-stdin [--user USER]] [--json]
  give this machine a git identity and a credential for a forge (the token comes on stdin)

lookout park

usage: lookout park [--on M]
  park live chats on a machine; they resume when it next starts

Sessions from a chat

Run from a chat's Shell or a routine's check, lookout sessions with no words reads what that chat's Sessions tool reads: the chats it started or was handed, on any of your machines. It talks to this machine's running Lookout as that chat, never with this machine's account sign-in.

--fleet: the chats of the projects the chat's agent works on, on every machine that has them. --project ID picks one of those projects (and implies --fleet).
--chat ID: one chat in depth (its todos, background work and the end of its conversation). It takes a chat id (or its first 8 or more characters, for a chat on this machine) or a lane key.
--models: this machine's models that can run now, one line each (id, name, provider, its effort levels), then each linked account's plan state, then the models that cannot run and why: Sessions' models view. --cursor N continues a plan list a More: line cut.
--changes ID: one chat's changed files with their diffs, a page at a time: Sessions' changes view. It takes a chat id (or its first 8 or more characters, for a chat on this machine) or a lane key, on any machine you hold the chat on. --scope chat|turn|uncommitted picks the whole chat (the default), its last turn, or uncommitted work in its workspace; --cursor N takes the next page a More: line names.
--state S: only chats in state S (new, running, awaiting, queued, paused, waiting, parked, interrupted, failed, stopped, background, incomplete, open-todos, done, unknown).
--since T: only chats whose last turn ended at or after T: an ISO time, or the cursor an earlier read returned.
--on M: only chats on machine M. Another machine is read only for the chats you hold there (or your fleet's projects with --fleet). Anything else is refused with exit 2.
--detail: a failed chat's error carries message too, the provider's own words. Without it a failure is only its kind, its line and the provider that reported it: a model may read this answer, and a provider's refusal read back into a model's context reads like what it refused.

With --json the answer is one JSON object, and its fields are stable:

{
  "chat": "the calling chat's id",
  "view": "chats",
  "on": "machine name, only with --on",
  "sessions": [
    {
      "id": "chat id",
      "title": "its title",
      "lane": "lane key or null",
      "state": "failed",
      "stateLine": "failed: declined by the provider (claude)",
      "stopReason": "refusal",
      "updatedAt": "2026-10-18T12:00:00.000Z",
      "settledAt": "2026-10-18T12:00:00.000Z or null while it runs",
      "machine": "machine name",
      "model": "model id and effort",
      "project": "project name",
      "owner": "yours | handed to you | another agent's (@name) | the USER's",
      "lastReply": "its last reply in full (another machine's chat: up to 16 KB; with --fleet or from an older machine an excerpt; lastReplyCut: true when cut)",
      "result": "the object it submitted, when it was given a schema",
      "error": { "kind": "declined", "line": "declined by the provider (claude)", "code": "refusal", "provider": "claude", "message": "the provider's own words, only with --detail" },
      "next": "what to do about it, when there is something to do",
      "unreachable": true
    }
  ],
  "total": 1,
  "cursor": "2026-10-18T12:00:05.000Z",
  "notes": ["machines that didn't answer, with --fleet"]
}

error, next, result, lastReplyCut and unreachable appear only when they apply. --chat answers { "chat", "view": "chat", "cursor", "session" }, where session is one row plus mode, branch, todos, background and conversation (its last lines, oldest first). --models and --changes answer { "chat", "view", "cursor", "text" }, where text is the lines the plain form prints, Sessions' own rendering. A chat whose provider declined its request reads failed with stop reason refusal: retry it, retry it on a model of another provider, or send a reworded message.

lookout check, lookout print and lookout exec (and resume) say a provider's failure the same way, as its kind and provider; --detail shows its own words.

Exit codes

Every command exits with one of these codes, so a script can tell a finished run from a failed one.

Code	Meaning	What to do
`0`	The command finished; a run's turn ended normally.	Nothing.
`1`	The turn or the command failed; stderr says why.	Read the error, then run it again or resume the chat.
`2`	The command line was wrong: an unknown command or flag, a missing value, an unknown chat.	Run lookout VERB --help for its usage.
`3`	The model's plan ran out for now.	Wait for the plan to reset, or run with another model or account.
`4`	A sign-in is missing: the provider's, or this machine's on your Lookout account.	For a provider, sign in again in Settings › Providers (lookout providers sync brings it to another machine); for this machine, run lookout login.
`5`	The machine is offline, asleep, signed out or not answering.	Check it with lookout machines, then try again once it is online.
`6`	This machine could not reach the Lookout account service.	Check the connection, then try again.
`130`	The run was stopped (Ctrl-C, or lookout stop).	Resume the chat to carry on.

CLI: The lookout command on Linux and macOS: install it, sign in, run chats, and use it in scripts.
Machines: Run chats on your other Macs and on your servers, from the app or the terminal.
Troubleshooting: Find your symptom and its fix, run the doctor check, and collect what to send when you need help.