Lyre CLI workflows

Before you start

Complete the quickstart. Examples use the current project folder and Codex; choose a provider available on your selected host. Replace uppercase IDs with values from the corresponding list command. Commands shown in separate examples are choices for different tasks, not a script to run from top to bottom.

Choose how the agent approaches a request

lyre run --provider codex --cwd . --task-mode plan "Plan a fix for the login error before editing."
lyre send AGENT_ID --task-mode debug "Investigate why the login test fails."

run --task-mode applies guidance to the first request; send --task-mode applies it to that follow-up. This is separate from provider --mode and permission policy. It does not grant access or guarantee helper tools. Orchestrate is an interactive client workflow, not a CLI task-mode value.

Keep parallel edits in separate checkouts

From a Git repository, create a managed worktree and branch:

lyre run --provider codex --cwd . --new-workspace worktree --new-branch fix-login --background "Fix login validation and run its tests."
lyre workspace ls

To start another agent in that checkout, select its workspace ID:

lyre run --provider codex --workspace WORKSPACE_ID "Review the login fix and its tests."

The original checkout keeps its own edits. Review and merge the branch through your normal Git workflow. Creating a worker does not merge its changes. If workspace setup was skipped, inspect its configured setup before explicitly allowing it with lyre workspace setup WORKSPACE_ID.

Send a screenshot with destination review

Choose an existing agent from lyre ls with an image-capable provider:

lyre send AGENT_ID --task-mode ask --image screenshot.png "Explain the layout issue in this screenshot."

Use an existing PNG or JPEG. Review the image-transfer prompt before sending it to the model provider; repeat --image for more than one image. Hosts requiring review reject images in an initial run request, so use this reviewed send path. Model and provider image support still applies.

Prepare a preview and control its service

Read local project metadata and review a web-service proposal on an explicit port:

lyre preview inspect . --json
lyre preview plan . --port 5173 --json

If suitable and no paseo.json exists, use lyre preview configure . --port 5173 --json to create it. Configuration does not launch the app or install dependencies and refuses to overwrite an existing file. Existing configuration needs manual review. Setup commands are local-only.

After installing the project's dependencies, choose a listed script:

lyre script ls --cwd .
lyre script start SCRIPT_NAME --cwd .

Replace SCRIPT_NAME with the listed name; a generated preview configuration uses preview. Use --workspace WORKSPACE_ID when a directory has multiple workspaces. Open and interact with the app in a supported Lyre client.

lyre script stop SCRIPT_NAME --cwd .

Agents and services have independent lifecycles. Stopping one does not stop the other. A loopback service is not a public deployment or an app-sharing grant. See project setup for services and dependencies.

Schedule a bounded weekday review

This example runs at 9 a.m. Chicago time on weekdays and stops after five runs:

lyre schedule create "Review this project and summarize the next steps without editing files." --provider codex --cwd . --task-mode ask --cron "0 9 * * 1-5" --timezone America/Chicago --max-runs 5
lyre schedule ls
lyre schedule logs SCHEDULE_ID

The daemon must be running and the provider ready. Permissions and provider costs still apply. You can pause future work and resume it later:

lyre schedule pause SCHEDULE_ID
lyre schedule resume SCHEDULE_ID

lyre schedule run-once SCHEDULE_ID requests an extra run without changing cadence. Use inspect and logs to verify what actually happened; a saved schedule is not a successful run.

Review a pending permission

lyre permit ls

Inspect the agent, request ID and operation. Then choose either lyre permit allow AGENT_ID REQUEST_ID or lyre permit deny AGENT_ID REQUEST_ID. Task modes and scheduling do not approve operations for you.

Inspect or develop a trusted plugin

lyre plugin ls
lyre plugin update --all --check

The update check reports available revisions without installing them. Authors can scaffold a focused lifecycle plugin and statically check it:

lyre plugin init ./my-plugin --template lifecycle
lyre plugin check ./my-plugin --json

Scaffolding does not install dependencies; a static check does not run entries, activate the plugin or prove runtime behavior. Follow plugin authoring for development dependencies and validation, then explicit installation and trust.

Plugins run unsandboxed code with the host account's access, and client surfaces run in connected Lyre apps. Review the source and updates you intend to trust.

Continue from a supported client

Use lyre pair to review owner-device pairing. Connected Lyre clients provide preview viewing, app-sharing invitations and whole-desktop control through their own permissions and platform support. The CLI does not imply every graphical feature has a terminal equivalent.