---
title: CLI
description: "The lookout command on Linux and macOS: install it, sign in, run chats, and use it in scripts."
canonical_url: https://lookout.itoowasinarcadia.com/docs/cli
type: surface
section: Surfaces
last_updated: 2026-10-22
related:
  - https://lookout.itoowasinarcadia.com/docs/cli-reference
  - https://lookout.itoowasinarcadia.com/docs/machines
  - https://lookout.itoowasinarcadia.com/docs/mac-app
---

> Every page of these docs: https://lookout.itoowasinarcadia.com/llms.txt

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

```sh
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:

```sh
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.

| 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](https://lookout.itoowasinarcadia.com/docs/machines#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:

```sh
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](https://lookout.itoowasinarcadia.com/docs/cli#install-unattended): 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](https://lookout.itoowasinarcadia.com/docs/models#connect)), 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](https://lookout.itoowasinarcadia.com/docs/models#cli-only).

## Run a prompt

```sh
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:

```text
[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](https://lookout.itoowasinarcadia.com/docs/chats#open-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](https://lookout.itoowasinarcadia.com/docs/cli#on).

## Follow up on a chat

```sh
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](https://lookout.itoowasinarcadia.com/docs/cli#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**.

```sh
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:

```sh
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](https://lookout.itoowasinarcadia.com/docs/agents#hosts) there, around the clock. `lookout share off` stops your other devices from using this machine.

## Use it in scripts

```sh
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](https://lookout.itoowasinarcadia.com/docs/cli-reference#exit-codes).

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

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

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

```sh
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](https://lookout.itoowasinarcadia.com/docs/troubleshooting#runaway-daemon)). 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 you@example.com`. 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.

## Related

- [CLI reference](https://lookout.itoowasinarcadia.com/docs/cli-reference.md): Every lookout command and flag as the command's own help prints them, and what each exit code means.
- [Machines](https://lookout.itoowasinarcadia.com/docs/machines.md): Run chats on your other Macs and on your servers, from the app or the terminal.
- [Mac app](https://lookout.itoowasinarcadia.com/docs/mac-app.md): Install the Mac app, keep it up to date, and find its logs.