Reference
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.
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 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: [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)
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 wordslookout 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)
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
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 clearslookout 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 directlylookout 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 Shelllookout trigger
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 herelookout secret
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 answerslookout memory
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
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
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 untouchedlookout 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 browserlookout login
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 Maclookout 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] [--yes] [--json]
the devices on your account; approve one asking to join (its link), remove one, or the loglookout recovery-key
usage: lookout recovery-key [rotate]
when your Recovery Key was set; rotate makes a new onelookout upgrade
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 itlookout status
usage: lookout status [--json]
your account, this machine, and how your other devices see itlookout 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-bufferedlookout 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, offlinelookout 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)lookout share
usage: lookout share [on|off] [--json]
use this machine from your other devices: on or offlookout 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]|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 insidelookout sessions
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
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 wordslookout steer
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
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 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
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 itlookout 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 waylookout doctor
usage: lookout doctor [--on M] [--json] | lookout doctor --head CHAT [--on M] [--json]
preflight: providers, git identity and credentials, toolchains, capacity, disklookout 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] [--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
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 systemdlookout 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] [--json]
park live chats on a machine; they resume when it next startslookout worktrees
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 nothingSessions 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.
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,
"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:
{
"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.
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. |