---
title: CLI reference
description: Every lookout command and flag as the command's own help prints them, and what each exit code means.
canonical_url: https://lookout.arcadia.is/docs/cli-reference
type: reference
section: Reference
last_updated: 2026-11-12
related:
  - https://lookout.arcadia.is/docs/cli
  - https://lookout.arcadia.is/docs/machines
  - https://lookout.arcadia.is/docs/troubleshooting
---

> Every page of these docs: https://lookout.arcadia.is/llms.txt

# CLI reference

Every lookout command and flag as the command's own help prints them, and what each exit code means.

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](https://lookout.arcadia.is/docs/cli).

## Help

```text
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 trigger NAME [--data TEXT]   fire a routine of yours from a script, with its data
  lookout secret put NAME [--from-file FILE --key KEY | --from-keychain SERVICE]
                                       from an agent's Shell: save a value as its secret, unseen
  lookout memory due [--days N]        this folder's memories not saved or confirmed lately
  lookout attachments --dry-run [--json]
                                       what the daily cleanup of stored images would remove
  lookout db compact [--dry-run]       shrink the store on disk, with the app quit
  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)
                  agent/ask select only the base mode, not the orchestration level;
                  omitted settings inherit the project's; resume keeps the chat's
  --no-multitask   pin orchestration off without changing the base mode
                  (conflicts with --mode multitask or workflows)
  --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
  --from NAME     who the chat reads the prompt as sent by (default "lookout CLI"): a
                  script names itself; a prompt from the CLI is never the USER's own words

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 | --no-browser | --recovery] [--no-wait] [--name NAME] [--replace MACHINE] [--share|--no-share] [--api URL] [--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] [--yes] [--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] [--api URL] [--json]
      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] [--json]
      park live chats on a machine; they resume when it next starts
  lookout worktrees reclaim [--dry-run] [--on M] [--json]
      free the disk archived chats' worktrees hold: each clean one goes, its branch kept while it has commits merged nowhere; a tree with changes, or a chat at work, stays. --dry-run lists them with their size and removes nothing
  lookout providers [sync|use-account P|keep P|keep-local P|import-key P --keychain SERVICE [--keychain-account A] [--models M,...] [--budget USD]|models P [--on ID] [--off ID] [--reset ID]] [--json]
      this machine's providers from your account
  lookout providers custom [list|add NAME --url URL --format chat|responses|messages [--key-stdin|--keychain SERVICE [--keychain-account A]] [--models M,... [--context TOKENS]]|models ID --models M,... [--context TOKENS]|test ID MODEL|remove ID] [--json]
      model hosts you add yourself: a base URL, its API format (chat, responses or messages), a key checked with the host first, and its models; they sync with 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 [--cursor end]] [--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, its conversation with --cursor end, --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|--cd DIR] [-m|--model MODEL] [--effort E] [--mode X] [--no-multitask] [--from NAME] [--detach] [--json] [--detail]
      run the prompt on machine M and follow its turns, Tasks, watches and pending wakes (questions are skipped); parked work and surviving background commands are reported, not waited on; --detach prints the thread id and leaves it running; --detail shows a provider's failure in its own words
  lookout check CHAT|TASK_ID [--parent CHAT] [--on M] [--tail N] [--json] [--detail] | lookout check CHAT --record --json [--on M]
      read a chat's state and last N entries (default 40), or an exact Task id's whole recorded result (not its summary); --parent CHAT disambiguates a Task; --record --json reads the complete retained raw chat record, not an attestation; exit 0 means the read succeeded, not approval or all work finished; --detail shows a chat's provider failure in its own words
  lookout steer CHAT [TEXT] [--from NAME] [--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 MODEL] [--effort E] [--mode X] [--no-multitask] [--on M] [--json]
      change a chat's model, effort, base mode or orchestration level
  lookout read THREAD [--on M] [--json]
      mark a chat read on machine M: its finished dot clears
  lookout answer THREAD [OPTION...] [--skip] [--from NAME] [--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 introductions AGENT [remove OTHER] [--json]
      the agents an agent was introduced to beyond its team (by your @mention in its chat, a message it received, or messages before introductions), with how and when; remove OTHER takes one away (yours alone: from a chat's Shell it is refused)
  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.arcadia.is/docs (lookout docs TOPIC prints a page's address; --md prints the page)
Help and feedback: feedback@arcadia.is
```

## Commands

### lookout exec

```text
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)
                  agent/ask select only the base mode, not the orchestration level;
                  omitted settings inherit the project's; resume keeps the chat's
  --no-multitask   pin orchestration off without changing the base mode
                  (conflicts with --mode multitask or workflows)
  --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
  --from NAME     who the chat reads the prompt as sent by (default "lookout CLI"): a
                  script names itself; a prompt from the CLI is never the USER's own words

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|--cd DIR] [-m|--model MODEL] [--effort E] [--mode X] [--no-multitask] [--from NAME] [--detach] [--json] [--detail]
  run the prompt on machine M and follow its turns, Tasks, watches and pending wakes (questions are skipped); parked work and surviving background commands are reported, not waited on; --detach prints the thread id and leaves it running; --detail shows a provider's failure in its own words
```

### lookout resume

```text
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)
                  agent/ask select only the base mode, not the orchestration level;
                  omitted settings inherit the project's; resume keeps the chat's
  --no-multitask   pin orchestration off without changing the base mode
                  (conflicts with --mode multitask or workflows)
  --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
  --from NAME     who the chat reads the prompt as sent by (default "lookout CLI"): a
                  script names itself; a prompt from the CLI is never the USER's own words

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

```text
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

```text
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

```text
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

```text
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 trigger

```text
usage: lookout trigger NAME [--data TEXT | --data -] [--agent AGENT | --chat CHAT] [--json]
  fire a routine that runs when a script fires it: its chat wakes with the routine's
  prompt and the data, as data a script sent (Check first reads it on stdin); this
  machine only. From a command of the agent's or the chat's own, its token is in the
  environment ($LOOKOUT_TRIGGER_<NAME>); from a terminal of yours, name whose it is
  --data TEXT       the event's data: text or JSON, at most 64 KB; - reads stdin
  --agent AGENT     the agent whose routine NAME is (its name or id)
  --chat CHAT       the chat whose routine NAME is
  --json            the answer as JSON
  exit 0 fired; 2 no such trigger, paused, or another trigger's token; 1 the agent
  is paused or at a limit you set, or no Lookout runs here
```

### lookout secret

```text
usage: lookout secret put NAME [--from-file FILE --key KEY | --from-keychain SERVICE [--account ACCOUNT]]
  from an agent's Shell, save a value as that agent's secret NAME without the value ever
  being shown: Lookout reads it, and a card asks the owner to save it, saying it comes
  from your Shell and what you named as its source, and the value's length, never the
  value. Once saved, the next Shell command has it as $NAME and output shows it as
  [secret:NAME]. The value comes from one of:
  (stdin)           a command's output piped in, UTF-8: some-command | lookout secret put NAME
  --from-file FILE  one key of a dotenv (KEY=VALUE lines) or JSON file
  --key KEY         that key (in JSON, a dotted path reaches a nested one)
  --from-keychain SERVICE
                    a generic password in the macOS login keychain, read with the system's
                    security tool only if macOS lets that tool read it without asking; any
                    other item, a missing one or a locked keychain is refused, never asked for
  --account ACCOUNT the Keychain item's account, when SERVICE names several
  NAME is a shell variable's name: letters, digits and _, not starting with a digit, at
  most 64, not the shell's or Lookout's own. It prints saved, declined or waiting, never
  the value or its length. Use it instead of reading a credential yourself. After the
  owner's not now, the same NAME is refused for 10 minutes
  exit 0 saved; 1 the owner declined, or refused (it says why); 2 waiting: the card waits
  in the agent's chat, and Lookout holds the value until the owner answers
```

### lookout memory

```text
usage: lookout memory due [--days N]
  list the topics of this folder's memory (in an agent's folder, the agent's own) that
  nothing saved or confirmed in the last N days, oldest first: one a line with its date,
  file, name and description, and nothing when none is. It changes nothing
  --days N          how many days back count (default 7)
```

### lookout attachments

```text
usage: lookout attachments --dry-run [--json]
  count this machine's stored images and files (its attachments folder) by what names
  them: a chat that is not archived, only archived chats, only other records (a Task's
  record, a memory, the action log), or nothing, 7 days old or not; and the browser's
  screenshots only the chat view shows, by age. Once a day the app removes a file
  nothing names once it is 7 days old; this removes nothing and opens the store read-only
  --dry-run         count, never delete (the only form)
  --json            the counts as one JSON object
  exit 0 counted; 1 no store, or one the cleanup would not judge now (it says why)
```

### lookout db

```text
usage: lookout db compact [--dry-run]
  rewrite this machine's store (lookout.db) without its free pages, in the mode that gives
  space back by itself later. Run it with the app quit: it refuses while the app or a
  lookout run holds the store, or with less free disk than the store plus 1 GB. It writes
  a compacted copy beside the store, checks it (integrity, every table's rows), then
  swaps it in; the original stays beside it until Lookout next starts. Any failure leaves
  the store as it was
  --dry-run         what it would need and do; changes nothing
  exit 0 compacted (or the dry run printed); 1 refused or failed, the store untouched
```

### lookout link

```text
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

```text
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
```

### lookout login

```text
usage: lookout login [--account NAME | --browser | --no-browser | --recovery] [--no-wait] [--name NAME] [--replace MACHINE] [--share|--no-share] [--api URL] [--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

```text
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

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

### lookout recovery-key

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

### lookout upgrade

```text
usage: lookout upgrade [--to VERSION] [--on M] [--api URL] [--json]
  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

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

### lookout usage

```text
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

```text
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

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

### lookout rename

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

### lookout remove

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

### lookout share

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

### lookout providers

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

usage: lookout providers custom [list|add NAME --url URL --format chat|responses|messages [--key-stdin|--keychain SERVICE [--keychain-account A]] [--models M,... [--context TOKENS]]|models ID --models M,... [--context TOKENS]|test ID MODEL|remove ID] [--json]
  model hosts you add yourself: a base URL, its API format (chat, responses or messages), a key checked with the host first, and its models; they sync with your account
  --format   chat (URL/chat/completions), responses (URL/responses) or messages (Anthropic's, URL/v1/messages)
  the key    (--key-stdin, or --keychain SERVICE) is checked against the host's model list before anything is kept;
             a key the host refuses, or a host Lookout can't reach, keeps nothing
  the id     custom-<slug of NAME>, fixed when it is added; its models are custom-<slug>/MODEL in every model picker
  sync       each one roams to your other devices sealed in your account's vault, its key and models inside
```

### lookout sessions

```text
usage: lookout sessions [WORDS] [--on M] [--project ID] [--json] | from a chat: lookout sessions [--fleet|--chat ID [--cursor end]] [--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, its conversation with --cursor end, --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

```text
usage: lookout check CHAT|TASK_ID [--parent CHAT] [--on M] [--tail N] [--json] [--detail] | lookout check CHAT --record --json [--on M]
  read a chat's state and last N entries (default 40), or an exact Task id's whole recorded result (not its summary); --parent CHAT disambiguates a Task; --record --json reads the complete retained raw chat record, not an attestation; exit 0 means the read succeeded, not approval or all work finished; --detail shows a chat's provider failure in its own words
```

### lookout steer

```text
usage: lookout steer CHAT [TEXT] [--from NAME] [--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: agents by name or id, chats by title, lane or chat id; 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, an
                                   agent's id (agt_...) or name on any of the USER's machines, 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 reads TEXT as a follow-up from you, its lead; 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.
  From a script or a terminal, the chat reads TEXT as a message from "lookout CLI", never as the USER's words;
  --from NAME names the script.
```

### lookout stop

```text
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

```text
usage: lookout set THREAD [-m|--model MODEL] [--effort E] [--mode X] [--no-multitask] [--on M] [--json]
  change a chat's model, effort, base mode or orchestration level
  --mode agent|ask selects only the base mode, leaving orchestration unchanged;
  --mode multitask selects Agent with Multitask on. Omitted settings stay as they are,
  including project inheritance. --no-multitask pins orchestration off without changing
  the base mode; it conflicts with --mode multitask.
```

### lookout answer

```text
usage: lookout answer THREAD [OPTION...] [--skip] [--from NAME] [--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

```text
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

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

### lookout capacity

```text
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] [--workflows on|off] [--reset] [--json]
  a machine's load and its limits on delegated turns (set them, hold on paths, drain it, or cordon it)
```

### lookout service

```text
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

```text
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

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

### lookout worktrees

```text
usage: lookout worktrees reclaim [--dry-run] [--on M] [--json]
  free the disk archived chats' worktrees hold: each clean one goes, its branch kept while it has commits merged nowhere; a tree with changes, or a chat at work, stays. --dry-run lists them with their size and removes nothing
```

## 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 state, what to do next, its todos, background work and last reply. `--cursor end` prints the end of its conversation instead. 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:

```json
{
  "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,
      "asking": { "id": "ask_1a2b3c4d", "question": "the question it asked, still unanswered", "at": "2026-10-18T11:40:00.000Z" }
    }
  ],
  "total": 1,
  "cursor": "2026-10-18T12:00:05.000Z",
  "notes": ["machines that didn't answer, with --fleet"]
}
```

`error`, `next`, `result`, `lastReplyCut`, `unreachable` and `asking` appear only when they apply. `asking` is a question the chat asked the agent that started it and nobody has answered yet, with the time it asked: then `stateLine` starts with `waiting on its question to you since` and that time (to the agent by its name when the chat isn't yours), and `next` says how to answer it. `--chat` answers `{ "chat", "view": "chat", "cursor", "session" }`, where `session` is one row plus `mode`, `branch`, `todos`, `background` and `conversation` (its last lines, oldest first), with or without `--cursor end`. `--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.

## Check a chat or Task

`lookout check CHAT --json [--on M]` returns `kind: "chat"`, the thread, a bounded tail of entries (40 by default, `--tail N` from 1 to 500), and the server's current state. This includes `tasks`, `backgroundPending`, `wakePending`, `watching`, `watches`, `shells`, `queue`, `queuePaused`, `queueRev`, `pendingQuestion`, `pendingLogin` and `lane` when present. `live: false` says no model turn is live, not that every job is finished. The lane can still be parked, a wake can be pending, and input can remain queued or paused. Exit 0 means the read succeeded, not approval or task completion.

`lookout check TASK_ID --json [--on M]` reads an **exact Task id** and returns:

```json
{
  "kind": "task",
  "machine": "machine name",
  "parent": { "threadId": "parent chat id", "projectId": "project id", "title": "parent title" },
  "task": {
    "id": "exact Task id",
    "status": "completed",
    "result": "the whole authoritative recorded result",
    "summary": "the separate card summary"
  },
  "record": { "spawnSeq": 12, "doneSeq": 29 }
}
```

`task` also carries the existing run facts, such as timestamps, transcript reference, model/effort choice, interruption, resumability and waiting state when recorded. A queued spawn also carries `queued: true`. `record` names this run's latest spawn and end sequences in the parent's retained log. A later spawn clears the earlier result: while that generation runs, `result` and `doneSeq` are null. A finished generation with no recorded result also returns null, never a summary substituted as a result. The command does not read the worker's transcript to invent a final response.

Task prefixes are not accepted. A similarly titled chat is not a match. Exact chat ids take precedence over prefixes; an exact Task/chat collision or multiple parents recording the exact same Task id is refused. Use `--parent CHAT` to select the Task's parent. `--tail` and `--detail` apply only to chat reads. A Task read without `--json` prints the same recorded result and its current status.

The recorded result is not always the unabridged model message. A foreground Task records its report before offloading the tool response; a background Task can offload a report above 24,000 characters **before recording it**. In that case `result` is the exact recorded preview plus its recovery reference. The command preserves that reference verbatim, does not automatically read paths mentioned in the text, and does not promise that a referenced file still exists.

## Complete retained record

`lookout check CHAT --record --json [--on M]` reads the existing raw export through the same authenticated transport. It returns `kind: "record"`, `machine`, `record` and `observed`. It takes no `--tail`, `--detail` or `--parent`.

- `record.format` is `lookout-retained-record/1`. `record.entries` contains **every retained row** in sequence order with full payloads, including opening user/context references, later delivered inputs, responses, configuration history, `head.item`, replay snapshots and provider-native state. It does not load files referenced by those rows.
- `record.snapshot` carries `at` (server time in epoch milliseconds), `endSeq` (the last retained entry's sequence, or 0), and `entries` (the retained count). The raw `thread`, `project` and `todos` are included at that snapshot.
- `observed` is a **separate, later state read**, with its own `now`. Its pending queue has not necessarily been delivered into the record. It may change while the record crosses the network.

This is a retained snapshot, not an immutable all-time history or a no-later-steering attestation. Rewind can delete rows. Accepted, normalized inputs can differ from the caller's argv or stdin. A response item's `producer.provider`, `producer.model`, `producer.wireModel` and recorded request/configuration effort are execution evidence; mutable thread defaults, `lastReply` excerpts and partial text are not proof of a completed final. Effort is requested/configured, not proof that a provider complied. A patch id in an opening prompt remains the caller's assertion. No independent-review or verified-patch claim is synthesized.

Large reads remain subject to the existing transport's response-size limits; an oversized relayed answer is refused, not silently shortened. Raw records can contain private context, file contents and provider replay data. Treat the output accordingly.

## Exec's return boundary

Both local and `--on` exec follow live turns, running Tasks, active watches and pending wake debounce. They do not wait for an ordinary persistent background server to exit. Parked work, remaining input and surviving shells are reported rather than represented as universal completion. JSON `run_end.state` preserves the last observed lifecycle facts, including the lane's parked state and the pending queue; `run_end.shells` retains the surviving-command list. The exit code describes the observed turn's stop reason. `--detach` still returns immediately after creation, not after execution.

## 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 succeeded; a run's observed turn ended normally. A successful read does not approve work or assert completion. | 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. |

## Related

- [CLI](https://lookout.arcadia.is/docs/cli.md): The lookout command on Linux and macOS: install it, sign in, run chats, and use it in scripts.
- [Machines](https://lookout.arcadia.is/docs/machines.md): Run chats on your other Macs and on your servers, from the app or the terminal.
- [Troubleshooting](https://lookout.arcadia.is/docs/troubleshooting.md): Find your symptom and its fix, run the doctor check, and collect what to send when you need help.
