Commands

The CLI is the lily command (also available as pathvela). This page is the accurate, hand-checked reference for the commands the shipped binary actually runs.

Every invocation has the same shape:

lily [global options] [command] [arguments]

With no command, lily opens the interactive terminal UI. The global options (like --cwd and --provider) go before the command.

Running the agent

Command	What it does
`lily`	Open the interactive terminal UI for a back-and-forth session.
`lily run "<message>"`	Ask one thing, print the answer, and exit.

The agent works in your current folder, so cd into the project you want it to see first:

cd ~/code/my-app
lily run "Explain what this repository does and where it starts."

`lily run` in scripts and pipelines

run is built for automation as well as quick questions:

Pipe input in. If you omit the message, the prompt is read from stdin. If you pass both a message and piped input, the input is attached to the message:
```
git diff | lily run "Review this change and flag anything risky."
```
--json emits a single machine-readable JSON result instead of streaming text — handy when a script needs the answer and the usage figures together.
--ndjson emits newline-delimited JSON events as the response streams, so a wrapper can react to tool calls and tokens live.

--json and --ndjson are mutually exclusive. With neither, run streams plain text to your terminal.

In the CLI, run works with a read-only tool profile — it can read files, search, and run read-only commands, but the interactive UI (lily) is where the agent makes changes.

Resuming a session

--resume picks up an earlier conversation:

lily --resume            # list your recent sessions
lily --resume <id>       # resume a specific one by id or name

A local, private web session

lily web runs the agent behind a small local web page and opens it in your browser:

lily web

Everything stays on your machine — the page, the agent, and your files are all local (http://127.0.0.1:<port>/, on a loopback address that's never exposed to the network). It works in the folder you run it from; use --folder <path> to point it elsewhere, --port <n> to choose the port, or --no-open to print the address instead of launching a browser.

Managing your key

Command	What it does
`lily key set [<key>]`	Store your API key on this machine.
`lily key status`	Show whether a key is stored, and your account and balance.
`lily key clear`	Forget the stored key.

lily key set sk-lily-...
lily key status

If you run lily key set with no key, it reads the key from stdin — which keeps it out of your shell history. Keys come from the developer console at platform.pathvela.com; see Your Pathvela account.

Models

Command	What it does
`lily model list`	List the model names you can pass to `--provider`/the SDK.

Add --json for machine-readable output or --verbose for more detail. The tiers are poolot-standard (default), poolot-pro, poolot-vision, and poolot-mini — see model tiers.

Auto mode (the bridge)

Auto mode keeps the agent running in the background so your Pathvela browser tab can reach it. It's opt-in.

Command	What it does
`lily bridge install`	Register auto mode so the agent starts on login.
`lily bridge status`	Report whether the bridge is running and auto mode is installed.
`lily bridge stop`	Stop the background agent now.
`lily bridge reset`	Stop it and revoke pairing (forces re-pairing next time).
`lily bridge uninstall`	Remove auto mode entirely.
`lily bridge log`	Print the bridge log.

To run the bridge scoped to a specific folder, pass --folder:

lily bridge --folder ~/code/my-app

See Auto mode for how pairing and the browser connection work.

The background server

The agent runs a background server for itself and starts it on its own when needed — you don't launch it. Two commands let you manage its lifecycle:

Command	What it does
`lily server reload`	Hand live sessions to a freshly started server on the newest binary.
`lily server stop --force`	Stop the running server (drops in-flight sessions, so it requires `--force`).

Editor integration

Command	What it does
`lily acp`	Run as an Agent Client Protocol (ACP) adapter over stdio, for an editor extension.

You don't usually run this by hand — an editor extension launches it for you.

Global options

These go before the command and apply across the CLI:

Option	What it does
`-p`, `--provider <auto\|poolot>`	Which backend to use. Both resolve to Pathvela; `auto` is the default.
`-C`, `--cwd <path>`	Set the working directory for the agent.
`--resume [<id>]`	Resume a session (or list sessions with no id).
`--quiet`	Suppress non-error status output — useful in scripts.
`--no-update`	Skip the automatic update check for this run.
`--version`	Print the version, e.g. `lily 0.1.35 (abc1234)`.
`--help`	Show help.

Help

lily --help            # top-level help
lily <command> --help  # help for a specific command

This page is the checked reference; if the built-in --help and these docs ever disagree, trust the docs.

Auto mode — background operation, pairing, and the browser connection.
Configuration — where the key and state live, and the environment variables the CLI reads.
Updating — how the CLI keeps itself current.