CLI Reference¶

`fuseraft run`¶

Run a task against the orchestration team.

fuseraft run [task] [options]

Arguments

Argument	Description
`[task]`	Task description. If omitted, you are prompted interactively.

Options

Flag	Default	Description
`-c, --config <path>`	`config/orchestration.yaml`	Path to the orchestration config file. YAML (`.yaml` / `.yml`) and JSON (`.json`) are both accepted.
`-f, --task-file <path>`	—	Read the task from a plain-text file instead of the command line. Useful for long or multi-line tasks. Ignored when resuming.
`-r, --resume [sessionId]`	—	Resume an incomplete session. Omit the ID to choose from a list.
`--hitl`	off	Human-in-the-loop mode. Pauses after every agent turn; you can inject a message, press Enter to continue, or type `q` to quit.
`-o, --output <path>`	—	Write the full session transcript (with per-turn costs) to a Markdown file.
`--verbose`	off	Enable debug logging, including token counts per turn.
`--tools`	off	Show tool calls made by each agent inline in the turn panel.
`--no-banner`	off	Skip the ASCII banner. Useful for CI or piped output.
`--ci`	off	CI mode. After the session ends, reads `.fuseraft/test-report.json` and exits with code `2` if any criterion has `status: FAIL`. Exits `0` if the report is absent or all criteria pass.
`--devui`	off	Start a local web server and print a URL for real-time session visualization. See DevUI below.
`--work-dir <path>`	—	Set the working directory for the session. Priority: flag > `Security.FileSystemSandboxPath` in the config > current directory.

Examples

# Run with default config and inline task
fuseraft run "Add pagination to the user list endpoint"

# Read the task from a file (useful for long or multi-line tasks)
fuseraft run -f task.md
fuseraft run -f task.md -c my-team.json -o transcript.md

# Use a custom config — JSON or YAML both work
fuseraft run -c configs/research-team.json "Summarise recent papers on diffusion models"
fuseraft run -c configs/my-team.yaml "Refactor the auth module"

# Resume a specific session
fuseraft run --resume a3f92c1d

# Resume interactively (shows a selection list)
fuseraft run --resume

# Human-in-the-loop: review each turn before it continues
fuseraft run --hitl "Refactor the payment module"

# Show tool calls inline in the turn panel
fuseraft run --tools "Refactor the auth module"
fuseraft run --tools --hitl "Build a REST API in Go with JWT auth"

# Open a real-time visualization in the browser while the session runs
fuseraft run --devui "Build a REST API in Go with JWT auth"
fuseraft run --devui -c my-team.yaml "Migrate the database schema"

# Save a transcript
fuseraft run -o transcript.md "Build a REST API"

# Set the working directory explicitly (useful when the config has no sandbox path)
fuseraft run --work-dir ~/github/fuseraft/kiwi -c kiwi-dev.yaml "Add a string interpolation function to lib/string.kiwi"

# Work-dir is also inferred automatically from Security.FileSystemSandboxPath in the config
fuseraft run -c kiwi-dev.yaml "Add a string interpolation function to lib/string.kiwi"

Task input priority

When multiple task inputs are provided, the following order applies:

Session checkpoint — when resuming, the original task is always used; [task] and --task-file are ignored with a warning
--task-file — if supplied, the file contents are used as the task
[task] — the positional argument
Interactive prompt — if nothing is supplied, you are asked to type a task
Built-in demo — if the prompt is left blank, a default demo task runs

The task file is read as plain UTF-8 text. Leading and trailing whitespace is trimmed. The file can contain any content — Markdown, plain prose, bullet lists, structured specs.

Human-in-the-loop controls¶

There are two ways human approval can pause a session:

1. --hitl mode — after every agent turn

When --hitl is active, after each agent turn you see a prompt:

  ↩ Enter to continue  ·  type a message to redirect  ·  q to stop:

Enter — continue to the next agent turn
Any text — inject that text as a user message into the conversation, then restart the stream
q — save the checkpoint and exit cleanly

After the termination condition fires (e.g. TASK_COMPLETE), the session does not exit silently. A distinct post-session prompt appears:

  Session complete.
  Type a follow-up message to continue  ·  press Enter to exit:

Enter — end the session cleanly
Any text — inject a follow-up message and continue the session (the termination condition resets for the next run of the orchestrator)

This lets you keep interacting with the agent after a task completes without needing to restart or resume.

Shell command approval in --hitl mode

When --hitl is active, every shell_run and shell_run_script call pauses for approval before executing:

⏸ Shell command requested:
  python google_search.py "test"
Allow? (y/N):

y / yes — the command runs normally
Enter / anything else — the command is blocked; the agent receives [DENIED] and can try an alternative or ask you what to do

Shell command approval only applies in --hitl mode. In normal runs, shell commands execute without prompting.

2. Per-route approval gates — before a specific route fires

Individual routes can require explicit approval by setting RequireHumanApproval: true in the route config. This works independently of --hitl — approval gates fire even in normal (non-HITL) mode.

- Keyword: "HANDOFF TO REVIEWER"
  Agent: Reviewer
  Validator: TestReportValid
  RequireHumanApproval: true

When the keyword fires and all validators pass, the session pauses:

⏸ Route approval required.
  From:    Tester
  To:      Reviewer
  Keyword: HANDOFF TO REVIEWER

Approve? (y/N):

y / yes — the route fires and the target agent is invoked
Enter / anything else — the route is blocked; a "route blocked by operator" message is injected and the source agent is re-invoked so it can continue working or await further instructions

Stuck-agent escalation

If an agent fails the same validator 3 consecutive times, the session pauses regardless of --hitl mode:

⚠ HITL intervention required.
  Agent:    Developer
  Blocked:  RequireWriteFile (3 consecutive failures)
  Last error: ...

Redirect Developer (Enter to abort session):

Any text — inject a redirect message and restart the stream
Enter — abort the session (checkpoint is saved for --resume)

DevUI¶

--devui starts a lightweight ASP.NET Core server on a randomly assigned port and prints the URL before the session begins:

DevUI → http://localhost:54321

Open the URL in any browser. The page connects via Server-Sent Events and shows agent turns in real time as the session runs.

What the page shows

Session ID and task in the header
A card per agent turn, with agent name (consistently colour-coded), turn number, elapsed time, and token usage (input / output / cost)
Fenced code blocks (```) rendered as formatted <pre> elements
A spinning "thinking" indicator when an agent is selected but has not yet responded
Status chip in the header: live while running, ✓ complete or ✗ failed when the session ends

Replay on refresh

Refreshing the page replays the complete event history — all cards from the start of the session are reconstructed instantly. This means you can open the browser after the session has already started (or even after it finishes) and still see everything.

Combining with other flags

--devui is independent of --hitl, --verbose, and --ci and can be used alongside any of them:

fuseraft run --devui --hitl "Refactor the auth module"
fuseraft run --devui --ci -c my-team.yaml "Add integration tests"

`fuseraft sessions`¶

Manage session checkpoints.

fuseraft sessions [options]

Options

Flag	Default	Description
`-a, --all`	off	Include completed sessions (default shows only incomplete).
`-d, --delete <target>`	—	Delete session by ID, or `all` to delete all completed sessions.

Examples

# List incomplete sessions
fuseraft sessions

# List all sessions including completed
fuseraft sessions --all

# Delete a specific session
fuseraft sessions --delete a3f92c1d

# Purge all completed sessions
fuseraft sessions --delete all

Session files are stored in ~/.fuseraft/sessions/ with owner-only permissions.

`fuseraft plugins`¶

List all registered plugins and their functions.

fuseraft plugins [options]

Options

Flag	Default	Description
`-p, --plugin <name>`	—	Filter to plugins whose name contains this substring (case-insensitive).

Examples

# Show all plugins
fuseraft plugins

# Show only the Shell plugin
fuseraft plugins --plugin shell

# Show only MCP-sourced plugins (by partial name match)
fuseraft plugins --plugin demo

Output shows built-in plugins (C# methods decorated with [Description]) and MCP-sourced plugins (tools from connected servers) separately.

`fuseraft validate`¶

Validate a config file without starting a session.

fuseraft validate <path> [options]

Arguments

Argument	Description
`<path>`	Path to the orchestration config file. JSON (`.json`) and YAML (`.yaml` / `.yml`) are both accepted.

Options

Flag	Default	Description
`--strict`	off	Fail if any agent references a plugin not in the default built-in registry.
`--diagram`	off	Print a Mermaid flowchart of the workflow after validation.

Checks performed

File exists and contains valid JSON or YAML (syntax checked based on extension)
Top-level Orchestration key is present
Every agent has a non-empty Name, Instructions, and ModelId
Agent names are unique within the config
FunctionChoice values are auto, required, or none
Selection strategy type is sequential, llm, keyword, structured, or magentic
If LLM selection: Selection.Model is configured
If keyword selection: Routes array is non-empty
If magentic selection: Selection.Magentic.Model is configured; warns if a non-default Termination section is present (it is ignored for Magentic)
Termination strategy type is regex, maxiterations, or composite
Regex termination: Pattern is non-empty
Agent names referenced in termination strategies exist in the agents list
If Telemetry is set: OtlpEndpoint is a valid absolute URI
With --strict: every plugin name in any agent's Plugins list is registered

Exit codes

0 — validation passed (warnings may still be printed)
1 — one or more errors found

--diagram output

Prints a Mermaid flowchart LR to stdout after the validation result. Each keyword route becomes a labelled edge; validators appear as additional lines in the label. Terminal routes (the self-routing convention, e.g. APPROVED from Reviewer → Reviewer) point to a Done node rather than looping back.

fuseraft validate config/orchestration.yaml --diagram
fuseraft validate config/examples/orchestration.yaml --diagram

flowchart LR

  Task([Task])
  Planner["Planner"]
  Developer["Developer"]
  Tester["Tester"]
  Reviewer["Reviewer"]
  Done(["✓ Done"])

  Task --> Planner

  Planner -->|"HANDOFF TO DEVELOPER<br/>RequireBrief"| Developer
  Developer -->|"HANDOFF TO TESTER<br/>RequireWriteFile<br/>RequireShellPass"| Tester
  Tester -->|"HANDOFF TO REVIEWER<br/>TestReportValid"| Reviewer
  Tester -->|"BUGS FOUND"| Developer
  Reviewer -->|"REVISION REQUIRED"| Developer
  Reviewer -->|"REPLAN REQUIRED"| Planner
  Reviewer -->|"APPROVED<br/>RequireShellPass<br/>RequireReviewJudgement"| Done

Paste the output into mermaid.live to render it. The diagram is printed regardless of whether validation passed or failed, so it can be used to visually debug a broken config.

For sequential configs the diagram renders as a simple linear chain: Task → Agent1 → Agent2 → ….

`fuseraft config`¶

Display or list config files.

fuseraft config [path] [options]

Arguments

Argument	Default	Description
`[path]`	`config/orchestration.yaml`	Config file to display.

Options

Flag	Default	Description
`-l, --list`	off	List all `.json`, `.yaml`, and `.yml` files found under `config/` instead of displaying a single file.

Examples

# Display default config as formatted tables
fuseraft config

# Display a specific config
fuseraft config configs/devops-team.json

# List all configs in the configs/ directory
fuseraft config --list

`fuseraft init`¶

Generate a ready-to-run YAML orchestration config from an interactive wizard or explicit flags.

fuseraft init [output] [options]

Arguments

Argument	Default	Description
`[output]`	`config/orchestration.yaml`	Path to write the generated config.

Options

Flag	Default	Description
`-t, --template <name>`	interactive	Team template to use. See templates below.
`-m, --model <id>`	auto-detected	Model ID to use for all agents. Auto-detected from your API keys if omitted.
`--no-interactive`	off	Skip all prompts and generate with the supplied options and defaults.

Templates

Template	Description
`dev-team`	Four-agent pipeline: Planner → Developer → Tester → Reviewer with keyword routing
`research`	Two-agent pipeline: Researcher gathers information, Synthesizer produces the final report
`devops`	Three-agent pipeline for infrastructure and deployment tasks
`content`	Two-agent pipeline: Writer drafts, Editor refines and approves
`minimal`	Single general-purpose agent for simple tasks
`magentic`	Magentic-managed team: a manager LLM plans and coordinates Researcher + Developer agents dynamically

Model auto-detection

If --model is not provided, init inspects environment variables in this order and picks the default model for the first provider that has a key set:

Environment variable	Default model
`OPENAI_API_KEY`	`gpt-4o`
`ANTHROPIC_API_KEY`	`claude-sonnet-4-5`
`XAI_API_KEY`	`grok-4`
`GOOGLE_AI_API_KEY`	`gemini-2.5-flash`
`MISTRAL_API_KEY`	`mistral-medium-latest`
`DEEPSEEK_API_KEY`	`deepseek-chat`

If no key is set, gpt-4o is used as the fallback default.

Examples

# Interactive wizard (prompts for template, model, and output path)
fuseraft init

# Write to a custom path
fuseraft init config/my-team.yaml

# Non-interactive with explicit template and model
fuseraft init --template dev-team --model claude-sonnet-4-5
fuseraft init --template minimal --no-interactive

# Generate a Magentic team config
fuseraft init --template magentic
fuseraft init config/magentic-team.yaml --template magentic --model gpt-4o

# CI / scripted usage
fuseraft init config/ci-team.yaml --template dev-team --model gpt-4o --no-interactive

After generating, init prints the next steps:

Review:   fuseraft config config/orchestration.yaml
Validate: fuseraft validate config/orchestration.yaml
Run:      fuseraft run --config config/orchestration.yaml "Your task"

`fuseraft context`¶

Manage reference material that is automatically available to all agents in a session.

When a session starts, fuseraft reads the context index and appends a summary block to every agent's system prompt. Agents can then call read_file to access the files — no extra tool is needed and no discovery step is required.

Files are stored in .fuseraft/context/<name>/ inside the project working directory, so they are always inside the sandbox.

`fuseraft context add`¶

Import a file or directory into the context store.

fuseraft context add <source> [options]

Arguments

Argument	Description
`<source>`	Path to the file or directory to import. Supports `~` expansion.

Options

Flag	Default	Description
`-n, --name <alias>`	Filename without extension (files) or directory name (dirs)	Short alias used to reference this item in agent prompts. Only letters, digits, hyphens, and underscores are allowed.
`-d, --description <text>`	—	Human-readable description appended to the context entry in agent prompts.
`--dir <path>`	Current directory	Project directory containing `.fuseraft/`.

Examples

# Import a single file (name derived from filename: "architecture")
fuseraft context add ~/docs/architecture.pdf

# Import with an explicit alias and description
fuseraft context add ~/data/schema.sql --name db-schema --description "Production database schema"

# Import an entire directory
fuseraft context add ~/specs/ --name specs --description "Product specifications"

# Target a specific project directory
fuseraft context add ~/docs/runbook.md --dir ~/projects/my-app

After importing, agents see an entry like this at the top of their system prompt:

CONTEXT — reference material imported for this session (use read_file to access):
  [db-schema] — Production database schema
    .fuseraft/context/db-schema/schema.sql  (12.4 KB, imported 2026-04-12)

`fuseraft context list`¶

List all imported context items.

fuseraft context list [options]

Options

Flag	Default	Description
`--dir <path>`	Current directory	Project directory containing `.fuseraft/`.

Examples

fuseraft context list
fuseraft context list --dir ~/projects/my-app

`fuseraft context remove`¶

Remove a context item and delete its copied files.

fuseraft context remove <name> [options]

Arguments

Argument	Description
`<name>`	Alias of the context item to remove.

Options

Flag	Default	Description
`--dir <path>`	Current directory	Project directory containing `.fuseraft/`.

Examples

fuseraft context remove db-schema
fuseraft context remove specs --dir ~/projects/my-app

When the last item is removed the index.json file is also deleted, leaving the context directory clean.

CLI Reference¶

fuseraft run¶

Human-in-the-loop controls¶

DevUI¶

fuseraft sessions¶

fuseraft plugins¶

fuseraft validate¶

fuseraft config¶

fuseraft init¶

fuseraft context¶

fuseraft context add¶

fuseraft context list¶

fuseraft context remove¶

`fuseraft run`¶

`fuseraft sessions`¶

`fuseraft plugins`¶

`fuseraft validate`¶

`fuseraft config`¶

`fuseraft init`¶

`fuseraft context`¶

`fuseraft context add`¶

`fuseraft context list`¶

`fuseraft context remove`¶