CLI

lk is the command-line client to the loopkeep daemon. Install it with the standalone installer or the desktop app. In an interactive terminal, lk with no arguments opens the terminal UI; piped or redirected, it prints its usage. This page is the full command surface, grouped.

Most commands act on a workspace. The target resolves in order: --workspace <id|path> → the LOOPKEEP_WORKSPACE environment variable → the current directory.

Workspace setup

Command	What it does
`lk init`	Create `.loopkeep/` in this workspace (starter policy + one workflow). Idempotent.
`lk trust`	Approve the current policy — enables the project policy and automatic triggers. Required again after the policy file changes.
`lk untrust`	Stop this workspace's triggers from firing automatically — the same kill switch as the desktop app. Manual and in-flight runs keep going; `lk trust` re-enables it.

Daemon

Command	What it does
`lk start`	Start `loopkeepd` (alias: `up`).
`lk stop`	Stop it (alias: `down`). Runs in flight are restored as interrupted on the next start.
`lk restart`	Stop, then start.
`lk status`	Daemon status.

Runs

Command	What it does
`lk run <workflow>`	Run a workflow by hand.
`lk rerun <run>`	Run a finished run's workflow again, reusing its trigger context.
`lk runs`	List runs.
`lk pause <run>` / `lk resume <run>`	Suspend at the next step boundary / resume.
`lk abort <run>`	End a run; the worktree is kept. `--rollback` resets to the last checkpoint first.
`lk take-over <run>`	Drive the run's claude session yourself, interactively.
`lk hand-back <run> [--summary <text>]`	End the take-over and return the run to running.

Inbox

Command	What it does
`lk inbox`	Attentions still waiting on you.
`lk watch [--json] [--no-notify]`	Stream new attentions as they arrive; rings on ask-first. `--json` emits NDJSON. Covers every workspace unless `--workspace` narrows it.
`lk approve <seq> [--steer\|--abort] [--instruction <t>]`	Decide a waiting attention. `--steer` requires an instruction; `--abort` stops the run.
`lk notify <message> [--url <url>]`	Post an external notification into the inbox — for CI hooks and scripts. Markdown supported.

Triggers

Command	What it does
`lk disable <workflow>` / `lk enable <workflow>`	Turn a workflow's automatic triggers off/on in this workspace. Manual and in-flight runs are unaffected.
`lk pause --all` / `lk resume --all`	Global kill switch: stop/restart trigger-driven runs across every workspace. Independent of trust.

Policy

Command	What it does
`lk policy explain <tool> [paths...] [--tags a,b] [--self <level>] [--workflow <name>] [--command <text>]`	Evaluate a hypothetical action and print every matching rule with its layer, file, and the final level.
`lk policy test <tool> [paths...] [--expect <level>] […]`	Same evaluation, exit-code driven: with `--expect`, 0 on match, 1 on mismatch; without it, the final level's rank (auto-approve 0, notify 1, ask-first 2, deny 3). Errors exit ≥ 10.

Both work without the daemon running — usable in CI.

Secrets

Command	What it does
`lk secret set <name> [--value <v>]`	Store a secret in the OS keychain (reads stdin without `--value`).
`lk secret list`	List the secret names recorded in this workspace.

GitHub Agentic Workflows

Command	What it does
`lk export --to-gh-aw <workflow> [--json]`	Translate to gh-aw with a green/yellow/red report.
`lk import <gh-aw-file>`	Import a gh-aw file; triggers it can't run locally become manual.

Workspaces & configuration

Command	What it does
`lk workspaces`	List registered workspaces.
`lk workspaces add <path> [--name <n>]` / `lk workspaces remove <id>`	Register / remove a workspace (home cannot be removed).
`lk global-max [<n>]`	Get/set the cap on runs in flight across every workspace.
`lk workspace-max [<n>\|clear]`	Get/set this workspace's own cap on runs in flight (`clear` removes it; the effective limit is the lower of this and `global-max`).
`lk retention [<days>\|off]`	Get/set how long finished runs' worktrees are kept.
`lk cleanup`	Remove finished runs' worktrees now (checkpoint branches are kept).

Console

Command	What it does
`lk login`	Pair this device with the Console (approved in your browser).
`lk logout`	Revoke this device and log out.
`lk account`	Show login state and the Console connection.

Runtime

Command	What it does
`lk update [--check\|--rollback\|--force]`	Update the runtime (`lk` + `loopkeepd` + adapter) to the latest release. `--check` only reports; `--rollback` returns to the previous version. Homebrew and desktop-app installs update through that channel instead.
`lk version`	Show the `lk` version, and the daemon's if it's running.

Environment variables

Variable	Meaning
`LOOPKEEP_WORKSPACE`	Default target workspace when `--workspace` isn't given.
`LOOPKEEP_SOCKET`	Daemon socket path (default `/tmp/loopkeepd.sock`).
`LOOPKEEP_CONFIG`	Path to `config.yaml`, overriding the default location.
`LOOPKEEP_DAEMON_BIN`	Explicit `loopkeepd` binary for `lk start`.