CLI Reference¶

li agent MODEL PROMPT [flags]        # single-turn agent
li team SUBCMD [flags]               # persistent team messaging
li o fanout MODEL PROMPT [flags]     # parallel workers
li o flow   MODEL PROMPT [flags]     # auto-DAG pipeline
li play NAME [ARGS]                  # sugar for `li o flow -p NAME`
li skill NAME                        # print a CC-compatible skill body to stdout

Three reusable primitives live under ~/.lionagi/:

See examples/ for minimal templates of each.

Common flags¶

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

Model spec: provider/model[-effort] — e.g. claude/opus-4-7-high, codex/gpt-5.4-xhigh. Bare aliases: claude → claude_code/sonnet, codex → codex/gpt-5.3-codex-spark, gemini-code → gemini_code/gemini-3.1-flash-lite-preview. Source: cli/_providers.py:72,145

li agent¶

One-shot agent turn or resumed conversation.

li agent [model] prompt [flags]

-r and -c are mutually exclusive (cli/agent.py:49). Common flags apply.

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="...") → api/branch.md#operate

li team¶

Persistent inbox messaging. Teams stored at ~/.lionagi/teams/{team_id}.json under fcntl.flock (cli/team.py:50).

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:284

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, msg count (cli/team.py:294). show TEAM — all messages with timestamps and read_by (cli/team.py:297). TEAM = ID, prefix, or name.

li team send¶

Source: cli/team.py:301

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

li team receive¶

Source: cli/team.py:322

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:29–119. 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 /Users/ocean/audit-out
Phase 3: Synthesis [claude/opus]...
Saved to /Users/ocean/audit-out

Worker outputs: worker_1.md … worker_N.md in artifact root (fanout.py:269). Synthesis: synthesis.md (fanout.py:317). Resume cancelled workers with li agent -r BRANCH_ID.

li o flow¶

Auto-DAG pipeline. Orchestrator plans a FlowPlan (agents + ops with depends_on edges); engine executes with dependency-aware parallelism. Control ops trigger re-planning up to 3 rounds (flow.py:705).

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:122–209. --background re-invokes python -m lionagi.cli without itself (cli/orchestrate/__init__.py:265). 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

# output:
Planning DAG...
Plan done (4.1s): 3 agents, 4 ops — o1:r1 | o2:i1←o1 | o3:t1←o2 | o4:r1←o3
Executing DAG: 3 agents / 4 ops...
  ▶ researcher started
  ✓ researcher done (8.2s)
  ▶ implementer started
  ✓ implementer done (22.1s)
  ▶ tester started
  ✓ tester done (18.4s)
Synthesis [claude/opus]...
Saved to ./parser-work/
Total: 55.8s

Use --dry-run to inspect the plan before running. Artifact dirs per agent: <save>/{agent_id}/. Python equivalent: Builder + Session.flow() → api/flow.md

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

A playbook is a YAML file that declares a reusable, parametric flow invocation: model, agent, effort, prompt template, and typed CLI args. Source of truth: ~/.lionagi/playbooks/<NAME>.playbook.yaml.

Playbook YAML shape¶

name: audit
description: Parametric audit pattern
argument-hint: '[--mode MODE] [--workers N]'   # CC-compatible display string

model: claude-code/opus-4-7
agent: orchestrator
effort: high

args:                       # explicit, typed schema (preferred)
  mode:
    type: str               # str | int | float | bool
    default: dry
    help: "audit mode: dry | security | dead-code"
  workers:
    type: int
    default: 8
  strict:
    type: bool
    default: false

prompt: |
  Run a {mode} audit with {workers} parallel workers. Strict: {strict}.

  Target: {input}

All playbook fields map to li o flow flags. If both args: and argument-hint: are present, args: wins. If only argument-hint: is present, it's parsed as CC does — [--flag VALUE] → string arg, [--flag] → bool arg, no type coercion.

Template interpolation¶

Inside prompt:, three rules:

1. {input} → the positional prompt text passed on the CLI.
2. {arg_name} → a declared arg (CLI override > playbook default).
3. If the template has no {...} placeholders, the positional text is appended with a blank line — same convention as Claude Code slash commands.

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 playbooks in ~/.lionagi/playbooks/
li play audit --help                # show playbook description, args, and usage

li play list¶

Lists all installed playbooks in ~/.lionagi/playbooks/.

li play list

# output:
audit        Parametric audit pattern              [--mode MODE] [--workers N]
refactor     Multi-step refactor with review       [--scope SCOPE]

li play NAME --help¶

Shows the playbook's description, its declared arguments with types and defaults, and a generated usage line. Does not execute the flow.

li play audit --help

# output:
audit — Parametric audit pattern

Usage: li play audit [--mode MODE] [--workers N] [--strict] PROMPT

Arguments:
  --mode MODE    str    default: dry    audit mode: dry | security | dead-code
  --workers N    int    default: 8
  --strict       bool   default: false

Prompt template:
  Run a {mode} audit with {workers} parallel workers. Strict: {strict}.

  Target: {input}

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

Ad-hoc specs (-f)¶

For one-off specs not worth installing globally:

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

-f takes an absolute/relative path; -p takes a bare name resolved under ~/.lionagi/playbooks/. They are mutually exclusive.

See examples/playbooks/ for ready-to-install playbooks with different shapes.

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 examples/skills/ for templates.

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 examples/agents/ for minimal/ and with-refs/ templates.

Run-ID and persistence¶

Every CLI invocation allocates a run directory. Source: cli/_runs.py:14. Run ID format: YYYYMMDDTHHMMSS-{6hex} (cli/_runs.py:61).

~/.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

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