CLI

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.

Install

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:

lightcone update

Sign in

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:

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:

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:

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:

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:

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:

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:

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:

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

Next steps

• Quickstart: run your first task with the SDK
• Tasks: how Tasks work, configuration, pause/resume
• Computers: the computer control API behind these commands
• How Lightcone works: architecture and the API layers