Quickstart

This page gets you from install to a useful first RunWield session.

For terminal setup, keybindings, and model-provider background that are inherited from Pi, see the Pi Quickstart.

Install

On macOS or Linux, the shell installer is available:

curl -fsSL https://raw.githubusercontent.com/gandazgul/runwield/main/install.sh | bash

The installer installs wld plus required Mnemoteca/Cymbal/agent-browser helpers and optional Snip to ~/.local/bin by default. If your shell cannot find wld, add the install directory to your PATH.

Homebrew packages for macOS are prepared but not public until the owner publishes gandazgul/homebrew-tap. After that, use:

brew install gandazgul/tap/wld
brew install gandazgul/tap/mnemoteca

Windows x64 WinGet packaging is prepared but public catalog availability is pending owner submission and acceptance. After acceptance, use:

winget install --id Gandazgul.RunWield --exact

Git for Windows is required and is declared as a package dependency.

To choose a different install directory:

WLD_INSTALL_DIR="$HOME/bin" \
  bash -c "$(curl -fsSL https://raw.githubusercontent.com/gandazgul/runwield/main/install.sh)"

Run from source

Contributors can run the CLI directly with Deno:

deno run -A src/cli.ts help

To build the standalone binary:

deno task compile
./bin/wld help

Runtime helpers

The one-line installer is the complete standalone setup path. It installs missing required helpers (mnemoteca for project/global memory, cymbal for symbol-aware code search, and agent-browser for headed browser inspection) beside wld, preserving helper binaries you already manage elsewhere on PATH or in WLD_INSTALL_DIR. It also attempts optional snip for compact shell-output rewriting; RunWield still starts if Snip is missing.

The prepared Homebrew package uses Homebrew dependencies instead of the shell helper installer: gandazgul/tap/mnemoteca, 1broseidon/tap/cymbal, ketch, agent-browser, and git. agent-browser install and Mnemoteca model setup still run on first use, not during formula installation. A Homebrew-owned wld update prints brew upgrade gandazgul/tap/wld instead of replacing package files.

The prepared Windows package bundles Mnemoteca, Cymbal, Ketch, and agent-browser beside wld.exe. It does not require a user-installed Deno, Go, Rust, npm helper install, or WSL. A WinGet-owned wld update prints winget upgrade --id Gandazgul.RunWield --exact. Snip remains optional. Windows arm64 and image clipboard parity are not part of this package.

Mnemoteca’s model payload is not downloaded by the installer. It is fetched lazily by Mnemoteca on first semantic memory use.

If you already have mnemoteca and need data from a pre-rename install, run the official Mnemoteca installer before installing RunWield v0.10.0. The RunWield installer preserves an existing mnemoteca executable and does not start the upstream migration flow.

Authenticate

Configure login in a project directory:

cd /path/to/project
wld login

Choose a subscription provider or API-key provider, then choose a default model. The command exits after setup is complete. RunWield stores credentials in ~/.wld/auth.json.

You can also start the interactive TUI with wld and run /login. In a live Session, /login keeps you in the TUI and switches the Session to the selected model.

You can also use provider API keys through environment variables where supported by Pi’s provider system. See Pi Providers for provider-specific setup.

Initialize the project

Run:

wld init

This bootstraps durable RunWield context:

• explores the repository,
• writes docs/domain-language.md,
• stores core project memories,
• records that initialization has run for the project.

You can also run /init inside an interactive session.

First routed request

Send a request from the command line:

wld "summarize this repository and tell me how to run its checks"

router is the default command, so this is equivalent:

wld router "summarize this repository and tell me how to run its checks"

Router is the default Agent for fresh triage. It calls triage_report to assign a routing intent: INQUIRY, IDEATION, OPERATION, QUICK_FIX, FEATURE, or PROJECT. That tool outcome hands off to Guide for answers, Ideator for idea sharpening, Operator for direct non-code operations, Engineer for bounded no-plan quick fixes, Planner for FEATURE plans, or Architect for PROJECT Epics. PROJECT work becomes an Epic design plan first, then the interactive Slicer breaks it into child FEATURE plans after approval.

Open Workspace in your browser or on your phone

Run this in a separate terminal and leave it running:

wld workspace serve

Your browser opens Workspace and shows a pairing code. Follow the Workspace setup guide to pair your browser, link your repository, and continue a TUI Session. The guide also walks through phone access with Tailscale.

Common commands

wld "your request"                  # route through triage
wld router "your request"           # explicit router form
wld agent                           # list available agents
wld agent engineer "implement X"    # start with Engineer instead of Router
wld login                           # configure credentials and choose a default model
wld plans                           # list saved plans
wld load-plan <name-or-path>        # review, execute, or continue a plan
wld init                            # bootstrap project context
wld theme --list                    # list themes
wld help
wld help <command>
wld version

Next steps

• Workspace on your computer and phone - browser setup, pairing, and Tailscale access.
• Using RunWield - day-to-day workflow and commands.
• Plans and workflows - RunWield planning and validation behavior.
• Providers and models - RunWield-specific provider paths.
• Settings Reference - configure defaults and agent model overrides.