# CLI Reference

```bash
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/`:

| Primitive | Location | Invocation |
|-----------|----------|------------|
| Agent profile | `~/.lionagi/agents/<name>/<name>.md` | `li agent -a <name>` / `li o flow -a <name>` |
| Skill (static ref) | `~/.lionagi/skills/<name>/SKILL.md` | `li skill <name>` |
| Playbook (parametric flow) | `~/.lionagi/playbooks/<name>.playbook.yaml` | `li play <name>` |

See [`examples/`](../examples/) for minimal templates of each.

---

## Common flags

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

| Flag | Default | Notes |
|------|---------|-------|
| `--yolo` | false | Auto-approve all tool calls |
| `-v, --verbose` | false | Stream real-time output; suppresses final print |
| `--theme {light,dark}` | none | Terminal theme |
| `--effort LEVEL` | none | Override effort; claude: `low medium high xhigh max`; codex: `none minimal low medium high xhigh`; gemini: unsupported (`cli/_providers.py:24,44`) |
| `--cwd DIR` | none | Working directory for CLI endpoint |
| `--timeout SECONDS` | none | Hard timeout; partial branches saved |

**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.

```bash
li agent [model] prompt [flags]
```

| Arg/Flag | Default | Notes |
|----------|---------|-------|
| `model` | — | Spec or alias. Omit with `-r` or `-c`. `cli/agent.py:156` |
| `prompt` | — | Message to send. `cli/agent.py:165` |
| `-a, --agent NAME` | none | Profile by name. Resolves `.lionagi/agents/<NAME>/<NAME>.md` first, then legacy `.lionagi/agents/<NAME>.md`. Sets model/effort/system/yolo. `cli/agent.py:167` |
| `-r, --resume BRANCH_ID` | none | Resume prior branch. `cli/agent.py:178` |
| `-c, --continue-last` | false | Resume most recent branch. `cli/agent.py:184` |

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

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

```text
# 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`](api/branch.md#operate)

---

## `li team`

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

```bash
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`

| Arg/Flag | Required | Notes |
|----------|----------|-------|
| `name` | yes | Team name |
| `-m, --members` | yes | Comma-separated member names |

Source: `cli/team.py:284`

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

```text
# 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`

| Arg/Flag | Required | Default | Notes |
|----------|----------|---------|-------|
| `content` | yes | — | Message text (positional) |
| `--team, -t` | yes | — | Team ID or name |
| `--to` | yes | — | `all` or comma-separated names |
| `--from` | no | `_cli` | Sender name |
| `--from-op` | no | none | Op id; ties signal to a specific flow invocation |

Source: `cli/team.py:301`

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

### `li team receive`

| Flag | Required | Default | Notes |
|------|----------|---------|-------|
| `--team, -t` | yes | — | Team ID or name |
| `--as` | no | none | Mark as read for this member; omit = see all |

Source: `cli/team.py:322`

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

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

---

## `li o fanout`

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

```bash
li o fanout [model] prompt [flags]
```

| Flag | Default | Notes |
|------|---------|-------|
| `-a, --agent NAME` | none | Orchestrator profile. `cli/orchestrate/__init__.py:49` |
| `-n, --num-workers N` | 3 | Worker count; ignored when `--workers` set |
| `--workers M1,M2,...` | none | Per-worker model specs (each can include effort suffix) |
| `--max-concurrent N` | 0 | Max concurrent (0 = all) |
| `--with-synthesis [MODEL]` | false | Enable synthesis; bare = orchestrator model |
| `--synthesis-prompt TEXT` | none | Override synthesis instruction |
| `--output {text,json}` | text | Output format |
| `--save DIR` | none | Write artifacts here |
| `--team-mode [NAME]` | none | Create persistent team; bare = `"fanout"` |

Source: `cli/orchestrate/__init__.py:29–119`. Common flags apply.

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

```text
# 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`).

```bash
li o flow [model] prompt [flags]
```

| Flag | Default | Notes |
|------|---------|-------|
| `-a, --agent NAME` | none | Orchestrator profile. Resolves `.lionagi/agents/<NAME>/<NAME>.md` first, then legacy `.lionagi/agents/<NAME>.md`. |
| `-f, --file PATH` | none | Load flow spec from YAML/JSON file. File values are defaults; CLI flags override. |
| `-p, --playbook NAME` | none | Load playbook from `~/.lionagi/playbooks/<NAME>.playbook.yaml`. Playbook's declared args are injected as additional flags. |
| `--with-synthesis [MODEL]` | false | Final synthesis after all ops |
| `--max-concurrent N` | 0 | Max concurrent agents per phase (0 = all) |
| `--max-agents N` | 0 | Cap total ops (0 = unlimited) |
| `--dry-run` | false | Plan DAG and print; no execution |
| `--show-graph` | false | Render DAG as matplotlib PNG into `--save` dir |
| `--bare` | false | Ignore agent profiles; all workers use CLI model |
| `--background` | false | Subprocess run; requires `--save`; monitor `tail -f <save>/flow.log`; child inherits `LIONAGI_RUN_ID` (`cli/_runs.py:57`) |
| `--output {text,json}` | text | Output format |
| `--save DIR` | none | Artifact dir; required for `--background` |
| `--team-mode [NAME]` | none | Create a FRESH team every invocation (new UUID). Bare = `"flow"`. |
| `--team-attach NAME` | none | Upsert: attach to existing team by NAME (preserving message history) or create if missing. Mutex with `--team-mode`. |

`-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

| Goal | Flag | Behavior |
|------|------|----------|
| One-off parallel workers, no shared history | `--team-mode [NAME]` | New UUID every invocation. Messages posted; team discarded conceptually. |
| Persistent thread across invocations | `--team-attach NAME` | First call creates; subsequent calls attach to the same team (same UUID, same history). No pre-step required — you never have to `li team create` first. |
| Strict attach (error if missing) | `li team create NAME -m ...` first, then `--team-attach NAME` | Explicit human-in-the-loop for shared, long-lived teams. |

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

```text
# 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`](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

```yaml
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

```bash
# 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/`.

```bash
li play list
```

```text
# 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.

```bash
li play audit --help
```

```text
# 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:

```bash
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/`](../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`.

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

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

# Commit conventions

... body ...
```

### Commands

```bash
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/`](../examples/skills/) for templates.

---

## Agent profile layout

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

```text
~/.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/`](../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`).

```text
~/.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:

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

### Env Vars

| Variable | Purpose | Source |
|----------|---------|--------|
| `LIONAGI_RUN_ID` | Child inherits parent run ID (background flows) | `cli/_runs.py:57` |
| `LIONAGI_HOME` | Override `~/.lionagi/` base dir | `lionagi/utils.py` |
| `OPENAI_API_KEY` | OpenAI REST API key (for `iModel`, not for `codex` CLI alias) | `lionagi/config.py` |
| `ANTHROPIC_API_KEY` | Anthropic REST API key (for `iModel`; `claude` alias uses `claude login` instead) | `lionagi/config.py` |
| `GOOGLE_API_KEY` | Gemini key | `lionagi/config.py` |
| `GROQ_API_KEY` | Groq key | `lionagi/config.py` |

---

*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](api/index.md)
