Install

Prerequisites

Requirement	Minimum version	Notes
Node.js	20 LTS	22 LTS recommended
pnpm	9.x	npm i -g pnpm
Git	2.40+	Required for worktree isolation
macOS or Linux	macOS 13+ / Ubuntu 22.04+	Windows support coming in a future release
Anthropic API key	—	Claude Sonnet 4.x is the default model

Install the CLI

npm

npm install -g @defiant/cli

pnpm

pnpm add -g @defiant/cli

Homebrew (macOS)

brew tap defiant-build/tap
brew install defiant

Verify the install:

defiant --version
# Defiant CLI 2.0.0

Configure credentials

Defiant stores credentials in ~/.defiant/. Run the interactive setup:

defiant init

The wizard prompts for:

• Anthropic API key — required. Used for all agent inference calls.
• GitHub token — required for repo access, PR creation, and status checks. Needs repo + workflow scopes.
• Supabase URL + anon key — required for the REST API and event log persistence.
• Asana PAT — optional. Enables the Scribe agent to create and update tasks.
• Sentry DSN — optional. Enables the Medic agent to monitor runtime errors.
• PostHog key — optional. Enables usage analytics.
• Stripe secret key — optional. Required only for Marketplace vertical billing flows.

Credentials are written to ~/.defiant/credentials.json with 600 permissions. They are never committed to git.

To update a single credential later:

defiant config set ANTHROPIC_API_KEY sk-ant-...
defiant config set GITHUB_TOKEN ghp_...

Start the Conductor

The Conductor is the local daemon that drives all sprint execution. It must be running before you create sprints.

defiant watch start

Expected output:

[Conductor] Starting...
[Conductor] IPC socket: ~/.defiant/ipc/conductor.sock
[Conductor] Event log: ~/.defiant/events.db
[Conductor] Token budget: 2,000,000 / day
[Conductor] Ready. Listening for sprints.

Check status at any time:

defiant watch status
# Conductor: running (PID 12345)
# Active sprints: 0
# Token usage today: 0 / 2,000,000 (green)
# IPC socket: ~/.defiant/ipc/conductor.sock

Stop the Conductor:

defiant watch stop

Verify the installation

1. Check the CLI — defiant --version returns the version string.
2. Check the Conductor — defiant watch status shows running.
3. Check credentials — defiant config check validates all configured keys against their APIs.
4. List projects — defiant projects list returns an empty list (or your existing projects).

defiant config check
# [OK] ANTHROPIC_API_KEY — valid
# [OK] GITHUB_TOKEN — valid (scopes: repo, workflow)
# [OK] SUPABASE_URL — reachable
# [OK] SUPABASE_ANON_KEY — valid
# [SKIP] ASANA_PAT — not configured
# [SKIP] SENTRY_DSN — not configured

Directory layout

After init, your ~/.defiant/ directory looks like:

~/.defiant/
  credentials.json     # API keys (chmod 600)
  config.json          # Preferences (model, token budgets, log level)
  ipc/
    conductor.sock     # Unix socket for JSON-RPC
  events.db            # SQLite event log (append-only)
  worktrees/           # Ephemeral git worktrees for each sprint
  logs/
    conductor.log      # Conductor stdout/stderr
    agents/            # Per-agent turn logs

Auto-start on login (optional)

macOS (launchd)

defiant watch install-service
# Installs a launchd plist at ~/Library/LaunchAgents/build.defiant.conductor.plist
# The Conductor starts automatically on login.

Linux (systemd user)

defiant watch install-service
# Installs a systemd user unit at ~/.config/systemd/user/defiant-conductor.service
# Enable with: systemctl --user enable --now defiant-conductor

Upgrading

# CLI
npm update -g @defiant/cli

# After upgrading, restart the Conductor
defiant watch stop
defiant watch start

Defiant follows semantic versioning. Minor versions are backward-compatible with the event log schema. Major versions ship a migration guide.

Uninstall

defiant watch stop
npm uninstall -g @defiant/cli
rm -rf ~/.defiant   # removes all local state — irreversible

Next steps

• Follow the Quickstart to create your first sprint.
• Read the Architecture Overview to understand what the Conductor is doing.