CLI Reference¶

The CLI has two jobs: run agent work and operate the durable lifecycle around it. Start with li agent; move to fan-out or flow only when the work needs more than one worker.

Command map¶

Run work¶

Observe and control¶

Reuse, coordination, and operation¶

play, skill, and wait are compatibility-friendly top-level conveniences handled before the normal argparse registry, so they may not appear in the command list printed by li --help. They are supported surfaces and are documented here.

Reusable definitions can be project-local, user-global, or supplied by a trusted plugin:

See the repository examples for minimal templates of each.

Shared run flags¶

Available on li agent, li o fanout, li o flow. Source: cli/_providers.py

MCP servers are resolved once per launch, from the directory the command was run in: --mcp-config PATH names a file, --no-mcp-config states that there are none, and otherwise the nearest .mcp.json at or above that directory is used. On li o fanout and li o flow, every worker the launch builds is handed that one result, so no worker starts with servers the run did not resolve; li agent resolves the same way and warns when it hands a leg no servers because no config was found. A set read from a file named with --mcp-config is exclusive: the agent starts with those servers and no others. A set found by the .mcp.json lookup is additive and joins the servers the provider already configures.

Model spec: provider/model[-effort] — for example claude/opus-4-7-high or codex/gpt-5.4-xhigh. Current bare aliases include claude → claude_code/sonnet, codex → codex/gpt-5.3-codex-spark, gemini-code → gemini_code/gemini-4-argon, and pi → pi/gemini-2.5-flash. Use gemini, without -code, for the direct Google API provider rather than the Gemini CLI backend.

li agent¶

One-shot agent turn or resumed conversation.

li agent [model] prompt [flags]

-r and -c are mutually exclusive. --context-from is rejected together with -r / -c (resume already carries the source context). Common flags apply.

With persistence enabled, a fresh execution records its own generation before starting workers. Resuming a terminal branch uses its adopted persisted session and a new generation. A separate invocation cannot resume a session that is still running. --resume-on-timeout continues that same execution once: it keeps the session and generation, waits for the parent's owned work and database close, and starts a new diagnostic run directory through a single-use in-process handoff.

--context-from resolves the ref in order — session id, branch id, run id, then file path — erroring loudly on an unresolvable or ambiguous (2+ match) ref rather than spawning with silently-missing context. Distillation is mechanical (no LLM): a saved artifact/summary verbatim if it fits, else the initial instruction plus final assistant message, else a loudly-marked head/tail truncation.

li agent -a reviewer --bypass --context-from 20260420T110143-a1b2c3 --prompt-file review.md

li agent claude/sonnet "What does Branch.operate() do?"

# output:
Branch.operate() is the universal structured operation entry point...

[to resume] li agent -r 20260420T110143-a1b2c3 "..."

Python equivalent: branch.operate(instruction="...") → Branch API

Read status without starting a worker:

li agent status                         # latest agent-kind session in this project
li agent status SESSION_OR_INVOCATION   # full ID or unique prefix
li agent status SESSION_OR_INVOCATION --json

Agent caps and workload¶

Every CLI worker (codex, claude_code, gemini-cli, pi) takes a slot before its process starts, from li agent, li o fanout, li o flow or the Python API alike. Slots are lock files under $LIONAGI_HOME/leases/subagents/<pool>/, so every lionagi process sharing one LIONAGI_HOME counts against the same caps. With no cap set nothing is counted. ADR-0133 records the design.

0, empty or unset means no cap. A value that is not a whole number refuses the worker rather than letting it start uncounted. A worker that waits out the whole window is refused with one line naming the pool, its cap and the pids holding it, and li agent exits 75 (EX_TEMPFAIL): the same command succeeds once a slot frees. The refusal is recorded on the run as SubagentAdmissionRefusedError, a retryable provider error. A pool stays full at the smallest cap its holders read, so a raised cap takes effect as the agents admitted under the lower one finish.

The slot belongs to the lionagi process that started the worker and is released when the worker's process group has ended, or when that process exits however it exits. A slot whose recorded worker is still running counts as held even if the process that took it is gone.

An agent lionagi started cannot start another agent through lionagi. Every CLI worker starts with LIONAGI_AGENT_DEPTH set over any value it would inherit: 1, or 0 for a li agent launch of a profile named in LIONAGI_SEAT_PROFILES. li agent, li o flow, li o fanout and every CLI worker spawn refuse at once, before taking a slot, in a process that inherited a depth of 1 or more or that runs under a process started with one. The second check covers tools an agent starts with an environment of its own choosing, such as the MCP servers codex starts with only the variables its config names. li o flow --background and the lion MCP server's agent, flow, fan-out and play submits check in the process that is asked, before anything detaches: a detached run checks again, but once its launcher has exited it no longer runs under the agent that asked. For the same reason li schedule create, enable, trigger and apply, the MCP server's schedule create, trigger and enable verbs, and li studio refuse inside an agent before the Studio daemon is asked or started, since the daemon starts its runs outside the agent's process tree. The refusal is NestedAgentRefusedError, a provider error that is not retryable; li agent and li o exit 1 with one line naming the process that carries the depth, and the MCP server answers with a conflict error and starts no job. A session nobody started through lionagi (a Claude Code or Codex session opened by hand) carries no depth and starts agents as before, and so does an agent launched with a profile named in LIONAGI_SEAT_PROFILES, which starts at depth 0. An agent such a profile starts waits for no slot its own ancestors hold: when they fill the pool, it is refused at once. The caps bound how many agents run; this bounds how deep they start each other, whether or not a cap is set.

--workload (or a profile's workload) sets the class:

A resumed leg (-r, -c) runs with the class this launch resolves: --workload, else the profile's, else heavy. Resuming a light leg without -a or --workload light therefore runs it heavy; pass the flag again to keep it light.

In li o flow and li o fanout each worker takes its own profile's class, whatever the orchestrator's. A light codex worker is given no extra writable directory, so it writes only its artifact directory, and under --team-mode it is refused before it starts. An independent agent a light worker asks for without naming an assignee runs on the orchestrator's engine with the worker's class; when that engine is another one, an API model included, the request is refused. --retry-failed refuses to run such an agent again, and a resume without the flag refuses every failed node, so a run in which one failed is re-run from scratch.

li monitor prints the held slots per pool under its table, for example subagents: all 3/30, heavy 1/6, codex 2/4, using the caps in its own environment, and li monitor --machine carries the same data under subagents.

li team¶

Persistent inbox messaging. Teams are stored at ~/.lionagi/teams/{team_id}.json under fcntl.flock.

li team create NAME -m MEMBERS
li team list     [alias: ls]
li team show TEAM
li team send CONTENT -t TEAM --to RECIPIENTS [--from NAME] [--from-op OP]
li team receive  -t TEAM [--as MEMBER]   [alias: recv]

li team create¶

Source: cli/team.py

li team create "docs-team" -m "researcher,writer,reviewer"

# output:
Created team 'docs-team' (7fa0d9abbf5b)
  Members: researcher, writer, reviewer
  File: ~/.lionagi/teams/7fa0d9abbf5b.json

list — sorted by mtime; shows ID, name, members, and message count. show TEAM — all messages with timestamps and read_by. TEAM = ID, prefix, or name.

li team send¶

Source: cli/team.py

li team send "Research done — see research.md" \
  --team 7fa0d9abbf5b --to writer --from researcher --from-op o1

li team receive¶

Source: cli/team.py

li team receive --team 7fa0d9abbf5b --as writer

Python equivalent: session.send() / session.receive() → api/team.md

li o fanout¶

Three-phase: orchestrator decomposes → N workers in parallel → optional synthesis.

li o fanout [model] prompt [flags]

Source: cli/orchestrate/__init__.py. Common flags apply.

li o fanout claude/opus-high "Audit lionagi/session/ for stale API surface" \
  -n 3 --with-synthesis --save ./audit-out

# output:
Phase 1: Orchestrator decomposing task into 3 agent requests...
Phase 1 done (3.2s): 3 requests generated.
Phase 2: Fanning out to 3 workers: [claude/opus, claude/opus, claude/opus]
Phase 2 done (14.1s).
Saved 3 worker results to /path/to/audit-out
Phase 3: Synthesis [claude/opus]...
Saved to /path/to/audit-out

Worker outputs are worker_1.md … worker_N.md in the artifact root. Synthesis is written to synthesis.md. Resume cancelled workers with li agent -r BRANCH_ID.

li o flow¶

Auto-DAG pipeline. The orchestrator plans an initial list of TaskAssignment entries with assignees, dependencies, and execution modes; the engine executes them with dependency-aware parallelism. When reactivity is enabled, workers can emit SpawnRequest follow-up work without re-running the initial planner.

li o flow [model] prompt [flags]

-f and -p are mutually exclusive. --team-mode and --team-attach are mutually exclusive. Source: cli/orchestrate/__init__.py. --background re-invokes python -m lionagi.cli without itself. Common flags apply.

Team lifecycle summary¶

li o flow claude/opus "Write and test a CLI arg parser for a new subcommand" \
  --save ./parser-work --with-synthesis

Use --dry-run to inspect assignments, dependencies, and resolved model/mode routing before running. Artifact directories are <save>/{agent_id}/. Python equivalent: Builder + Session.flow() → api/flow.md

Checkpoint resume and live control are intentionally separate:

li o flow --resume RUN_OR_SESSION_ID      # prior process ended; replay checkpoint
li o ctl resume RUN_OR_SESSION_ID         # process is alive but paused

li o ctl¶

Address read/control operations to a durable ID:

li o ctl status ID
li o ctl pause ID
li o ctl resume ID
li o ctl msg ID "Prioritize correctness over breadth"

status reads sessions, invocations, plays, and branch-backed sessions. pause, resume, and msg queue control for a running flow; msg is available for flows using context-mode operator steering. Use li o ctl SUBCOMMAND --help for the command-specific ID and JSON options.

Foreground flows print Session: <full ID> after recording the session, before planning. Background launch prints the full session ID assigned to its child. Control actions accept an exact recorded session, invocation, play or run ID, an unambiguous 8-character hex prefix, or an unambiguous prefix of a run ID (the ID li agent prints) that reaches the T after its date, such as 20260801T0201. Any other string is looked up as an exact id first; a string shorter than eight characters or carrying a non-hex character is treated as a prefix only when it reaches that T and begins a recorded run ID, and one that begins both a run ID and another ID is refused as ambiguous. A run-id prefix that stops short of the T, such as 2 or 2026, therefore cannot act on a run; an eight-character hex string is read as a printed id prefix, so 20260801 acts on the session whose printed id it begins, exactly as any other eight-hex prefix does — unless a recorded run id also begins with those eight digits, which makes the string ambiguous and refused. Shorter prefixes remain available to status, which does not act on a run. An exact stored ID need not be a UUID. --invocation must name an existing invocation registered with li invoke start; unknown values fail before flow setup/planning or background launch, rather than silently disabling persistence. Both li o flow and li o fanout check it before anything is spawned. The flag does not register an alias.

While a flow is waiting for DAG execution, controls are deferred until its DAG execution poller starts, including pre-planning, graph construction and resumed run windows. The poller checks about every two seconds during DAG execution; this is not a delivery deadline or a guarantee before the first operation. Controls will not be applied after the poller stops. Flows whose poller has stopped, and older flows without control-delivery tracking, refuse new controls. The stop marker is published before the poll loop stops, and enqueue re-checks it in the same statement that inserts the control, so a run that has lost its poller refuses rather than queueing against a consumer that is gone. A control admitted just before the marker lands can miss the last poll; when the run's teardown writes its terminal status, every control still queued and unclaimed is closed as rejected rather than left pending. Teardown also closes them if a later teardown step fails after that status write. That teardown path closes the flow/play queue: a process killed outright runs no teardown, and neither li kill nor a reaper sweeps the queue, so a control queued in that window stays pending and li o ctl status renders it as never landed. li o ctl resolve closes only a row a consumer claimed and never reported back. Marker writes are best-effort: a failed stop-marker write can leave a stale active marker, so enqueue is never a delivery guarantee. Check status for application.

Pause/resume acts at operation boundaries before the concurrency limiter. Operations already past the pause gate, including those waiting for limiter capacity, may still start; running operations are not interrupted. Messages affect only operations prepared after delivery and are rejected if none remain pending. Applied pause/resume writes paused/executing with one retry after a phase-write failure; repeated write failure can leave telemetry stale. The paths that end a flow run clear current_phase in the same statement as the terminal status; a legacy or out-of-band terminal row can keep a stored phase, and reads hide one on a terminal row. Flow runs are sessions: use li monitor --type session, or --type invocation for registered invocations.

Playbooks (-f, -p, li play)¶

A playbook is the declarative tier of orchestration: a reusable YAML input to the flow planner. It is not the plan itself. Each invocation combines the playbook with that run's input, the orchestrator produces a run-specific FlowPlan, and each plan assignment becomes a branch-bound FlowOp. Source: lionhub/src/lionhub/orchestration/patterns.py and cli/orchestrate/flow.py.

Bare names resolve project-local .lionagi/playbooks/ first, then user-global ~/.lionagi/playbooks/, then active trusted plugins. Use <plugin>/<name> to select a plugin playbook explicitly.

Playbook YAML shape¶

description: Parametric audit pattern    # shown by `li play NAME --help`
argument-hint: '[--mode MODE]'           # used only when `args:` is absent

model: claude-code/opus-4-7
agent: orchestrator
effort: high
max_ops: 6
reactive: "off"

args:                       # typed schema; becomes real CLI flags
  mode:
    type: str               # str | int | float | bool
    default: dry
    help: "audit mode: dry | security | dead-code"

prompt: |
  Run a {mode} audit of {input}. Cite source evidence for every finding.

A playbook carries two kinds of key, read by different code.

Runtime fields configure the flow: model, agent, effort, prompt, workers, max_ops, deprecated max_agents, with_synthesis, bare, dry_run, show_graph, save, team_mode, team_attach, reactive, and artifacts. _validate_spec_fields in cli/orchestrate/__init__.py checks the type and bounds of whichever of these are present. It is a type check, not a field list: it does not enumerate a closed set and does not reject unknown keys. See the orchestration guide for types, bounds, and runtime effects. Quote reactive: "off"; bare YAML off is a boolean, but the loader requires this field to be a string.

Declaration fields describe the playbook's own interface: description, args, and argument-hint. They are read on a separate path. args is checked by _validate_args_schema, which fails the run on a malformed schema, and is turned into parser flags by inject_playbook_schema_into_parser. When args is absent, argument-hint is parsed into the same schema shape by _parse_argument_hint. The discovered playbook name comes from the filename.

Template interpolation¶

Inside prompt:, three rules:

1. {input} → the positional prompt text passed on the CLI.
2. {arg_name} → a declared arg (CLI override beats playbook default).
3. If the template has no {...} placeholders, the positional text is appended after a blank line.

Invocation¶

# Long form
li o flow -p audit --mode security "the auth service"

# Sugar
li play audit --mode security "the auth service"
li play list                        # list all discovered playbooks
li play audit --help                # show description, declared args, and usage
li play check audit                 # validate declared playbook artifacts/dependencies
li play status [ID]                 # latest play/flow status, or one durable ID
li play --resume ID                 # resume a checkpointed flow

li play list¶

Lists project-local, user-global, and active trusted-plugin playbooks. Plugin entries are namespaced as <plugin>/<name>.

li play list

li play NAME --help¶

Prints the playbook's description, a usage line built from argument-hint when one is declared, and an Arguments: block listing each declared arg with its type and default.

li play audit --help

--help is checked before any flags are forwarded to li o flow, so it never starts execution.

Submission is not validation¶

play.submit returns an allocated run ID after spawning the CLI child. The child then loads the playbook and calls _validate_spec_fields; a run ID is therefore a handle, not proof that the YAML is valid or that a result exists. Read it with job.status and job.output. Source: lionhub/src/lionhub/serve/mcp/jobs.py and cli/orchestrate/__init__.py.

Ad-hoc specs (-f)¶

For one-off specs not worth installing globally:

li o flow -f ./my-spec.yaml "target"

-f takes an absolute or relative path. -p takes a discovered bare name or an explicit <plugin>/<name> token. They are mutually exclusive.

The orchestration guide follows one playbook through its FlowPlan and a single FlowOp.

Skills (li skill)¶

A skill is static reference content the agent pulls on demand. Format is identical to Claude Code skills — you can symlink one source file into both ~/.claude/skills/<name>/SKILL.md and ~/.lionagi/skills/<name>/SKILL.md.

~/.lionagi/skills/commit/SKILL.md

---
name: commit
description: Conventional Commits style guide + safety rules.
---

# Commit conventions

... body ...

Commands¶

li skill NAME          # print body (post-frontmatter) to stdout
li skill list          # list installed skills
li skill show NAME     # print full file (frontmatter + body)

An orchestrator agent can shell out to li skill <name>, capture stdout, and inject the result into its own context — no extra protocol required.

See the skill examples for templates.

li monitor¶

Observe play/agent/run progress in real time. Replaces fragile file-polling and log-tailing with a single surface. Source: cli/monitor.py (add_monitor_subparser). Alias: li mon.

li monitor                      # table of all running entities
li monitor <id>                 # detail view for one run/play/agent/invocation
li monitor --watch              # live-refresh table
li monitor --watch <id>         # live-refresh detail view
li monitor --since 1h           # entities updated in the last hour, including terminal rows
li monitor --type session       # filter table by entity type
li monitor --type command --since 1h  # recent command actions, including failed fires
li monitor --project myproject  # filter sessions by project

Flow runs are sessions: use --type session, even when the table's type column labels the row flow. Use --type invocation for records registered through li invoke start. flow is not a supported --type value.

A session detail view includes a khive injection block when an opted-in profile recorded non-zero recall, injection, failure, degradation, or writeback counters. degraded_turns distinguishes a provider-contained transport failure from a successful recall that returned no context. The block contains aggregate counts, not injected source text.

For scripts, use a waiter instead of scraping the watch display:

li wait SESSION_ID PLAY_ID                 # any durable entity kinds; mixed IDs allowed
li wait ID_A,ID_B --interval 2

li monitor run SCHEDULE_RUN_ID             # follows on_success/on_fail children by default
li monitor run SCHEDULE_RUN_ID --no-chain  # wait for only the literal ID
li monitor run SCHEDULE_RUN_ID --follow    # keep watching for later schedule runs
li monitor run SCHEDULE_RUN_ID --max-wait 0

li wait accepts run, session, play, flow-invocation, and scheduled-run IDs or unique prefixes. li monitor run follows a watched run's scheduler chain by default; --no-chain disables that behavior. After the initial set drains, --follow keeps the monitor open and prints newly created schedule runs. The initial wait defaults to a bounded 900 seconds.

li kill¶

Terminate a running entity by id, or sweep stale entities whose OS process is already dead. Source: cli/kill.py (add_kill_subparser).

li kill abc123                        # kill by id prefix
li kill <session-id>                  # stop a worker process
li kill abc123 --reason 'stuck'
li kill abc123 --recursive            # kill + direct children (session -> invocation)
li kill --all-stale                   # sweep dead-PID sessions/invocations
li kill --all-stale --threshold 3600  # only rows older than 1h
li kill --all-stale --dry-run

--recursive scope boundary. Recursion only reaches PID-bearing workers, and an orchestrator row reaches them only through a link it recorded:

• Killing a play reaches its worker chain only if the play row records the session it started, in plays.session_id. One path binds that column: the Studio show importer, which resolves the session by name when it mirrors a show directory. A play created by a live run leaves it unset, and a worker session stores no play reference either, so there is no key to resolve those workers by. In that case the kill marks the play row blocked, prints an error saying no worker was stopped, and exits 1 — a play kill never reports success it did not achieve. Kill the worker session ids directly (li monitor lists them). --recursive is not needed for either case: a play row carries no PID of its own, so resolving its workers is the kill.
• Killing a session with --recursive also cancels its linked invocation.
• A show id cannot be killed directly today: only running rows are killable, and show rows persist as active (never running), so li kill <show-id> is rejected as already-terminal, with or without --recursive.

To stop everything under a show, kill the play id or session id directly (li monitor <show-id> lists its plays). --all-stale covers the abandoned case only as far as the recorded links allow: a play older than --threshold whose recorded worker session has gone terminal is marked blocked; a play that records no worker session is left alone, because age by itself cannot tell an abandoned play from one still doing hours of work. The sweep prints one line naming how many rows it skipped for that reason, and reports them as skipped_unlinked_plays in its closing counts. A show row is marked aborted only once it is older than --threshold and all of its plays are terminal.

li invoke¶

Group the sessions a skill spawns (e.g. /show, /codex-pr-review) into one parent invocation record, so the runs list and Studio dashboard collapse "14 sessions" into a single row. Opt-in — sessions spawned without --invocation behave exactly as before. See the CLI internals. Source: cli/invoke.py.

INV=$(li invoke start --skill show --prompt "resolve lionagi issues")
li play backend  ... --invocation "$INV"
li play frontend ... --invocation "$INV"
li invoke end "$INV" --status completed

end closes a running invocation, and it records --metadata on a row an earlier close already put in the requested status: that same-status close merges the payload without moving the stored status or end time, and exits 0; the same close with no --metadata also exits 0, since there is nothing left to record. --metadata merges key by key into the invocation's stored metadata, and the merge runs inside the store's own write, so a payload another closer records in between is merged with rather than overwritten and both closes keep their keys. Keys merge per RFC 7396: a nested object merges into the stored object, a key set to null is removed, and an array or scalar replaces the stored value. A stored value that is not an object (an old row whose metadata is a bare string, for instance) is kept under _discarded_node_metadata. An end that names a different status than the stored one — the row was cancelled, reaped, or closed by a sibling launch while the work ran — records neither the requested --status nor its --metadata. That refusal is reported on stderr and exits 1, and the stored status another writer recorded is left exactly as it is. The status write and the metadata merge are separate writes in that order, so a reader can see the terminal status a moment before the closer's metadata lands. Treat a zero exit as proof the status and metadata were saved.

li hooks¶

Import an existing Claude Code or Codex hooks configuration into this project's .lionagi/settings.yaml hooks_external: block, then record trust for the imported commands so they are allowed to execute. Trust is hash-pinned: approval is recorded against the content-hashed argv, so a command that changes after import must be re-approved before it runs. Source: cli/hooks.py.

li hooks import claude                   # reads .claude/settings.json
li hooks import codex .codex/hooks.json  # explicit config path
li hooks trust                           # review and approve pending commands
li hooks trust --yes                     # record trust without the prompt

li mcp¶

Serve an MCP server over stdio. The server is a control plane over this CLI: it submits li runs as detached background jobs and answers questions about them, so a submit returns a run_id immediately instead of blocking and the run keeps going in its own process group, surviving an MCP-server restart. Requires the mcp extra (pip install 'lionagi[mcp]'). Source: lionhub/src/lionhub/serve/mcp/.

li mcp            # serve over stdio (same as: python -m lionhub.serve.mcp)

The server advertises a single tool, request, and every operation is a namespaced verb passed to it. Seeing one entry in a client's tools/list is correct. Call request with help=true for the catalog of verbs.

Register it with any MCP client (e.g. an .mcp.json). The key here is the local name your client uses to launch the server; the name the server reports over the protocol is lion:

{
  "mcpServers": {
    "lion": { "command": "li", "args": ["mcp"] }
  }
}

Job records live under ~/.lionagi/mcp/jobs/<run_id>/; the authoritative run state is the CLI's own ~/.lionagi/runs/<run_id>/. In job.status, the top-level status is authoritative: the embedded run manifest is advisory and its own status may lag.

The verb catalog, the request result contract, and a worked submit-and-poll example are in the MCP server reference.

When a run's process is gone and nothing recorded how it came out¶

A background run normally records its own end: the CLI's terminal hook writes it, and a run stopped by li kill leaves it in the lifecycle store, which the server caches onto the job record. A run whose process dies before either of those happens leaves nothing behind at all — no surviving producer can ever write its end.

Where an observation positively establishes that the run's process is gone — the recorded pid holds no process, it disappears between two probes, or a live process holds the number and started at a different time, so it is a different process — job.status, job.list and job.wait record that end themselves and then report it:

outcome: "indeterminate" means the process is conclusively gone and no authoritative outcome was reported. It does not mean the work failed: the run may well have finished what it was doing before it died, and nothing survived to say either way. failed stays reserved for a reported terminal status classified as a failure, and a caller may retry a failed run under its own policy. Do not automatically retry such a run — an external side effect it never got to report may already have committed.

terminal_source says what wrote the end: cli_terminal_hook (the run's own terminal hook), lifecycle_cache (an end read back from the lifecycle store), spawn_failure (the spawn was caught failing), mcp_kill (the run was killed through this server), or mcp_orphan_reaper (this server, from the conclusive observation above). It is null on records written before the field existed.

For a run ended this way, finished_at is when the loss was established and recorded, not when the process exited — nothing surviving can report that instant. Any duration derived from it is therefore an upper bound on how long the run actually ran.

liveness_conclusion on job.status says what the observation established: process_gone, alive, or unknown. Only process_gone can end a run. unknown — a pid the OS cannot be asked about, a denied or unreadable identity probe — never does, and such a run stays non-terminal and advisory (possibly_orphaned), reported by job.wait under stopped_without_end.

job.wait's all_terminal means every valid requested run has a recorded end, including runs whose outcome is indeterminate. It does not mean every run succeeded or reported an outcome; read each entry's outcome for that.

Terminal notices¶

When a background run finishes, the server records its terminal status and, if a delivery command is configured, runs it — on every terminal state, including failure and kill. Nothing is configured out of the box, so the default is no notice. The command is an argv list run directly (never through a shell); the placeholders {run_id}, {status}, {label}, and {target} are substituted into its arguments, and the same fields are offered as a JSON object on stdin. {sender} names the actor signing the notice, {reason_code} carries the run's terminal reason when one was recorded, and {reason_detail} its finer detail; a reason placeholder with no value becomes empty.

Configure the command once via lionagi's own notify.on_terminal setting (~/.lionagi/settings.yaml or a project .lionagi/settings.yaml):

notify:
  on_terminal:
    adapter:
      kind: exec
      argv: ["/usr/local/bin/notify-run", "{run_id}", "{status}", "{target}"]

Or per submit: notify overrides the delivery command for one run (a JSON argv list), notify_seat fills the {target} placeholder, and notify_sender fills {sender}, naming the actor signing the notice. A submission that names either but has no delivery command from notify, the environment or the settings still runs, and its submit handle carries a notify_warning saying nothing will be sent. By default an explicit sender is checked against the submitting directory, as before. A deployment that wants callers to attest from their run directories sets LIONAGI_MCP_SENDER_ROOTS to an OS-path-separated list of absolute paths where the server is declared; then a declared sender is checked against the run directory the submission names in cwd, which must sit under one of those roots and hold .khive/config.toml. A submission that names no cwd is checked against the submitting directory, as before. The notice is delivered from the directory that was checked, so the identity it claims is the one it is signed with. The environment variables LIONAGI_MCP_NOTIFY_COMMAND, LIONAGI_MCP_NOTIFY_TARGET and LIONAGI_MCP_NOTIFY_SENDER set a process-wide default, and LIONAGI_MCP_NOTIFY_CWD names the directory delivery runs in instead of the checked (or submitting) one. These are the server operator's settings and are used as given: the sender check applies only to a notify_sender passed on the submit. With no sender from either, a delivery command that takes {sender} is not run, and one that does not reports whatever identity it resolves from the directory it runs in. Delivery outcome is recorded on the job and surfaced in job.status (notify_delivery), so a notice that failed to send is visible rather than silently lost. job.list carries the same outcome collapsed to one word in notify_delivery_state — delivered, delivered_unverified when it exited zero but that command shape's zero exit doesn't prove a send, failed when the notifier reported its own failure, unknown when an attempt's final result was interrupted or it was stopped for running past its deadline, or none when no notifier was configured — so a run whose notice never went out is spotted while scanning runs, not only when one is looked up. The full job.status.notify_delivery object is null only for a non-terminal run.

Spawning and the MCP server set¶

The four spawn verbs (agent.submit, flow.submit, fanout.submit, play.submit) accept exclude_mcp_servers, a list of server names to remove from the MCP config the submission resolves before its immutable snapshot is written. Every name must exist in that config — a name it does not declare is refused rather than silently ignored — and the parameter cannot be combined with mcp_config or no_mcp_config, since neither leaves a resolved set to filter. The removed names are reported as excluded_mcp_servers on the handle, the job record, and job.status.

A run is write-capable when its agent.submit arguments or its agent profile set yolo or bypass, or when it resumes or continues a branch, which reloads the provider settings that branch kept. Every flow.submit, fanout.submit and play.submit run is write-capable too, because it casts its workers onto profiles while it runs. By default a write-capable run gets no separate khive actor, and a submission without cwd is accepted as before. A deployment that wants each writable run to have its own identity sets LIONAGI_MCP_CHILD_ACTOR_SUFFIX to a non-empty suffix. Then a write-capable run submitted with a cwd gets the actor <submitting actor><suffix> (for example, with a suffix of :child, <submitting actor>:child), minted into <cwd>/.khive/config.toml before the run starts, so a writable run does not sign as the submitting identity. The mint copies the submitting directory's config and rewrites only its [actor] table; it refuses when the run has no own directory, when the submitting directory has no actor config, or when the run directory already holds a config other than exactly the one it would mint; a config that is exactly that one is reused as it is, and one minted before the submitting config changed is refused until it is removed. job.status reports the result as child_actor, child_actor_config and submitting_actor.

li handshake¶

Report what this installation is, for a program deciding whether it can talk to it. Pair it with --machine, since a program is the only caller this is for.

li handshake --machine

{"ok": true, "contract_version": 1,
 "data": {"contract_version": 1, "min_supported_version": 1,
          "implementation": "lionagi", "implementation_version": "0.30.2",
          "module": "/path/to/lionagi/cli"},
 "error": null}

contract_version is the machine-result contract this build speaks and min_supported_version is the oldest it still accepts. A caller checks both once at startup, then validates contract_version on every envelope afterwards — the binary at a pinned path is replaced during normal operation, so a handshake governs registration and never stands in for per-response checking.

module is where the code being served actually lives, which answers "is this the checkout I think it is" without guessing from a version number.

li runs¶

List the runs recorded on disk and what each one wrote.

li runs --machine [--limit N]

Each entry carries the run id, its state root, its artifact root, and the artifacts found there. It reports which runs EXIST and what they left behind, not whether any of them finished or succeeded — for that, ask li job status or the MCP request operation job.status, which carry the terminal and outcome derivations.

The artifact list is wrapped in the availability shape, so a directory that could not be read is reported as unavailable with a reason rather than as a run that produced nothing.

li lifecycle¶

Report what the lifecycle store records about one CLI run.

li lifecycle <run-id> --machine

This is the one path from a run id to the rows the lifecycle writers actually write. A normal teardown records an end; so does li kill, which writes the row and signals the process without touching the MCP job record or the run manifest. A caller holding only a run id and reading only those two would see a dead process with no recorded end, which is what an orphaned run looks like.

The answer is read-only and carries its own availability. An established answer with found: false means no session was ever recorded under this id. An unavailable one means the store could not be read at all, which is not a statement about the run. A caller that collapsed the two would report a run as finished, or as never started, on the strength of a database it never opened.

The store consulted is the one LIONAGI_STATE_DB_URL names when it is set, and the default otherwise — including for the question of whether a store exists at all, so a configured store is never reported missing because the default path is absent.

Machine mode: --machine¶

Any command that reaches the dispatcher accepts --machine, which turns its output into exactly one JSON object on stdout:

{"ok": true, "contract_version": 1, "data": {...}, "error": null}

Exactly one of data and error is present, and error.kind is a closed set a caller may branch on. Diagnostics, progress and warnings go to stderr, so stdout carries the object and nothing else — a caller can parse it without scanning for where the JSON starts.

Anything derived from a read that can fail is wrapped rather than flattened:

{"available": false, "value": null, "reason_code": "unreadable",
 "detail": "permission denied"}

This keeps "there are no artifacts" and "the artifacts directory could not be read" from sharing an encoding, which is the difference between a caller reporting an empty result and reporting a broken one.

Check the exit status before parsing. 78 means nothing executed — the environment could not run the work at all — and stdout must not be parsed on it, because attributing an environment fault to the submitted work is the misattribution the code exists to prevent.

The full contract, including how status, terminal and outcome divide the question of whether a run is over, is in ADR-0106.

li engine run¶

Run a domain-specific multi-agent engine pipeline without writing Python. Progress events stream to stderr; the final result is emitted as JSON on stdout for piping. Run records persist in the StateDB engine_runs table. Source: cli/engine.py. Provider workers belong to the engine's persisted signal-session row; a supplied --session-id remains a parent association. Owned worker work drains before the engine/session is terminalized and its database closes.

li engine run research 'What are the latest advances in GQA?'
li engine run review   'See artifact.py' --model claude/sonnet
li engine run coding   'Implement a BFS traversal' --test-cmd 'pytest'
li engine run hypothesis 'Finding: X causes Y' --export-dir ./out
li engine run planning 'Build a REST API'

Agent profile layout¶

A profile is resolved by name. Two layouts are supported:

~/.lionagi/agents/
    orchestrator/                      # preferred — directory layout
        orchestrator.md                # main profile
        patterns/                      # optional supplementary references
            empaco.md
        refs/
            commit-conventions.md
    legacy.md                          # flat layout — backward compat

li agent -a NAME and li o flow -a NAME check for <NAME>/<NAME>.md first and fall back to <NAME>.md. Supplementary files beside the main profile are not injected into the initial system prompt — the agent reads them on demand (via direct file reads or li skill).

Project-local .lionagi/agents/ takes precedence over ~/.lionagi/agents/.

See the agent examples for minimal/ and with-refs/ templates.

Profile format¶

A profile is YAML frontmatter followed by a markdown body (the system prompt). Source: cli/_agents.py (AgentProfile).

---
model: claude_code/opus
effort: high
yolo: true
---

You are an implementer. Write production code, not stubs...

All frontmatter fields are optional; matching CLI flags override them at invocation.

When lion_system: true, the global Lion system preamble is prepended to the body to form the system prompt. Set it to false for a verbatim body (e.g. when the profile already carries its own complete system prompt).

Run-ID and persistence¶

Task-producing agent, fan-out, flow, and playbook invocations allocate a run directory. Administrative commands such as doctor and monitor do not. Run IDs use the format YYYYMMDDTHHMMSS-{6hex}. Source: cli/_runs.py.

~/.lionagi/runs/{run_id}/
  run.json                        manifest (command, branches, artifact_root)
  branches/{branch_id}.json       branch snapshot — resumable via -r / -c
  stream/{branch_id}.buffer.jsonl live chunk buffer during streaming
  artifacts/                      deliverables — only when --save was NOT given

Authoritative state always lives under ~/.lionagi/runs/{run_id}/, so any branch is resumable from anywhere. User-facing artifacts (per-agent working dirs, synthesis.md, flow.log, flow_dag.png) land in the --save directory when one is provided, otherwise in artifacts/ under the run dir. The --save directory is not authoritative state — deleting it does not break -r.

Pre-run-scoped sessions (legacy ~/.lionagi/logs/agents/{provider}/{branch_id}) are still read as a fallback on resume.

Resume any prior branch:

li agent -r 20260420T110143-a1b2c3 "follow up"
li agent -c "continue most recent"

Env Vars¶

Sources: cli/agent.py · cli/team.py · cli/orchestrate/__init__.py · cli/orchestrate/fanout.py · cli/orchestrate/flow.py · cli/_providers.py · cli/_runs.py

Next: Python API reference