Surfaces
CLI
The lookout command on Linux and macOS: install it, sign in, run chats, and use it in scripts.
lookout runs a prompt from a terminal with no window, and drives Lookout on any machine of your account. It runs the same agent and writes the same chats as the Mac app. On a Mac with the app, both share chats and provider sign-ins, and while the app is open a run goes through it, so the chat shows in its sidebar as it works.
Install
On Linux or macOS, x64 or arm64:
curl -fsSL https://lookout.arcadia.is/install.sh | shThe installer checks the release's signature before it installs the release, puts lookout in ~/.local/bin, signs the machine in to your account, and installs a service that keeps it on your account. It needs curl, tar and git. If it says so, add ~/.local/bin to your PATH.
Install with no terminal
For cloud-init, CI or an agent over ssh, name your account (your username or email) and the machine:
curl -fsSL https://lookout.arcadia.is/install.sh | LOOKOUT_ACCOUNT=you LOOKOUT_NAME=vps-1 shThe installer prints a code and a link, then exits. Lookout on your Mac shows a banner, vps-1 wants to join your account: click Review, enter the code the machine printed, then click Add vps-1. The service finishes the join by itself. In the app, Add a device in Settings › Devices shows this line with your account filled in.
Installer settings
Set these before sh in the line, as above.
| Variable | What it sets |
|---|---|
LOOKOUT_ACCOUNT | The account to join, by username or email: your devices show the request, no terminal needed |
LOOKOUT_NAME | The machine's name (default: its hostname) |
LOOKOUT_REPLACE | An offline machine this one takes over, after a reinstall |
LOOKOUT_JSON=1 | With LOOKOUT_ACCOUNT, the last line is the waiting request as JSON (state, name, code, addLink) |
LOOKOUT_NO_LOGIN=1 | Skip signing in; run lookout login later |
LOOKOUT_NO_SERVICE=1 | Install no service; run lookout up yourself |
LOOKOUT_USER | As root, the user Lookout runs as (default lookout; root keeps root) |
LOOKOUT_PROJECTS_DIR | Where cloned repositories go (default ~/projects) |
LOOKOUT_VERSION | A release to install instead of the latest, older than the installed one too |
The service has no CPU or memory limits of its own. On a server shared with other work, set them with --nice, --cpu-weight, --io-weight, --memory-high or --memory-max after sh -s -- in the line, for example sh -s -- --memory-max 6G. On a Mac only --nice applies. An installed service keeps its limits through upgrades, and lookout service changes them later from any of your devices (Service limits). sh -s -- --help in place of sh prints every setting the installer takes.
Sign in
The installer signs in when it has a terminal. To sign in later, or again:
lookout loginlookout status shows the account, this machine and how your other devices see it. A machine on your account gets your providers without signing in to them. Commands that reach a machine through your account (sessions, check, steer, stop, set, answer, and any command with --on) need this machine signed in.
On a Mac with the app
While the Lookout app runs and is signed in, lookout in a terminal on that Mac needs no lookout login. Commands for this Mac (usage, check, sessions, doctor, capacity and the rest) go straight to the app, and commands for another machine (machines, rename, --on NAME) go through it, as you. Your account's devices and keys stay with the app: devices, recovery-key, remove and choosing a provider's copy (providers use-account, keep, keep-local) say to use its Settings. With the app quit, these commands need lookout login again.
In a chat's Shell on that Mac they go through the app too, as that chat, so an agent can list your machines (lookout machines) and reach them with --on NAME. A command only you run, such as rename or providers sync, says it is yours instead of asking you to log in.
Providers on this machine
The CLI has no sign-in of its own for a plan: you sign in once in the Mac app's Settings › Providers (Connect a provider), and your account carries the sign-in to every machine on it. lookout providers lists each provider and whether it runs here:
Without an account, a machine with only the CLI still runs the free models, with no sign-in (lookout exec "say hello"), and providers whose key is in its environment: On a machine with only the CLI.
A model host Lookout has no provider for is a custom provider you add yourself: its base URL, its API format (chat, responses or messages), a key piped in or read from the Keychain, and the models it serves. Lookout checks the key with the host first and never prints it:
printf %s "$KEY" | lookout providers custom add "My host" --url https://api.example.com/v1 --format chat --key-stdin --models my-model
lookout providers custom test custom-my-host my-modellookout providers custom lists what you added, models ID --models M,... adds more models, and remove ID takes one away. A model whose host doesn't say its context window needs --context TOKENS. Custom providers sync to your other devices with your account.
lookout providers models PROVIDER lists a provider's models and whether your model lists show each; --off ID, --on ID and --reset ID change one on this device. A switched-off model still runs where a chat or project already uses it: Choose which models your lists show.
Run a prompt
cd ~/projects/app
lookout exec "fix the failing test in calc.py"The agent's reply and its tool calls stream to the terminal. The run ends when the chat goes quiet, with a footer naming the chat's thread:
[stop] thread 73f05d47-fb87-48e9-99d1-1fbaf28a4759 (14.2s)Where the installer's service runs (a server, or a Mac without the app), runs go through the service: lookout exec --on local "fix the failing test", followed with the commands in Run on another machine.
Follow up on a chat
lookout resume THREAD "now add a test for it"
lookout print THREADresume sends a follow-up and follows the chat until it goes quiet. If a turn is running there, in the app for example, the message steers it. -m, --effort, --mode and --no-multitask switch the requested settings first; omitted settings stay as they are. print shows the chat without calling a model.
lookout read THREAD clears a finished chat's dot and lookout archive THREAD moves it out of the sidebar and stops what it runs (--restore brings it back, and so does lookout steer to it, except to a routine's chat that was started over, which only --restore brings back). Nothing reads or archives a chat on its own.
Wherever a command takes THREAD, the first 8 or more characters of the chat's id work too, the way git takes a short hash: lookout check 595a9ea7 --on vps-1. The machine that holds the chat finds it, and the answer names the whole id. When several chats' ids start that way, the command lists them (id, state, title, lane) and changes nothing.
lookout check TASK_ID --json also reads an exact Task's whole recorded result and current run state, with its parent chat. Task prefixes are refused; --parent CHAT disambiguates a Task when needed. lookout check THREAD --record --json reads the complete retained raw record, not an immutable history or an approval. The read contracts explain the schemas, snapshot boundaries and recorded offload references. Exit 0 from check means only that the read succeeded.
Run on another machine
With this machine signed in, by lookout login or by the app on a Mac (On a Mac with the app), --on takes any machine of your account, by name or id. A Mac takes commands once Use this Mac from your other devices is on in its Settings › Devices.
lookout machines
lookout exec --on vps-1 -C '~/projects/app' "run the tests and fix what fails"
lookout sessions --on vps-1Files in a chat's folder
lookout files reads and writes the folder a chat works in, on any machine of your account, this one included:
lookout files ls THREAD out --on vps-1
lookout files get THREAD out/report.md --on vps-1 --to report.md
lookout files put THREAD specs/plan.md --from plan.md --on vps-1lookout up keeps a machine on your account so your other devices can run chats on it; the installer's service runs it. lookout up --agents-host also runs your agents there, around the clock. lookout share off stops your other devices from using this machine.
Use it in scripts
if lookout exec -o review.md "review the changes on this branch"; then
cat review.md
fiSave a secret from an agent's Shell
In an agent's commands, lookout secret put NAME saves a value as one of that agent's secrets without the value ever reaching the chat:
gh auth token | lookout secret put GITHUB_TOKEN
lookout secret put RELEASE_KEY --from-file .env --key RELEASE_KEY
lookout secret put DEPLOY_TOKEN --from-keychain deploy-tokenFollow plan usage
lookout usage prints what each provider's plan has left. lookout usage --follow keeps reading it, once a minute, and prints a line each time something changes, so a script or an agent's Shell can wait on it:
lookout usage --follow --provider claude | grep --line-buffered ALERTUpdate
lookout upgradeIt downloads the latest release, checks its signature against the key this install already trusts, installs it and restarts the service. It never installs a release Lookout has pulled, and goes back to an older one only when Lookout signed that rollback; lookout upgrade --to <version> installs the version you name, older too. lookout upgrade --on vps-1 upgrades another machine: its running chats park first and resume after. Running the install line again works too.
Uninstall
curl -fsSL https://lookout.arcadia.is/install.sh | LOOKOUT_UNINSTALL=1 shIt signs the machine out and removes the CLI, its releases and its service. Your data in ~/.lookout stays; delete it yourself if you want it gone. The machine stays on your account's list as signed out: remove it in Settings › Devices, or with lookout remove NAME from another device.
To leave your account and keep the CLI, run lookout logout.