Lyre / documentation
Get Lyre
Command line

CLI reference

Common commands and options for the published Lyre CLI, grouped by what you want to do.

On this page

Read the command syntax

Start with the CLI quickstart if you need installation, provider setup or a running host. AGENT_ID, WORKSPACE_ID and other uppercase names are placeholders. Quotes keep a multiword prompt together; the examples use single-line commands that work in PowerShell, cmd.exe and POSIX shells. 

lyre --help
lyre run --help
lyre schedule create --help
lyre describe run --json

--help shows the installed command's arguments and options. describe reads its registered metadata without connecting to a host or executing the command.

Command Use it to
lyre run --provider codex "TASK" Start an agent and wait for its current task.
lyre ls Find agents and their IDs.
lyre logs AGENT_ID --follow Follow activity.
lyre send AGENT_ID "FOLLOW_UP" Continue the same conversation.
lyre stop AGENT_ID Interrupt the current agent turn.

Host selection and global options

Command Use it to
--home PATH Select a local daemon home; default ~/.lyre-foundation. Use the same value on subsequent local commands.
--host TARGET Select an explicit daemon endpoint: host:port, TCP, local socket/pipe, SSH or pairing URL.
--json / --format json Request machine-readable JSON where the command supports it.
--format yaml Request YAML where supported.
--quiet Use minimal output, commonly IDs.
--no-headers / --no-color Simplify terminal output.
--version Print the CLI version. 
lyre status --home PATH_TO_LYRE_HOME
lyre ls --host "ssh://USER@HOST"

Replace the SSH target with a host you control, with a running daemon and a working SSH connection. Host selection does not install or start Lyre on that computer. Remote project paths refer to the remote filesystem. Local preview planning/configuration is an exception: it operates on this computer's files and rejects --host.

Local connections use the selected daemon's local credential. Pairing and remote authentication remain explicit; a reachable address does not grant access. See connection setup.

Agent lifecycle and context

Command Use it to
lyre run --provider PROVIDER --cwd PATH "TASK" Create an agent in a workspace for the selected directory.
lyre run --workspace WORKSPACE_ID "TASK" Create an agent in an existing workspace.
lyre run --background "TASK" Return while the agent keeps running.
lyre ls --json List agents as structured output.
lyre inspect AGENT_ID Inspect an agent.
lyre logs AGENT_ID --follow Follow its timeline.
lyre send AGENT_ID --task-mode plan "TASK" Send a follow-up with request-scoped task guidance.
lyre send AGENT_ID --image IMAGE_PATH "TASK" Send PNG/JPEG context after reviewing the transfer prompt.
lyre wait AGENT_ID Wait until the agent becomes idle; inspect its result separately.
lyre stop AGENT_ID Interrupt its active turn.
lyre archive AGENT_ID Archive the conversation.
lyre delete AGENT_ID Permanently remove the agent; inspect help before using it.

Run options include --provider, --model, --thinking, provider --mode, Lyre --task-mode, --workspace, --new-workspace, --label, --env and --wait-timeout. Availability depends on the provider and host. An idle agent is not proof that a task succeeded.

See task modes and reviewed image transfer.

Projects and workspaces

Command Use it to
lyre project create PATH Register an existing folder. With an explicit remote host, provide its path.
lyre project ls List registered projects.
lyre project rename PROJECT_ID "TITLE" Change the displayed project name.
lyre workspace ls List active workspaces.
lyre workspace create --isolation worktree --path PATH --new-branch BRANCH Create a separate managed Git checkout.
lyre workspace rename WORKSPACE_ID "TITLE" Change its displayed title.
lyre workspace setup WORKSPACE_ID Explicitly allow and run the workspace setup commands.
lyre workspace archive WORKSPACE_ID Archive the workspace and its owned work.
lyre project delete PROJECT_ID Remove project registration and archive active workspaces; the project folder remains.

Archiving a workspace affects its agents and terminals. An owned managed worktree may be removed when its last active reference is archived; a local project folder remains. Review those commands before using them. See worktree examples.

Preview setup and workspace services

Command Use it to
lyre preview inspect PATH --json Read local project metadata and preview readiness.
lyre preview plan PATH --port PORT --json Propose a local preview configuration without writing or launching.
lyre preview configure PATH --port PORT --json Create a new paseo.json; refuse to overwrite existing configuration.
lyre preview serve PATH --port PORT Serve supported static assets on loopback.
lyre preview native-status PATH --json Inspect native targets and toolchain prerequisites without building.
lyre script ls --workspace WORKSPACE_ID List configured workspace scripts and their state.
lyre script start SCRIPT_NAME --workspace WORKSPACE_ID Start one script through the host lifecycle.
lyre script stop SCRIPT_NAME --workspace WORKSPACE_ID Stop that service independently of agents.

Script selection also accepts --cwd PATH; use the workspace ID when a directory has multiple workspaces. A readiness proposal does not prove the app runs, and a local preview does not publish or share it. Follow the preview workflow.

Files and terminals

Use lyre files find, grep and read to inspect workspace files through the host. Use lyre terminal ls, create, capture, send-keys and kill for managed terminals. Inspect each subcommand's help before supplying paths or sending commands. 

lyre files read --help
lyre terminal create --help
lyre terminal ls --workspace WORKSPACE_ID --json

Terminals belong to a workspace. Commands and setup scripts execute on the selected host with its account's permissions.

Schedules and permissions

Command Use it to
lyre schedule create "TASK" --provider PROVIDER --cwd PATH --every 1h --max-runs 5 Create bounded recurring work in new agents.
lyre schedule ls List schedules.
lyre schedule inspect SCHEDULE_ID Inspect cadence, target and history.
lyre schedule logs SCHEDULE_ID Read recent run logs.
lyre schedule pause SCHEDULE_ID Pause future scheduled runs.
lyre schedule resume SCHEDULE_ID Resume a paused schedule.
lyre schedule run-once SCHEDULE_ID Request an extra run without changing cadence.
lyre schedule update SCHEDULE_ID --help Inspect supported updates before changing a schedule.
lyre schedule delete SCHEDULE_ID Remove a schedule.
lyre permit ls Inspect pending agent permissions.
lyre permit allow AGENT_ID REQUEST_ID Approve a reviewed request.
lyre permit deny AGENT_ID REQUEST_ID Deny it.

Use --cron and --timezone for calendar schedules. The host and provider must be available; permissions and provider charges still apply. See a weekday example.

Providers and trusted plugins

Command Use it to
lyre provider ls Check available coding providers.
lyre provider models PROVIDER List the provider models the selected host reports.
lyre provider diagnostic PROVIDER --json Inspect its host environment and readiness.
lyre plugin ls List configured plugins.
lyre plugin init PATH --template lifecycle Write a new author project without installing or activating it.
lyre plugin check PATH --json Perform static checks without executing entries.
lyre plugin update --all --check Review available updates without installing them.
lyre plugin logs PLUGIN_ID Read recent plugin logs.

Explicit plugin installation, enable/disable, reload and removal are available under lyre plugin --help. Plugins are trusted, unsandboxed code. See installation and trust and authoring examples.

Standalone daemon lifecycle

Command Use it to
lyre daemon start Start the selected local home from saved configuration.
lyre status Check the selected daemon and endpoint.
lyre daemon stop Stop the standalone host and its running work.
lyre daemon restart Restart the selected worker.
lyre daemon config get KEY Read a saved setting.
lyre daemon config set KEY VALUE Change a saved setting; consult help for accepted values.
lyre pair Review owner pairing and print connection instructions.

Manage a desktop-owned daemon through the desktop app. Preserve homes, projects and saved connections when updating. Update instructions.

Scripting and complete command discovery 

lyre ls --json
lyre describe run --json
lyre describe --all --json

For structured agent results, lyre run --output-schema SCHEMA_FILE "TASK" waits for output matching a JSON schema. It cannot be combined with --background. Inspect errors and task results before treating an automation step as successful.

The registered command and flag catalog for 0.11.0-beta.3 includes advanced and compatibility commands. It records syntax, choices and registered defaults; it does not infer runtime validation, output schemas or whether external services are configured. The installed command's help and behavior remain authoritative.

Use lyre --help to discover additional families such as agent-scoped heartbeats, connected-host delegation and configured integrations. Those commands require their own host capabilities, authorization and destination setup. See Lyre workflow examples.