> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tallwatch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI

> Install the Tallwatch CLI, sign in from your terminal, and manage monitors from the shell.

The Tallwatch CLI is a thin client over the public REST API. Use it in CI, on your laptop, or to import monitors from UptimeRobot. The control plane stays on Tallwatch — the CLI only calls `https://api.tallwatch.com`.

## Install

<Tabs>
  <Tab title="macOS / Linux">
    Requires Node.js 20+.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -fsSL https://tallwatch.com/install-cli.sh | bash
    ```

    Or with npm:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g @tallwatch/cli@latest
    ```
  </Tab>

  <Tab title="Windows">
    Requires Node.js 20+ (PowerShell).

    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    irm https://tallwatch.com/install-cli.ps1 | iex
    ```

    Or with npm:

    ```powershell theme={"theme":{"light":"github-light","dark":"github-dark"}}
    npm install -g @tallwatch/cli@latest
    ```
  </Tab>
</Tabs>

Verify:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tallwatch --help
```

## Sign in

Run `tallwatch login` with no flags. The CLI starts a device session, opens your browser, and polls until you approve.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tallwatch login
```

1. The terminal prints a one-time code and opens your browser.
2. Sign in if needed — approval is automatic when the URL includes your code.
3. Tallwatch creates an API key and delivers it to the CLI over the short-lived device session.
4. The browser tab can close. The terminal prints login success.

This works on SSH and remote machines: the browser can run on your laptop while the CLI runs on a server. Use `--no-browser` to print the URL yourself.

The key is saved to `~/.config/tallwatch/config.json` (mode `0600` on Unix). On Windows the path is `%USERPROFILE%\.config\tallwatch\config.json`.

### Manual key

Paste a key directly:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tallwatch login --api-key tw_live_your_key_here
```

Create keys in [**Settings → API keys**](https://app.tallwatch.com/settings/api-keys), or run `tallwatch login` to authorize from the terminal.

### Environment overrides

| Variable            | Purpose                                                         |
| ------------------- | --------------------------------------------------------------- |
| `TALLWATCH_API_KEY` | Bearer key (skips config file)                                  |
| `TALLWATCH_API_URL` | API base URL (default `https://api.tallwatch.com`)              |
| `TALLWATCH_APP_URL` | App URL for browser login (default `https://app.tallwatch.com`) |

Use `tallwatch login --no-browser` when the CLI runs on a remote machine and you open the login URL on your laptop.

### Sign out

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tallwatch logout
```

Removes `~/.config/tallwatch/config.json`. It does not revoke the API key in the dashboard — revoke **CLI login** keys from [Settings → API keys](https://app.tallwatch.com/settings/api-keys) if you want them dead server-side.

## Update and uninstall

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tallwatch update
tallwatch uninstall
```

`update` checks npm and installs the newer package with the **same Node/npm that runs `tallwatch`** (important if you use fnm or nvm). `uninstall` clears local login and removes the global package.

If a bare `npm uninstall -g @tallwatch/cli` does nothing, Homebrew npm and your fnm/nvm Node are different installs. Use `tallwatch uninstall`, or `which -a tallwatch` / `which -a npm` to align them.

## Commands

Same surface as the [MCP server](/integrations/mcp). Add `--json` on list, show, and mutating commands for scripting. List `--limit` max is **15**.

| Command                                 | What it does                                            |
| --------------------------------------- | ------------------------------------------------------- |
| `tallwatch help`                        | Print usage                                             |
| `tallwatch login`                       | Browser device login; stores API key locally            |
| `tallwatch login --api-key tw_live_…`   | Log in with an existing API key                         |
| `tallwatch logout`                      | Remove the local API key config                         |
| `tallwatch update`                      | Install the latest CLI from npm                         |
| `tallwatch uninstall`                   | Log out and remove the global package                   |
| `tallwatch version`                     | Print the installed CLI version                         |
| `tallwatch whoami`                      | Show org name, plan, and API key name                   |
| `tallwatch monitor list`                | List monitors (optional `--limit`, `--cursor`)          |
| `tallwatch monitor show [id]`           | Show one monitor (omit id to pick)                      |
| `tallwatch monitor create --url …`      | Create an HTTP monitor                                  |
| `tallwatch monitor update [id]`         | Patch name, interval, regions, or status                |
| `tallwatch monitor pause [id]`          | Pause scheduling (`--yes` to skip confirm)              |
| `tallwatch monitor resume [id]`         | Resume a paused monitor                                 |
| `tallwatch incident list`               | List incidents (`--status`, `--monitor-id`, `--cursor`) |
| `tallwatch incident show [id]`          | Incident detail (omit id to pick)                       |
| `tallwatch incident ack [id]`           | Acknowledge an open incident (`--note`)                 |
| `tallwatch incident resolve [id]`       | Manually resolve an incident (`--yes`)                  |
| `tallwatch incident postmortem [id]`    | Set or clear postmortem (`--md`, `--file`, `--clear`)   |
| `tallwatch oncall now`                  | Who is on call now (`--schedule-id`)                    |
| `tallwatch status-page list`            | List status pages in the org                            |
| `tallwatch test --url …`                | Run one ad-hoc check from the API host                  |
| `tallwatch import uptimerobot --file …` | Dry-run UptimeRobot import (`--apply --yes` to write)   |

Examples:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
tallwatch monitor create --url https://api.example.com/healthz --interval 60s
tallwatch monitor pause <uuid> --reason "database migration" --yes
tallwatch incident ack <uuid> --note "looking"
tallwatch incident resolve <uuid> --yes
tallwatch incident postmortem <uuid> --file ./postmortem.md
```

## UptimeRobot import

Export monitors from UptimeRobot, dry-run the mapping, then apply:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://api.uptimerobot.com/v2/getMonitors \
  -H "Content-Type: application/json" \
  -d '{"api_key":"YOUR_UR_KEY","format":"json"}' \
  > monitors.json

tallwatch import uptimerobot --file ./monitors.json
tallwatch import uptimerobot --file ./monitors.json --apply --yes
```

Dry-run works without login. `--apply` requires a signed-in CLI. HTTP (type 1) and keyword (type 2) monitors map to Tallwatch HTTP checks. Ping, port, and heartbeat exports are skipped with a reason.

## Auth and limits

The CLI uses the same [API keys](/api/api-keys) and [rate limits](/api/rate-limits) as curl or MCP. Keys need `read` to list; `write` to create, pause, or resolve.

CLI login creates a key named **CLI login** with `read` + `write` scopes. Revoke it anytime from Settings.

## Related

[API keys](/api/api-keys). [MCP server](/integrations/mcp) for AI agents. Install page: [tallwatch.com/cli](https://tallwatch.com/cli).