CLI Commands

lody is both:

a local runtime process started with lody start or lody daemon start
a one-shot CLI for workspace, GitHub repository, session, machine, and agent-config management

If you are new to Lody, read Quick Start, Sessions, Agent Config, and CLI Runtime Types first.

Help and Parameter Discovery

The built-in help output is the source of truth for exact flags and positional arguments.

bash

lody --help
lody session --help
lody session create --help
lody agent-config update --help

Use this pattern for any command:

Scope	Command
Top-level overview	`lody --help`
Command group	`lody <group> --help`
Specific subcommand	`lody <group> <subcommand> --help`

Command Overview

Command group	What it is for	Help command	Docs
`lody` / `login` / `logout` / `start`	Sign in, inspect the CLI, run the local runtime in the foreground	`lody --help`	Core commands
`daemon`	Start, stop, inspect, and read logs for the background daemon	`lody daemon --help`	Daemon mode
`workspace`	Discover accessible workspace IDs and slugs	`lody workspace --help`	Workspace commands
`github`	List GitHub repositories already linked to a workspace	`lody github --help`	GitHub commands
`project`	Manage local project registrations	`lody project --help`	Project commands
`session`	Create, chat with, inspect, archive, restore, and delete sessions	`lody session --help`	Session commands
`machine`	Inspect machines registered in a workspace	`lody machine --help`	Machine commands
`agent-config`	Manage agent configs and refresh runtime capabilities	`lody agent-config --help`	Agent config commands

Core Commands

Command	What it does	Help command
`lody`	Show top-level help and available commands	`lody --help`
`lody login`	Sign in and register the current machine	`lody login --help`
`lody logout`	Clear local credentials	`lody logout --help`
`lody start`	Run the Lody CLI in the current terminal	`lody start --help`

Commands that talk to the local runtime directly usually need lody start running in the foreground, or lody daemon start running in the background:

lody session create
lody session chat
lody session cancel
lody agent-config refresh-capabilities

Non-Interactive Login with `--auth`

By default lody login opens a device-authorization flow in your browser. On headless machines (CI runners, remote servers, containers) you can skip the browser by passing a pre-created CLI token instead:

bash

lody login --auth <token>
lody start --auth <token>          # sign in and start the runtime in one step

--auth <token> authenticates using a CLI token generated from Settings → Account → CLI Token in the desktop or web app. Click Create token, add a short note (for example CI runner, home server), and copy the token before closing the dialog — it is only shown once.
Tokens can be revoked at any time from the same panel. Revoking immediately disables every CLI that was using that token.
--auth accepts the same --machine-name <name> flag as interactive login, so you can override the default hostname.
If --auth is omitted on lody login, the command falls back to the interactive device-authorization flow; if it is omitted on lody start in an environment without an existing session, the runtime will prompt you to log in separately.

Store the token somewhere private (for example a secrets manager or a LODY_AUTH environment variable). It grants the same access as an interactive login for the workspaces you belong to.

Daemon Mode

lody daemon start runs the Lody CLI in the background and keeps it available for desktop, web, and mobile clients without leaving a terminal window open.

Command	What it does
`lody daemon start`	Start the background daemon
`lody daemon status`	Show runtime, machine, and connection status
`lody daemon logs`	Print recent logs, 50 lines by default
`lody daemon stop`	Stop the background daemon
`lody daemon restart`	Stop the daemon if running, then start it again

Common examples:

bash

lody daemon start
lody daemon status
lody daemon logs --lines 100
lody daemon restart
lody daemon stop

Daemon logs are written under ~/.lody/logs. Use lody daemon logs when startup fails or the UI cannot reach the CLI. Use lody start instead when you want live foreground output while debugging.

Workspace Commands

Use workspace commands when you need an exact workspace ID or slug for later commands.

Command	What it does	Help command
`lody workspace list`	List workspaces you can access	`lody workspace list --help`

workspace list

lody workspace list prints a table with ID, Name, and Slug. Use it before commands that accept --workspace <idOrSlug>.

bash

lody workspace list
lody workspace list --json

GitHub Commands

Use GitHub commands to inspect which repositories have already been linked to a workspace from Settings → GitHub.

Command	What it does	Help command
`lody github list`	List GitHub repositories linked to a workspace	`lody github list --help`

github list

lody github list prints the repositories already added to a workspace. It does not show every repository the GitHub App can access, only the ones currently linked into that workspace.

bash

lody github list --workspace my-team
lody github list --workspace my-team --json

Notable parameters:

--workspace <idOrSlug> chooses the target workspace
default output is a human-readable table with repository ID, full name, and visibility
--json returns structured repository data for automation

Exact flags:

bash

lody github list --help

Project Commands

Project commands manage local-project registrations that can later be selected in session creation.

Command	What it does	Help command
`lody project add [path]`	Register a local project directory	`lody project add --help`
`lody project list`	List registered local projects	`lody project list --help`
`lody project delete`	Delete registered local projects	`lody project delete --help`

For the exact current flags, always check the built-in help:

bash

lody project add --help
lody project list --help
lody project delete --help

Session Commands

Session commands are the main non-web workflow for Lody.

Before you use them:

session create, session chat, and session cancel need lody start or lody daemon start running on the current machine
session list, history, show, rename, archive, restore, and delete only need login plus workspace access
Use lody workspace list if you need a workspace ID or slug
sessionId can be passed positionally or through LODY_SESSION_ID

Subcommand	What it does	Needs local runtime	Help command
`lody session create`	Create a new session on the current machine	Yes	`lody session create --help`
`lody session chat`	Send a new turn to an existing local session	Yes	`lody session chat --help`
`lody session cancel`	Cancel the running turn on a local session	Yes	`lody session cancel --help`
`lody session list`	List sessions in a workspace	No	`lody session list --help`
`lody session history`	Read visible transcript history	No	`lody session history --help`
`lody session show`	Show session metadata	No	`lody session show --help`
`lody session rename`	Rename a session	No	`lody session rename --help`
`lody session archive`	Move a session out of the active list	No	`lody session archive --help`
`lody session restore`	Restore an archived session	No	`lody session restore --help`
`lody session delete`	Permanently delete an archived session	No	`lody session delete --help`

session create

Create a session attached to either a GitHub repository or a registered local project.

bash

lody session create --workspace my-team --agent-config codex --repo owner/repo "Fix the failing test"

Notable parameters:

--workspace <idOrSlug> chooses the target workspace
--agent-config <idOrName> chooses the agent config from Agent Config
--repo <owner/repo> attaches a GitHub repo
--local-project <id|name|path> attaches a previously registered local project
--repo and --local-project are mutually exclusive
--branch <name> selects the starting branch
--mode <modeId> and --model <modelId> override ACP selections
--env KEY=VALUE can be repeated and is stored with the session for later resume
prompt input can come from positional text, --prompt, --prompt-file, or stdin

Exact flags:

bash

lody session create --help

session chat

Send another user turn to an existing session on the current machine.

bash

lody session chat <sessionId> "continue from the last patch"
LODY_SESSION_ID=<sessionId> lody session chat --prompt "continue from the last patch"

Notable parameters:

sessionId can come from the positional argument or LODY_SESSION_ID
prompt input can come from positional text, --prompt, --prompt-file, or stdin
--mode <modeId> and --model <modelId> override ACP selections for this turn

Exact flags:

bash

lody session chat --help

session cancel

Cancel the currently running turn for a local session.

bash

lody session cancel <sessionId>

If cancellation fails, the command exits non-zero. Exact flags:

bash

lody session cancel --help

session list

List sessions in a workspace. By default it shows active sessions only.

bash

lody session list --workspace my-team
lody session list --workspace my-team --archived
lody session list --workspace my-team --all --limit 50 --json

Notable parameters:

--archived shows only archived sessions
--all includes both active and archived sessions
--limit <count> limits the result size
default output is a human-readable table; --json returns structured data

Exact flags:

bash

lody session list --help

session history

Read the visible transcript for one session. This command intentionally hides internal reasoning, tool calls, and other non-user-facing items.

bash

lody session history <sessionId> --limit 20
lody session history <sessionId> --all --reverse
lody session history <sessionId> --jsonl

Notable parameters:

--limit <count> returns the newest N visible turns
--all returns the full visible transcript
--reverse prints newest first
--json and --jsonl are useful for automation

Exact flags:

bash

lody session history --help

session show

Show session metadata such as status, machine, workspace binding, and history count.

bash

lody session show <sessionId>
lody session show <sessionId> --json

Exact flags:

bash

lody session show --help

session rename

Rename a session.

bash

lody session rename <sessionId> "New title"
LODY_SESSION_ID=<sessionId> lody session rename --title "New title"

If you rely on LODY_SESSION_ID, prefer --title so the title is not mistaken for an explicit session selector.

Exact flags:

bash

lody session rename --help

session archive

Archive a session so it disappears from the active list but remains recoverable.

bash

lody session archive <sessionId>

Exact flags:

bash

lody session archive --help

session restore

Restore an archived session back to the active list.

bash

lody session restore <sessionId>

This only works for archived sessions. Exact flags:

bash

lody session restore --help

session delete

Permanently delete an archived session. This also queues machine-side cleanup so worktree and runtime resources can be removed.

bash

lody session delete <sessionId>

This only works for archived sessions. Exact flags:

bash

lody session delete --help

Machine Commands

Use machine commands to inspect which machines are registered in a workspace and whether they look online.

Command	What it does	Help command
`lody machine list`	List machines in a workspace	`lody machine list --help`

machine list

bash

lody machine list --workspace my-team
lody machine list --workspace my-team --online-only
lody machine list --workspace my-team --json
lody machine list --workspace my-team --json --include-acp-capabilities

The default table shows only machine ID, name, online/offline status, and the merged CLI list (builtin CLIs plus registry agents in one CLI column).

by default, both online and offline machines are shown
use --online-only to filter the list down to machines with a recent heartbeat
--json omits acpCapabilities by default to keep payloads smaller
pass --include-acp-capabilities when you need the capability cache in JSON output

This is useful before agent-config refresh-capabilities.

Exact flags:

bash

lody machine list --help

Agent Config Commands

Agent config commands mirror much of the behavior from the web UI in Agent Config.

Before you use them:

selectors accept an ID or a name
if multiple configs or machines share the same name, the CLI requires an explicit ID
refresh-capabilities currently works only on the current machine from the CLI

Subcommand	What it does	Help command
`lody agent-config list`	List configs in a workspace	`lody agent-config list --help`
`lody agent-config show`	Show one config	`lody agent-config show --help`
`lody agent-config create`	Create a new config	`lody agent-config create --help`
`lody agent-config update`	Update an existing config	`lody agent-config update --help`
`lody agent-config delete`	Delete a config	`lody agent-config delete --help`
`lody agent-config refresh-capabilities`	Refresh supported modes, models, and options	`lody agent-config refresh-capabilities --help`

agent-config list

bash

lody agent-config list --workspace my-team

Shows the config ID, name, agent type, and description.

agent-config show

bash

lody agent-config show <idOrName>
LODY_AGENT_CONFIG_ID=<id> lody agent-config show

Shows the config fields in a human-readable form or JSON.

agent-config create

Create a config for a built-in or registry agent runtime.

bash

lody agent-config create \
  --workspace my-team \
  --agent-type codex \
  --name "Codex Default" \
  --env OPENAI_API_KEY=... \
  --prompt "Always run tests before finishing"

Notable parameters:

--agent-type <type> is required
claude and codex are treated as built-in runtimes
all other agent types are treated as registry runtimes
--env KEY=VALUE can be repeated
--env-file <path> loads env vars from a file
--prompt or --prompt-file sets the default prompt prefix

Exact flags:

bash

lody agent-config create --help

agent-config update

Update a config in place.

bash

lody agent-config update <idOrName> --name "Codex CI"
lody agent-config update <idOrName> --env OPENAI_API_KEY=... --unset-env OLD_KEY
lody agent-config update <idOrName> --prompt ""

Notable parameters:

--name updates the display name
--description "" clears the description
--env and --env-file merge new environment values
--unset-env KEY removes one or more environment variables
--prompt "" clears the default prompt prefix

Exact flags:

bash

lody agent-config update --help

agent-config delete

bash

lody agent-config delete <idOrName>

Deletes one config by ID or unique name.

agent-config refresh-capabilities

Refresh the capabilities cached for one agent config on the current machine.

bash

lody agent-config refresh-capabilities <idOrName> --workspace my-team

Use it after:

installing or upgrading a coding CLI
changing the environment of an agent config
updating available models or modes on the machine

Notable parameters:

--machine <idOrName> defaults to the current machine
the selected machine must be online
the CLI currently rejects remote-machine refresh; use the current machine for this command
--json and --jsonl are supported for automation

Exact flags:

bash

lody agent-config refresh-capabilities --help

Common Examples

bash

# Find the workspace id or slug you want to use
lody workspace list

# Inspect GitHub repositories already linked to that workspace
lody github list --workspace my-team

# Inspect agent configs in that workspace
lody agent-config list --workspace my-team

# Start the local daemon in the background
lody daemon start

# Foreground mode is useful for temporary debugging
lody start

# Create a session in a GitHub repo
lody session create \
  --workspace my-team \
  --agent-config codex \
  --repo owner/repo \
  "Fix the failing tests"

# Read the latest visible transcript turns
lody session history <sessionId> --limit 20

# Inspect machines and refresh capabilities on the current machine
lody machine list --workspace my-team --online-only
lody agent-config refresh-capabilities codex --workspace my-team

CLI Commands ​

Help and Parameter Discovery ​

Command Overview ​

Core Commands ​

Non-Interactive Login with --auth ​

Daemon Mode ​

Workspace Commands ​

workspace list ​

GitHub Commands ​

github list ​

Project Commands ​

Session Commands ​

session create ​

session chat ​

session cancel ​

session list ​

session history ​

session show ​

session rename ​

session archive ​

session restore ​

session delete ​

Machine Commands ​

machine list ​

Agent Config Commands ​

agent-config list ​

agent-config show ​

agent-config create ​

agent-config update ​

agent-config delete ​

agent-config refresh-capabilities ​

Common Examples ​

CLI Commands

Help and Parameter Discovery

Command Overview

Core Commands

Non-Interactive Login with `--auth`

Daemon Mode

Workspace Commands

workspace list

GitHub Commands

github list

Project Commands

Session Commands

session create

session chat

session cancel

session list

session history

session show

session rename

session archive

session restore

session delete

Machine Commands

machine list

Agent Config Commands

agent-config list

agent-config show

agent-config create

agent-config update

agent-config delete

agent-config refresh-capabilities

Common Examples