CLI quickstart

Choose a desktop or terminal workflow

The npm package includes the CLI and host daemon. The host runs projects and coding agents; the CLI and supported Lyre clients connect to it. Install the desktop app for the graphical workspace, or run a standalone host on a computer without the desktop app.

Host

The computer where projects and agents run.

Provider

An external coding-agent tool, such as Codex or Claude Code, installed and configured on the host.

Project

A registered folder on the host.

Workspace

A place to work within a project, using a local folder or separate Git worktree.

The initial npm release is qualified on Windows x64 with Node.js 24. Installed macOS/Linux qualification is pending; macOS native helpers are absent from this npm build. See current limits.

1. Install and check

node --version
npm --version
npm install --global @lyrestudio/cli@beta
lyre --version
lyre --help

The published npm CLI version is 0.11.0-beta.3, accompanying desktop 0.1.6. To pin this version, use npm install --global @lyrestudio/cli@0.11.0-beta.3. npm installs all six companion runtimes automatically; you do not need to install them separately.

lyre, lyre-foundation and paseo are aliases for the same Lyre CLI. Help may print lyre-foundation. This guide uses lyre.

2. Start or select the host

If Lyre Studio desktop is already running, use lyre status to check the selected host. Manage that desktop-owned host from the app.

For a standalone npm host:

lyre daemon start
lyre status

The daemon keeps running after the start command exits. Start reports its PID, endpoint and log path. Allow provider discovery to finish, then retry status if the host is still starting.

The default local home is ~/.lyre-foundation. To select another local home, use the same --home on every command. Replace the placeholder below with a short absolute path outside your project:

lyre daemon start --home PATH_TO_LYRE_HOME
lyre status --home PATH_TO_LYRE_HOME

For another computer, see host selection. A remote command acts on the selected host, and project paths refer to that computer.

3. Check your provider

lyre provider ls
lyre provider diagnostic codex

Replace codex with your provider. Install and sign into that provider's own tool on the host, following Lyre's provider guide and its official instructions: Claude Code or Codex CLI. Lyre manages the provider; installing Lyre does not install or sign you into it.

Provider accounts, model access, usage limits and service charges are separate from Lyre. A provider installed in your shell may still be missing from the daemon's environment; the diagnostic checks the environment the host actually uses.

4. Run a first task

Open a terminal in your existing project folder. This example registers it and asks Codex to explain it:

lyre project create .
lyre run --provider codex --cwd . --task-mode ask "Explain this project without changing files."
lyre ls

Choose a provider shown by lyre provider ls. Task modes guide the request; they do not change permission policy. For a coding task, use --task-mode agent and describe the change.

run normally waits for the task. Add --background to return immediately. Copy the agent ID from lyre ls and replace AGENT_ID below:

lyre logs AGENT_ID --follow
lyre send AGENT_ID "Explain what I should check next."

If the provider is waiting for approval, inspect lyre permit ls and review that specific request. Use lyre stop AGENT_ID to interrupt its current work.

5. Connect a client when you need one

lyre pair

Review the host's prompts to approve a trusted owner device. Open a supported Lyre client on that device, choose Connect in the Library and use the pairing instructions. Keep the host awake and connected.

Owner pairing grants host management access. To invite someone to try only your app, use the client's app-sharing controls. Check mobile availability before choosing a phone client.

Update a standalone npm host

Let running tasks finish before stopping the host. Keep its existing home and project folders:

lyre daemon stop
npm install --global @lyrestudio/cli@beta
lyre daemon start
lyre --version
lyre status

Include your custom --home on daemon/status commands if you use one. For a desktop-managed host, use the app's update and restart controls. npm updates the CLI and companion runtimes; the desktop app updates separately.

Troubleshooting

lyre is not found

Reopen the terminal. Run npm config get prefix; ensure that directory is on PATH on Windows, or its bin directory on macOS/Linux. Check lyre --version to confirm which installation you are using.

The daemon is unreachable

Allow startup to finish, retry lyre status, and check the reported log path. Use the same --home or intended --host throughout.

A provider is unavailable

Run lyre provider diagnostic codex with its name. Complete its installation and account setup on the host, not only on the client.

An agent is waiting

Check lyre logs AGENT_ID and lyre permit ls. Review a pending request before approving or denying it.

A daemon launch option is rejected

Persistent settings use lyre daemon config set KEY VALUE. For listening configuration, inspect lyre daemon config set --help; old launch-time listen overrides are no longer accepted.

Current release limits and next steps

Windows qualification includes installed lifecycle, command aliases, dependency audit, image-input and project-process helpers. It does not establish installed macOS/Linux or every provider/device workflow.

Keep Windows daemon homes short: the image-file helper does not support full image or temporary paths of 260 characters or more. The VS Code companion is not yet published. Use the available Lyre clients.

npm package · Release README and installation guide