cli.md

Command-line behavior

LCM uses its own help renderer so every command has consistent usage, options, and examples.

Use lcm --help for the complete command list and lcm <command> --help for command-specific help. Commands grouped under daemon, config, machine, project, events, and connectors use the parent command's help page:

lcm daemon start --help
lcm config set --help
lcm machine recover --help
lcm project link --help
lcm connectors install --help

Nested help is resolved before command execution. A help request therefore never starts the daemon, changes a machine or project identity, installs or removes a connector, or performs another command action. For known commands, this preflight happens before required-argument validation, so lcm store --help and other incomplete command forms still show the relevant help page.

The store command accepts one tag per occurrence using either long spelling; the aliases can be mixed and retain command-line order:

lcm store "Use ensureDaemon before background promote" --tag type:solution --tags scope:lcm

In lcm store, --tag and --tags are repeatable single-tag aliases. This is different from lcm export --tags, which remains a comma-separated filter, for example lcm export --tags decision,architecture.

An unknown command writes an error and the complete command list to the terminal, completes both outputs, and then exits with status 1.

Daemon-dependent resilience

lcm doctor limits the complete daemon health exchange to two seconds. The deadline covers both the HTTP response and parsing its JSON body, so an unresponsive or partially responding local daemon cannot hold up the remaining diagnostics.

Authenticated daemon health includes a startup-captured SHA-256 digest of the packaged lcm.mjs entrypoint. LCM reuses a running daemon only when its version, storage backend, entrypoint, and runtime digest all match the invoking CLI. This also replaces a daemon left running across a same-version rebuild. A missing or mismatched digest makes the running daemon ineligible for reuse. When the daemon is responsive, lcm daemon restart uses the authenticated lifecycle and the owning systemd/launchd service to apply the replacement; the digest check does not grant PID, pathname, or token authority for offline recovery. A no-response or ambiguous service remains untouched and fails closed.

After lcm compact creates summaries, automatic promotion normally uses the same verified daemon connection. If that connection fails at the transport layer, LCM runs the managed-daemon recovery check, creates a fresh client, and retries promotion for that project once. It does not rerun compaction. Application-level promotion errors are not retried, and each later project gets its own independent recovery opportunity.

lcm compact --all reports each SQLite project that it cannot open, migrate, or scan as a failure in the Compact phase while continuing with readable projects. These failures produce a nonzero exit status and are not reported as “Nothing to compact.” A failed scan does not mark any session as processed. Back up the reported project database, resolve the SQLite or schema error, and rerun the command; the still-eligible sessions will be discovered again.

Managed-daemon recovery

Use the public commands for daemon recovery:

lcm doctor
lcm daemon restart

lcm doctor checks the daemon, hooks, connector registration, MCP server, and summarizer without asking an unknown process to stop. lcm daemon restart validates the effective configuration, asks the host service manager to replace the exact LCM service, and waits for authenticated health before returning. After changing configuration, run the restart command once; do not start a second daemon to work around a health failure.

Linux uses the current user's systemd --user manager and macOS uses the current user's launchd agent. Both integrations are deliberately one-shot: LCM does not request automatic restart (Restart=) or a launchd KeepAlive policy. If a daemon reaches its idle timeout and exits normally, the next LCM request recreates the registered service. This keeps idle terminals quiet while retaining a single, authenticated service owner.

Health observation has three outcomes. An HTTP response (including an error status, malformed body, or a body timeout after headers) stays on the normal authenticated path. A transport failure or deadline before any response is a no-response outcome and may be handed to the service manager only when the exact managed service is still identifiable. An unknown or ambiguous outcome is refused. LCM never turns an uncertain result into permission to signal a numeric PID or delete state files.

Detached and foreground launches are compatibility/debug modes, not managed recovery authorities. Windows, containers without a user service manager, and any unsupported or ambiguous launch are refused rather than force-recovered. Run lcm doctor, restore the host service manager, and retry lcm daemon restart.

There is no detached offline force-recovery option. A service-manager identity is an ownership authority for LCM, not a same-UID filesystem security boundary: another process running as the same operating-system user can still read or modify that user's files and runtime state. When recovery is refused, inspect the host with lcm doctor, restore the manager, and retry one explicit lcm daemon restart.

If a connector was removed or its installed paths are stale after an upgrade, repair it through the connector manager and then re-run doctor:

lcm connectors install <agent>
lcm connectors doctor <agent>
lcm doctor

Do not edit hook files or use process-kill commands as a recovery procedure. See Managed daemon recovery for the platform boundaries and the user-facing failure cases.