Getting Started

Prerequisites

• Access to at least one supported model provider (see Models & Providers) — a cloud API key, or a local model via Ollama (no key required)
• Docker Desktop (only required for the CodeExecution plugin)
• Git (only required for the Git plugin)
• .NET 10 SDK (only required if building from source)

Install

Option A — install script (recommended)

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/fuseraft/fuseraft-cli/main/install.sh | bash

Downloads the latest release binary to ~/.local/bin and prints a PATH hint if needed. Pass --system to install to /usr/local/bin instead.

Windows

irm https://raw.githubusercontent.com/fuseraft/fuseraft-cli/main/install.ps1 | iex

Downloads the latest release binary to %LOCALAPPDATA%\fuseraft\bin and adds it to your user PATH.

Once installed, fuseraft is available on your PATH (you may need to restart your terminal on Windows).

Option B — build from source

git clone <repo-url>
cd fuseraft-cli
./build.sh          # Linux/macOS
.\build.ps1         # Windows

The default target compiles, tests, and publishes a self-contained single-file binary to bin/fuseraft (Linux/macOS) or bin\fuseraft.exe (Windows). Use ./bin/fuseraft (or .\bin\fuseraft.exe) in place of fuseraft in the commands below.

Other targets:

./build.sh --target=Build                        # compile only
./build.sh --target=Test                         # compile + run tests
./build.sh --target=Pack --runtime=linux-x64     # single-file archive
./build.sh --target=Lint                         # format check
./build.sh --configuration=Debug --target=Build  # debug build

Set your API key

Option A — user config (recommended)

fuseraft (or fuseraft repl) detects first-time usage and walks you through a short setup wizard before starting the session. It asks for a provider URL and API key (leave the key blank for Ollama), tests the endpoint’s model listing, and lets you pick a model from the live results — falling back to a free-typed model ID if the endpoint can’t be reached. Settings are then stored in ~/.fuseraft/config (without the key) and your OS keychain (for the key):

$ fuseraft
No configuration found at ~/.fuseraft/config

Provider setup
Configure your provider and API key, then pick a model.

Provider URL  (http://localhost:11434): https://api.anthropic.com
API Key       (leave blank for Ollama): ••••••••

Model  (2 available from https://api.anthropic.com)
> claude-sonnet-4-6
  claude-opus-4-6

>

The config is saved after the first successful reply. Once saved, subsequent fuseraft invocations start immediately using those defaults. Use /provider setup inside the REPL to reconfigure the provider/model/key at any time, or fuseraft settings show/fuseraft settings set <key> <value> to view or tweak everything else the file holds (sampling defaults, REPL startup defaults, telemetry, skill curation, model overrides) — see CLI Reference — fuseraft settings.

Typing Anthropic’s bare endpoint here (not its /v1 OpenAI-compatible path) is what lands you on the native anthropic provider — see Models & Providers — anthropic for why that’s the one you want for Claude (it’s what makes prompt caching available).

The API key is stored in the OS keychain — never in the config file, and never in plaintext on disk anywhere:

Platform	Store
Linux	GNOME Keyring (secret-tool / libsecret)
macOS	Keychain (security CLI)
Windows	Credential Manager (Win32 API, works in Git Bash)

If no keychain is reachable, fuseraft does not fall back to writing the key to disk — it keeps the key in memory for the current session and tells you to set a provider environment variable (e.g. ANTHROPIC_API_KEY) instead. See Security — API key storage for details.

Relocating ~/.fuseraft

If the OS home directory isn’t durable across sessions — e.g. a roaming or ephemeral profile on an RDS/VDI pool that assigns a different machine per connection — point fuseraft at a persistent location instead, such as a network share or mapped drive, by setting FUSERAFT_HOME before running any fuseraft command:

export FUSERAFT_HOME=/mnt/shared/fuseraft   # or, on Windows, e.g. Z:\fuseraft

This relocates the entire global root (config, sessions, logs, scratchpad, skills, memory) to the given directory. Project-local .fuseraft/ directories inside each repo (tracked by git) are unaffected. The API key itself is never part of this — it still only ever lives in the local OS keychain or in memory for the current session; see Security — API key storage.

Option B — environment variable

Export the key for your provider before running:

export ANTHROPIC_API_KEY=<your-key>
# or OPENAI_API_KEY, XAI_API_KEY, GOOGLE_AI_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY

For other providers see Models & Providers.

Option C — VS Code extension

The fuseraft VS Code extension stores your API key in VS Code’s built-in secure storage (backed by the OS credential store on each platform). When the extension launches a terminal or runs a command, it automatically injects the key as FUSERAFT_API_KEY and passes --vscode to the CLI. The CLI then reads the key from that environment variable instead of the OS keychain.

You do not need to set anything manually — configure your provider once via fuseraft: Configure fuseraft in the VS Code command palette and the key is available to all fuseraft commands run through the extension.

Start a REPL session

For quick questions or single-model chat, run fuseraft with no subcommand:

fuseraft

No config file needed. The REPL auto-detects your provider from the API key stored in ~/.fuseraft/config (or runs the setup wizard on first use). Type a message and press Enter. Use /help inside the session to see available commands.

Every session is auto-saved after each turn. Resume a previous session at any time:

# List resumable sessions from inside the REPL
/sessions

# Resume by ID (shown in the header at startup)
fuseraft repl --resume a87569bc

Working across more than one project tree in a session? Add --include <dir> (repeatable) for each extra root:

fuseraft repl --include ../shared-lib --include ../other-service

The launch directory and every --include root show up in the startup banner as Included:. See REPL — The safety model for how this interacts with sandboxing and --yolo.

---

Run your first session

Option A — generate a config with init

The fastest way to get started is fuseraft init. It walks you through a short wizard and writes a ready-to-run YAML config:

fuseraft init

You’ll be prompted to pick a team template, confirm a model (auto-detected from your API keys), confirm a provider URL (defaults to the endpoint saved in ~/.fuseraft/config), and choose an output path. Then:

fuseraft run -c .fuseraft/config/orchestration.yaml "Add a hello-world endpoint to this project"

For non-interactive or CI use:

fuseraft init --template solo --no-interactive
fuseraft run -c .fuseraft/config/orchestration.yaml "Your task here"

To invoke fuseraft from a script or trigger it from an external event (a webhook, a queue, a cron tick), add --json for a single machine-parseable result and a clean stdout/stderr split — see Scripting & Automation.

Option B — copy an example config

cp config/examples/orchestration.yaml .fuseraft/config/orchestration.yaml
fuseraft run -c .fuseraft/config/orchestration.yaml "Add a hello-world endpoint to this project"

---

If no task is given you are prompted interactively:

fuseraft run -c .fuseraft/config/orchestration.yaml

The orchestrator loads the config, prints a summary of the team, and streams agent responses as they arrive.

Understand the output

Each agent turn is prefixed with its name:

[Planner] Reading the task…
[Developer] Writing the implementation…
[Tester] Running tests…
[Reviewer] APPROVED

Token counts and estimated cost appear after each turn in --verbose mode, and in the transcript written by --output.

Resume an interrupted session

Sessions are checkpointed after every turn. If a run is interrupted (Ctrl+C, network error, etc.) resume with:

fuseraft run --resume

You are shown a list of incomplete sessions; select one and the run picks up exactly where it left off. See Sessions for more detail.

Validate your config

Before running an unfamiliar config:

fuseraft validate .fuseraft/config/orchestration.yaml

This checks field types, agent names, strategy references, and plugin names without making any API calls.

Keep up to date

If you installed a prebuilt binary, keep it current with:

fuseraft update          # download and install the latest release
fuseraft update --check  # check for a newer release without installing

On Linux and macOS the binary is replaced atomically in place. On Windows a separate fuseraft-update.exe process (bundled in the release archive) handles the swap after all fuseraft instances exit. See CLI Reference — fuseraft update for full details.

Next steps

• Read REPL for the full walkthrough of interactive chat sessions — tools, the safety model, the ! shell escape, skills, memory
• Edit .fuseraft/config/orchestration.yaml to change agent instructions, models, or plugins
• Read Writing Effective Tasks to learn how to write task descriptions that produce correct, verifiable results
• Read Configuration for the complete schema reference
• Read Plugins for every tool agents can call
• Read Examples for ready-to-use team configs