---
title: CLI | Lightcone
description: Run tasks, control computers, and wire up coding agents from your terminal.
---

The `lightcone` CLI brings everything in Lightcone to your terminal: run Northstar tasks with live streaming, control browser and desktop computers directly with pipeable Unix-style commands, and connect coding agents like Claude Code and Cursor to Lightcone via MCP.

[](/media/cli-process-spawn.mp4)

## Install

Terminal window

```
curl -fsSL https://lightcone.ai/install | sh
```

This installs a single static binary; no runtime or toolchain required. Prebuilt binaries are available for macOS (Intel and Apple Silicon), Linux (x86\_64 and aarch64), and Windows.

To upgrade later:

Terminal window

```
lightcone update
```

## Sign in

Terminal window

```
lightcone login
```

This opens your browser for a device-flow sign-in, so it inherits your organization’s SSO and MFA. Check or clear your session with:

Terminal window

```
lightcone whoami   # show the stored identity
lightcone logout   # revoke the session and clear local credentials
```

Alternatively, skip browser auth entirely and use an API key from the [dashboard](https://lightcone.ai/dashboard):

Terminal window

```
export TZAFON_API_KEY=sk_your_api_key_here
```

New to Lightcone? `lightcone quickstart` walks you through auth and agent setup interactively.

## Run tasks

Give Northstar a task and watch it stream live:

Terminal window

```
lightcone run "Go to wikipedia.org and tell me the first sentence of the Alan Turing article"
```

Useful flags:

| Flag                      | What it does                       |
| ------------------------- | ---------------------------------- |
| `--kind desktop\|browser` | Choose the computer environment    |
| `--max-steps <n>`         | Cap the number of agent steps      |
| `--model <model>`         | Pick the Northstar model           |
| `--start-url <url>`       | Open a page before the task starts |
| `--system-prompt <text>`  | Add custom system instructions     |
| `--json`                  | Emit raw NDJSON events for piping  |

Running bare `lightcone` opens the interactive TUI instead. While a task is running, press Enter to inject a message into it mid-run: steer it, add context, or tell it to stop. The TUI also shows a **Follow** URL you can open in a browser to watch the session live.

The CLI also ships an experimental `lightcone goal` command for long-running durable goals; its interface is subject to change.

## Direct computer control

Every direct-control command is a single REST call that writes its load-bearing output (IDs, URLs, HTML, shell output) to stdout, so `$()` capture and pipes work naturally:

Terminal window

```
lightcone computers create [--kind desktop|browser] [--persistent]   # prints the computer id
lightcone computers list [--json]
lightcone computers destroy <id>


lightcone screenshot <id>            # prints a signed image URL
lightcone click <id> <x> <y>
lightcone double-click <id> <x> <y>
lightcone right-click <id> <x> <y>   # desktop only
lightcone type <id> "<text>"
lightcone hotkey <id> <keys...>      # e.g. ctrl c
lightcone scroll <id> <dx> <dy> [x] [y]
lightcone navigate <id> <url>        # browser only
lightcone html <id>                  # page HTML to stdout
lightcone shell <id> "<command>"     # remote stdout/stderr/exit code
lightcone batch <id> --json '[...]'  # multiple actions in one round-trip
```

Chain them together:

Terminal window

```
id=$(lightcone computers create)
lightcone screenshot $id | xargs open    # macOS: open the screenshot URL
lightcone navigate $id https://example.com
lightcone click $id 400 300
lightcone type $id "hello world"
lightcone hotkey $id enter
lightcone computers destroy $id
```

A few things worth knowing:

- **`--persistent`** creates a computer whose state can be saved and reused across sessions.
- **`hotkey`** takes named keys like `enter`, `ctrl`, `shift`, case-insensitive.
- **`shell`** mirrors the remote command’s stdout, stderr, and exit code locally, so `lightcone shell $id "exit 7"; echo $?` prints `7`. It works as an ssh-like step in CI scripts.

## Wire up coding agents

Connect Claude Code, Cursor, or Codex to Lightcone so your coding agent can drive browsers and desktops:

Terminal window

```
lightcone configure-agents
```

This writes MCP configuration pointing at `@tzafon/lightcone-mcp` for the agents you select. Your API key is read from the environment at runtime; it is never embedded in the config files.

For a single project instead of your whole machine:

Terminal window

```
lightcone configure-project
```

This writes project-scoped config (`.mcp.json`, `.cursor/mcp.json`) and offers to install the Lightcone SDK into the project as well.

## Scripting

Commands that support `--json` emit NDJSON or JSON on stdout, so the CLI composes with `jq` and standard shell tooling:

Terminal window

```
lightcone computers list --json | jq -r '.[].id'
lightcone run "check example.com is up" --json | jq -r 'select(.type == "text") | .delta'
```

## Next steps

- [**Quickstart**](/guides/quickstart/index.md): run your first task with the SDK
- [**Tasks**](/guides/tasks/index.md): how Tasks work, configuration, pause/resume
- [**Computers**](/guides/computers/index.md): the computer control API behind these commands
- [**How Lightcone works**](/guides/how-lightcone-works/index.md): architecture and the API layers