# CLI reference

> Commands, flags, arguments, defaults, exit behavior, and examples for the command-line interface.

- Repository: egoist/lorca
- GitHub: https://github.com/egoist/lorca
- Human docs: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6
- Complete Markdown: https://grok-wiki.com/public/docs/egoist-lorca-2cf67495e5e6/llms-full.txt

## Source Files

- `web/content/docs/cli.mdx`
- `crates/cli/src/main.rs`

---

---
title: "CLI reference"
description: "Commands, flags, arguments, defaults, exit behavior, and examples for the command-line interface."
---

`lorca` is the binary that holds keys, serves the local websocket API the app connects to, runs the agent loop, and syncs with the relay. Unknown flags error. With no subcommand, it runs `serve`.

```bash
lorca [--home <path>] [--port <u16>] [serve|identity|pair|provider|status|doctor] …
```

## Global flags

<ParamField body="home" type="PathBuf" optional>
  Data directory for keys, credentials, and chats. Long flag `--home`. Env: `LORCA_HOME`. Default: `~/.lorca`.
</ParamField>

<ParamField body="port" type="u16" optional>
  Local websocket port for the app. Long flag `--port`. Env: `LORCA_PORT`. Default: `4862`.
</ParamField>

Both flags are global and apply to every subcommand.

## Environment

| Variable | Effect |
| --- | --- |
| `LORCA_HOME` | Data directory. Default `~/.lorca`. |
| `LORCA_PORT` | Local port. Default `4862`. |
| `LORCA_RELAY_URL` | Relay URL for multi-device sync. Unset = single-device mode. |
| `LORCA_SHELL` | Shell bots use for commands. Default `/bin/bash`; on Windows, Git for Windows bash. |
| `LORCA_DEEPSEEK_MODEL`, `LORCA_ANTHROPIC_MODEL`, `LORCA_CHATGPT_MODEL`, `LORCA_GROK_MODEL` | Default model when a bot does not pick one. |

Tracing logs go to stderr. Default filter when `RUST_LOG` / env filter is unset: `lorca=info,lorca_agent=info`.

## Command map

| Command | Role |
| --- | --- |
| `lorca serve` | Local API + agent loop + relay sync (default). |
| `lorca identity …` | Create, restore, or show identity. |
| `lorca pair [string]` | Start pairing or join with a pairing string. |
| `lorca provider …` | Connect, disconnect, or list AI providers. |
| `lorca status` | Pretty-printed JSON snapshot of this device. |
| `lorca doctor` | Local setup checks with ✔ / ✘ lines. |

---

## `lorca serve`

Runs the local websocket the app connects to. Default when `command` is omitted (`parent_pid: None`, `ready_stdout: false`).

On start it primes runtime names, resumes sent jobs, closes stale shell rows, refreshes installed marketplace plugins from the bundled index, optionally watches a parent PID, loads login-shell environment for bots, and spawns relay sync and routines before `ws::serve`.

<ParamField body="parent-pid" type="u32" optional>
  Long flag `--parent-pid`. Exit when this process is gone. The app passes its own PID so a killed app does not leave a stale CLI holding the port. Polls every 1s; on parent exit shuts down shell sessions and `process::exit(0)`.
</ParamField>

<ParamField body="ready-stdout" type="bool" optional>
  Long flag `--ready-stdout`. Write a JSON readiness message to stdout once the local server is listening.
</ParamField>

<RequestExample>
```bash
lorca serve
lorca serve --parent-pid 12345 --ready-stdout
```
</RequestExample>

### Unix signals

On Unix, `SIGTERM`, `SIGINT`, and `SIGHUP` first shut down bot shell sessions, then restore the default handler and re-raise the same signal so the process exits as usual.

### Headless Runner

```bash
export LORCA_RELAY_URL=https://relay.example.com
lorca pair 'lorca://pair?…'
lorca serve
```

After pairing and serve, the computer appears in the Device list and can host bots.

---

## `lorca identity`

### `lorca identity new`

Creates a new identity on this device and prints the backup phrase.

<ParamField body="name" type="string" optional>
  Long flag `--name`. Device name for the new identity.
</ParamField>

<ResponseExample>
```text
Identity created on this Device.

Backup phrase (write it down; it is the identity):

  word1 word2 … wordN

No relay configured. Set LORCA_RELAY_URL to sync with other Devices.
```
</ResponseExample>

If `LORCA_RELAY_URL` is set, one sync flush (up to 8s) runs after create.

### `lorca identity restore`

Restores from a backup phrase. Needs a relay.

<ParamField body="phrase" type="Vec<String>" required>
  Positional words of the backup phrase (joined with spaces for restore).
</ParamField>

<ParamField body="name" type="string" optional>
  Long flag `--name`.
</ParamField>

Prints: `Identity restored. Run \`lorca serve\` to sync.`

### `lorca identity show`

Prints identity id, public keys, device name/OS, whether this device holds the master, and registration. If none: `No identity on this Device. Run \`lorca identity new\`.`

```text
identity id:   …
identity key:  …
machine key:   …
device name:   name (os)
holds master:  true|false
registered:    true|false
```

---

## `lorca pair`

### Start pairing (no string)

Creates a pairing string and waits until the other device joins or pairing fails.

```bash
lorca pair
# optional: lorca pair --name "laptop"
```

Prints instructions, then polls status every 1s:

- `completed` → prints paired device name, flushes outbox once, exits 0
- `failed` → bails with the status error message (or `pairing failed`)

### Join with a string

```bash
lorca pair 'lorca://pair?…' --name "runner"
```

On success: `Paired as <name>. Run \`lorca serve\` to sync.`

<ParamField body="pairing_string" type="string" optional>
  Positional. From the device that holds the identity. Omit to create one here.
</ParamField>

<ParamField body="name" type="string" optional>
  Long flag `--name`. Name for this device when joining.
</ParamField>

---

## `lorca provider`

Manages account provider credentials. Prefer a running `lorca serve`: set/remove call `ws://127.0.0.1:<port>/ws` so the app sees the change immediately. If nothing listens, the CLI dispatches locally and runs one sync flush.

Allowed kinds: `deepseek`, `anthropic`, `opencode`, `opencode-go`, `chatgpt`, `grok`.

### `lorca provider set <kind> [api-key]`

| Kind | How it connects |
| --- | --- |
| `deepseek`, `anthropic`, `opencode`, `opencode-go` | API key (positional or stdin) |
| `chatgpt`, `grok` | Browser sign-in only |

<ParamField body="kind" type="string" required>
  Provider id. Unknown values bail: `Unknown provider {kind}. Use one of: …`.
</ParamField>

<ParamField body="api_key" type="string" optional>
  Positional API key. Omit to read from stdin (keeps the key out of shell history). Prompt `API key: ` on stderr when stdin is a terminal.
</ParamField>

<ParamField body="base-url" type="string" optional>
  Long flag `--base-url`. Custom API root (proxy or compatible server). Ignored / rejected for `chatgpt` and `grok`.
</ParamField>

Constraints:

- `chatgpt` / `grok` with `api_key` or `base_url` set → bail: `{kind} connects with a browser sign-in and takes no API key`
- For those kinds, prints `Finish the sign-in in the browser…` then calls `providers.connect_<kind>` with `{}`
- `opencode-go` maps to method `providers.connect_opencode_go`

After success, prints each provider as `{kind}` left-padded to 10 columns plus `detail`.

### `lorca provider remove <kind>`

Disconnects that provider on every device via `providers.disconnect` with `{ "kind": kind }`.

### `lorca provider list`

Lists providers and connection detail from the credentials file (same set a running serve would hold). No websocket call.

---

## `lorca status`

Prints `app.snapshot()` as pretty JSON (devices, bots, chats, providers, and related state). Exits after print.

```bash
lorca status
```

---

## `lorca doctor`

Checks local setup; always returns `Ok(())` from main after printing lines.

| Check | Pass signal | Fail detail |
| --- | --- | --- |
| `home` | `config.home` is a directory | path string |
| `identity` | identity present | `run \`lorca identity new\`` |
| `port` | `127.0.0.1:<port>` bind succeeds | `{port} busy (lorca serve running?)` |
| `relay` | health OK when URL set | unreachable URL, or `not configured (LORCA_RELAY_URL); single-Device mode` |
| `providers` | at least one connected kind | `none connected` |

Each line: `✔` or `✘`, then label and detail.

---

## Exit and error behavior

| Situation | Behavior |
| --- | --- |
| Success paths above | `Ok(())` / normal process exit |
| `--parent-pid` parent gone | shell shutdown, then exit code `0` |
| Pairing `failed` | `anyhow::bail` with error string |
| Unknown provider kind | bail with allowed-kinds list |
| chatgpt/grok with key/url | bail with browser-sign-in message |
| Serve websocket closed mid-call | bail `lorca serve closed the connection` |
| Provider RPC error | mapped from JSON `error.message` |
| Unknown CLI flags | error (`unknown_flags = "error"`) |

Provider set/remove against a live serve send JSON-RPC over websocket:

```json
{ "id": 1, "method": "<method>", "params": { … } }
```

Reply is the message with matching `id`; `error.message` becomes the CLI error.

---

## Install and binary location

On Apple silicon Mac or Linux without the app:

```bash
curl -fsSL https://lorca.app/install-cli.sh | sh
```

On Windows PowerShell:

```powershell
irm https://lorca.app/install-cli.ps1 | iex
```

Install script options: `LORCA_VERSION`, `LORCA_INSTALL_DIR`, `LORCA_NO_MODIFY_PATH=1`. Default install path: `~/.local/bin`. On macOS with the app, the bundled binary is `Lorca.app/Contents/Resources/bin/lorca`. App service logs: `~/Library/Logs/Lorca/cli.log`.

On Windows, install Git for Windows so bots can run commands in its bash.

## Data under home

Everything under `~/.lorca/` (or `LORCA_HOME`): identity and machine keys, provider credentials, settings, chats, attachments, plugins, and one workspace folder per bot. Readable only by the user.

## Related pages

<CardGroup>
  <Card title="Installation" href="/installation">
    Prerequisites, install command, first run, and recovery notes.
  </Card>
  <Card title="Quickstart" href="/quickstart">
    Shortest path from install to a first successful invocation.
  </Card>
  <Card title="Configuration reference" href="/configuration-reference">
    Config keys, environment variables, defaults, and where each is read.
  </Card>
  <Card title="crates/cli reference" href="/ref-crates-cli">
    Library surface under `crates/cli`: exports, invocation, options, errors.
  </Card>
  <Card title="HTTP API reference" href="/http-api-reference">
    Local websocket / RPC methods the CLI and app use.
  </Card>
</CardGroup>

Next: Run `lorca doctor` and confirm every line shows ✔ before connecting providers.