CLI

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.itoowasinarcadia.com/install.sh | sh

The 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.

• Run as root on Linux, it creates the user lookout and installs everything as that user. Run commands as that user: sudo -iu lookout lookout status.
• On a Mac with the Lookout app installed, it adds no service: the app keeps the Mac on your account while it runs.

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.itoowasinarcadia.com/install.sh | LOOKOUT_ACCOUNT=you LOOKOUT_NAME=vps-1 sh

The 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.

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 login

• With a browser on the machine, it opens one to sign in. Over ssh, or with no display, it asks for your Lookout username or email instead; press Enter for a link to open on your Mac.
• Lookout on your Mac then shows a request to add the machine, as in Install with no terminal: enter the code the machine printed. If you pressed Enter instead of a name, open the link it printed on your Mac. With no Mac at hand, run lookout devices approve LINK on a machine already on your account.
• On a new account, the first machine shows your Recovery Key. Save it, then press Enter.
• lookout login --recovery signs in with your browser and adds the machine with your Recovery Key, with no other device.

lookout 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:

• ready: it runs on this machine, and the line says where its sign-in comes from.
• not synced: your account's sign-in hasn't reached this machine, because the machine isn't on your account yet (lookout login) or no sync has run (lookout providers sync).
• not connected: your account has no sign-in for it.
• signed out, sign-in expired, needs a choice: what to do is on the line.

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.

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)

• -C DIR runs in another folder, which must exist. -m, --effort and --mode set the chat's model, reasoning effort and mode (default: the project's).
• The folder is opened the way the app opens one (Open a folder): a worktree or clone of a project's repository runs as a chat of that project, and a temp folder as a Scratch chat, in that folder.
• Piped input is read too: git diff | lookout exec "review this diff".
• A question the agent asks is skipped: a run never waits for input.
• Ctrl-C stops the turn; a second Ctrl-C quits at once.
• exec is the default command, so lookout "fix the failing test" runs too. A single word needs exec, and so do unquoted words that start with a command's name: lookout stop the flaky test runs stop.

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 THREAD

resume 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 and --mode switch the chat first. 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). 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.

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-1

• On another machine, -C takes a path that exists there: absolute, or '~/<path>' in quotes, so that ~ is the home folder there and not here. Without -C, runs there share one project, "lookout exec".
• --detach prints the thread id and returns; the chat keeps running there.
• Follow the chat with the same --on: lookout check THREAD --on vps-1 shows its state and last entries, steer THREAD TEXT sends it a message, stop THREAD stops it, set THREAD -m MODEL changes its model, answer THREAD OPTION answers a question it waits on.
• LOOKOUT_MACHINE=vps-1 makes that machine the one these commands reach when --on is left out, exec and sessions included. --on local is this machine.
• If the machine stops answering while exec follows a run, it retries for a minute, then exits with code 5 and prints the lookout check command that picks the chat up again.

Files 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-1

• get prints a text file, or writes it with --to FILE; an image or a media file needs --to. It carries text up to 512 KB and images up to the relay's 8 MB.
• put writes --from FILE, or what comes on stdin, at that path inside the chat's folder (its worktree when it has one), up to 10 MB. A file already there stays unless you add --overwrite. Only you, the chat itself or the chat that started it puts a file into a chat.
• Paths stay inside the chat's folder and out of .git, and put never writes through a link: it writes regular files only.
• A chat whose worktree was removed has no folder left: ls, get and put say so instead of reaching the project's checkout.
• A file named like a credential (.env, .envrc, .dev.vars, *.tfvars, secrets.yml, auth.json, a key, anything under ~/.ssh or ~/.lookout), a link to one, an .npmrc or .pypirc holding a login, or a file holding a token is refused either way: provider sign-ins reach your other machines only through your account.
• From a chat's Shell it runs as that chat, so its agent can bring back a report a chat it started wrote on another machine.

lookout 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
fi

• -o FILE writes the agent's last message to FILE.
• The run prints thread ID to stderr as it starts, for a later resume or print.
• --json prints one JSON object per line instead of text; the last is run_end, with stopReason and exitCode. status, machines and sessions take --json too.
• The exit code says how the run ended: 0 done, 1 turn error, 3 quota spent, 4 sign-in needed, 130 stopped. Every code is in the CLI reference.

Follow 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 ALERT

• The first lines are each account's 5-hour and weekly meters, the accounts already spent and the account serving now. After that, a line comes when an account is spent (with its window and when it reopens) or open again, a 5-hour or weekly meter drops past a 5-point step (or comes back up after a reset), the serving account changes, or chats are pinned to an excluded account.
• A line that needs you starts with ALERT:. It comes when an excluded account is serving, when no account is under the failover line, or when an API key is refused for credit, which doesn't reset on its own.
• Lines name providers and accounts by id, never by label or email.
• --for SECONDS (default 1800) is how long it follows; then it prints a last line saying so and exits 0. --on NAME follows another machine of your account, from a chat's Shell too.

Update

lookout upgrade

It 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.itoowasinarcadia.com/install.sh | LOOKOUT_UNINSTALL=1 sh

It 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.

Troubleshooting

• lookout doctor checks what chats on a machine need: providers, git identity and credentials, toolchains, capacity and disk, and its Hangs line names the server's recent hangs. Its Host line shows swap and the largest memory holders, and a macOS service that ran away with memory is a problem with the command that restarts it (A Mac that slows down). It lists each problem on a line starting with !, most with their fix, and exits 1 when it finds one. --on vps-1 checks another machine.
• lookout status says whether this machine is signed in, by lookout login or by the app, and how your other devices see it, with a fix when it knows one.
• Commits fail on a new server until git has an identity: lookout git setup --name "Your Name" --email [email protected]. For private repositories, pipe in a token for the forge: printf %s "$TOKEN" | lookout git setup --host github.com --token-stdin.
• lookout VERB --help prints one command's usage. lookout docs TOPIC prints a docs page's address, and --md prints the page.