Skip to content

Getting Started

This page walks through the current beta setup model. Merlin ships as an app-first distribution: the macOS app owns onboarding, secure provider keys, project selection, update checks, and CLI install state.

Merlin is in beta, Apple Silicon macOS first, with Linux to follow and Windows on the roadmap. Builds are signed and notarized; one-step public install is part of the road to 1.0.

Prerequisites

RequirementWhy
Apple Silicon MacFirst beta target
One LLM API keyOPENROUTER_API_KEY (easiest, one key gets 5 providers), ANTHROPIC_API_KEY, OPENAI_API_KEY, or others
A project folderMerlin can run from any folder after the app-managed CLI is installed

Internal development builds additionally require Rust 1.75+ stable, git, and fledge on PATH.

Install

Beta app path

  1. Install the signed Apple Silicon DMG.
  2. Drag Merlin.app into Applications.
  3. Open the app and complete onboarding.
  4. Add a provider key in Settings → Providers & Keys.
  5. Install the CLI in Settings → CLI.
  6. Open a terminal in any project and run merlin doctor.

The app installs ~/.local/bin/merlin as a symlink to its bundled CLI. If ~/.local/bin is missing from PATH, Merlin shows copyable shell guidance but does not edit shell rc files automatically.

Internal development path

Merlin is a CorvidLabs internal project. This source-checkout section is for contributors working on Merlin itself, not for approved alpha users installing the product. If you have source access and are changing Merlin, install the local checkout CLI:

git clone https://github.com/CorvidLabs/merlin
cd merlin
cargo install --path crates/merlin-cli --force
merlin init

This path is for development workstations only. It uses the local checkout, builds the checkout plugins, and is not the supported end-user install path. Approved alpha users should install the app, then use Settings → CLI to install the bundled command.

What merlin init does in a checkout

  • Builds all plugins under plugins/ in release mode.
  • Copies each plugin's plugin.toml to the fledge data dir (~/Library/Application Support/fledge/plugins/<name>/ on macOS, ~/.local/share/fledge/plugins/<name>/ on Linux).
  • Symlinks plugin binaries into the fledge bin shim directory.
  • Appends new plugins to plugins.toml registry.
  • Best-effort starts localnet and generates AlgoChat keys (skip-tolerant).

Configure a Provider

Set an API key. Pick one of three methods:

# Option 1: OS keychain (recommended, works globally, no .env needed)
merlin keys set OPENROUTER_API_KEY

# Option 2: Environment variable
export OPENROUTER_API_KEY="sk-or-..."

# Option 3: .env file (project-local)
cp .env.example .env
# Edit .env and paste your key

Confirm Merlin sees it:

merlin keys           # shows all keys and their source
merlin doctor         # runtime, CLI install, plugins, and key sources
merlin health         # tests configured providers

See Configuration for the full [merlin] config block, including how to register multiple providers and switch between them at runtime.

Run Your First Task

One-shot mode. Pass the task on the command line from any project folder:

merlin "list rust files under crates/"

You'll see the agent transition through Planning → Executing → Verifying → Reporting → Idle, with streaming text deltas, tool calls, and a final summary listing any files changed.

Interactive REPL

Drop into the REPL by running with no task:

merlin

Inside the REPL:

> /help
  /model [name]     -- List or switch provider/model
  /memory <query>   -- Search memory
  /contacts         -- List AlgoChat contacts
  /status           -- Show agent status
  /verify           -- Run verify lane
  /quit             -- Exit

> add docstrings to crates/merlin-core/src/agent.rs
Planning...
  ...

See Slash Commands for the full reference.

Cancellation

Press Ctrl+C mid-task. The in-flight LLM HTTP request is dropped, any files already modified are listed, and the agent returns to Idle.

What's Next