Start with the mechanics

CLI concepts

Commands that matter

The CLI wraps an agent run with the lease protocol. Server-host commands stand up the control plane; agent-machine commands claim territory and keep the map honest.

Server host

managent try is the one-command first-success path after install — seed a local home (~/.managent), write env.sh, start the API, optionally replay the two-agent collision demo, print MCP/CLI wiring, and open the dashboard. Flags: --reset, --no-demo, --no-open. From a monorepo checkout, npm run try at the repo root is the equivalent dev-stack path.

managent server boots the coordination API and dashboard for ongoing use (PORT default 8787, HOST default 127.0.0.1). managent init / seed creates org, API keys, and repo records — keys print once. managent doctor runs preflight checks (Node floor, DB path traps, license, API reachability) with fix suggestions.

managent run

The primary agent-machine command. Acquires a file/glob or inclusive line-range lease, auto-registers a stable agent identity, stamps territory metadata, sets non-territory tracked files read-only for the child (Mechanism A — same-UID bypassable; managent repair recovers after SIGKILL), heartbeats every held lease (~65s), and releases on exit — including non-zero exits and graceful signals.

Omit --paths to let the server predict scope from the task description. Hotspot paths split into short-TTL child leases; the CLI waits for all of them, prints multi-lease guidance, and heartbeats each id. Without --wait, a queued lease exits 75 (EX_TEMPFAIL) so schedulers can retry. With --wait, transient poll failures retry with backoff and honor Retry-After.

status and watch

managent status --repo owner/name prints a one-shot territory map: active and queued leases, queue depth, paths. managent watch polls GET …/map (default every 2s), redraws on a TTY, and shows plan status when a fleet plan exists. Same ground truth the dashboard reads — laptop, CI, and cloud share one map.

managent mcp

MCP server over stdio for Claude Code and similar hosts. Tools cover link/unlink, acquire / check / extend / shrink / release, get map, announce, and sync awareness. Coordination tools stay dormant until the checkout is linked (managent link writes .managent-link.json — no secrets; safe to commit) or the explicit link gate is disabled. Treat MCP config as secret storage for the embedded API key.

managent hook

managent hook install adds optional pre-commit and pre-push territory guards that inspect git diff --unified=0 against active claims. Only enforcement_level=hard_fail exits 1 on out-of-territory hunks; other levels log and exit 0. Hooks are bypassable with --no-verify — pair with PR verify so bypasses cannot land. uninstall / check manage and inspect.

managent execute

Orchestrates Intent → Fleet Plan → Attested Merge over the deterministic partition engine and lease/verify layers. --dry-run partitions without locking; default prepare-and-complete prints attestation; --prepare, --handoff, and --agent cover lock-only, human step-through, and per-step spawn. Attestation records claim limitations honestly — advisory enforcement is not a crypto signature; empty pairs_checked is not proof.

Enforcement honesty

Default leases are advisory at the filesystem. Harden with --runtime=hardened when the threat model requires a VFS boundary, and require managent enforce verify-pr / GitHub checks so local bypasses cannot land. Full posture: security. Interactive proof: demo, merge, semantic.