Commands Reference

Every Fellowship CLI command with usage, flags, and examples.

`fellowship init`

Interactive wizard that sets up Fellowship in a new project. Analyzes your description, generates architecture, creates an AI agent team, and scaffolds the project.

terminal

fellowship init

Creates the following in your project:

.fellowship/config.yaml — Project config (provider, model, settings)
.fellowship/team.yaml — Agent definitions (roles, skills, profiles)
.fellowship/profiles/ — Agent profiles with coding guidelines
.fellowship/architecture.md — Project architecture reference
.fellowship/fellowship.db — SQLite database (runs, decisions, learnings)
.gitignore — Auto-generated for your stack

`fellowship adopt`

Adds Fellowship to an existing project by analyzing the codebase. Detects stack, framework, patterns, and generates a team tailored to your project.

terminal

cd existing-project
fellowship adopt

`fellowship run`

The core command. Generates a spec, assigns an agent, executes the task, reviews the code, and extracts learnings.

terminal

# Basic run
fellowship run "add pagination to GET /users"

# With human review (accept/reject/feedback)
fellowship run "refactor auth middleware" --review

# Run in background — free your terminal
fellowship run "add search endpoint" --bg

# Background + human review
fellowship run "add auth" --bg --review

# Preview what would happen (no code changes)
fellowship run "add search endpoint" --dry-run

# Skip AI review
fellowship run "fix typo in README" --no-review

# Use a pre-written spec
fellowship run --spec path/to/spec.md

Options

Flag	Description
`--bg`	Run in background — free your terminal, get notified when done
`--review`	Pause for human review after implementation
`--dry-run`	Generate spec and show preview, no code changes
`--no-review`	Skip the Sentinel AI review cycle
`--no-sanitize`	Disable prompt injection sanitization
`--spec <path>`	Use an existing spec instead of generating one
`--scribe`	Force documentation generation after run
`--no-scribe`	Skip documentation generation
`--agent <id>`	Force a specific agent, bypassing the smart selector

`fellowship run --bg`

Run in background — your terminal stays free while the agent works.

terminal

fellowship run "add user authentication" --bg

⚔️  Fellowship — running in background
   Task:    add user authentication
   PID:     45231
   Log:     .fellowship/runs/run-1.log

   fellowship log              ← view agent output
   fellowship log --follow     ← stream in real time
   fellowship status           ← check progress

You'll hear a sound when it's done 🔊

When the run completes: sound + desktop notification + terminal flash. Use fellowship log to check output or fellowship review to accept/reject changes.

`fellowship log`

View the output log of a background run.

terminal

fellowship log                # latest run
fellowship log --follow       # stream in real time (tail -f)
fellowship log --run 3        # specific run number

`fellowship review`

Review changes from a background run. Accept or reject with full diff display.

terminal

fellowship review
# Shows diff, spec, stats
# [a]ccept  [r]eject  [d]iff  [s]pec

`fellowship hire`

Add a new agent to your team through an AI conversation.

terminal

fellowship hire

`fellowship fix`

Diagnose a bug, generate a targeted fix spec, and run the fix agent. Use this instead of fellowship run when you need to resolve a specific defect.

terminal

fellowship fix "payment webhook returns 500 when amount is zero"

# With human review
fellowship fix "login fails after password reset" --review

`fellowship spec`

Generate a spec without running it. Useful for reviewing specs before execution.

terminal

fellowship spec "add WebSocket support for real-time updates"

`fellowship search`

Search learnings and gotchas using FTS5 full-text search.

terminal

fellowship search "authentication"

`fellowship status`

Dashboard showing your team, recent runs, costs, and project stats.

terminal

fellowship status

⚔️  Fellowship v0.4.2 — my-api
   Provider: anthropic (claude-sonnet-4-6)

👥 Team (4 agents)
   ⚙️  Carlos — Backend development
   🗄️  Atlas — Database design and management
   🎯  Merlín — Project coordination
   🛡️  Sentinel — Code reviewer

📊 Recent Runs
   #   Task                          Agent    Status     Duration  Cost
   3   add rate limiting             Carlos   ✅ done    2m 15s   $0.31
   2   add CORS config               Carlos   ✅ done    1m 54s   $0.24
   1   scaffold project              Carlos   ✅ done    2m 50s   $0.67

📈 Summary
   Runs: 3 total (3 completed, 0 failed)
   Tokens: 892,411 (~$0.82)
   Learnings: 5 bullets (distilled)
   Decisions: 8 in DB

`fellowship doctor`

Check your setup for issues. Verifies Node, Git, agent CLI, API key, config, team, Sentinel, learnings, and more. Zero LLM calls.

terminal

fellowship doctor

⚔️  Fellowship Doctor

  ✅ Node.js v25.6.1  (>= 18)
  ✅ Git 2.47.0
  ✅ Agent CLI  (claude)
  ✅ .fellowship/ directory
  ✅ config.yaml  (anthropic / claude-sonnet-4-6)
  ✅ team.yaml  (4 agents)
  ✅ API key  (configured for anthropic)
  ✅ Sentinel reviewer  (profile present)
  ✅ fellowship.db
  ✅ .gitignore  (covers fellowship.db)
  ⚠️  Learnings  (none yet — run some tasks first)
  ⚠️  Gotchas  (none yet)
  ✅ architecture.md

  All checks passed (11 ✅, 2 ⚠️, 0 ❌)

`fellowship memory`

Interactive TUI with four views: Dashboard, Runs, Memory, and Diff. Now supports add, edit, and delete of Memory Graph nodes directly from the terminal UI.

terminal

fellowship memory                      # Opens on dashboard
fellowship mem                         # Alias
fellowship memory --view runs          # Jump to runs table
fellowship memory --view memory --section gotchas
fellowship memory --view diff          # Side-by-side diff
fellowship memory --view diff --diff main
fellowship memory --search "database"  # Pre-filter entries

Views

Dashboard — stats overview: total runs, tokens, cost, team, last run
Runs — full run history table with agent, status, review, tokens, cost, duration
Memory — browse learnings, gotchas, decisions, reviews (4 sub-tabs)
Diff — side-by-side diff view with add/remove coloring

Keyboard Navigation

Key	Action
`1-4`	Jump to view
`Tab`	Cycle views
`↑↓` / `jk`	Navigate
`h` / `l`	Switch memory tabs
`Enter`	Expand item
`/`	Search
`a`	Add new node
`e`	Edit selected node
`D`	Delete selected node
`u` / `d`	Page scroll (diff)
`q`	Quit

`fellowship learn`

Interactive wizard to add a typed node to the Memory Graph. Supports five node types: learning, gotcha, decision, code-pattern, architecture. No file required — runs fully in the terminal.

terminal

# Interactive wizard — prompts for content and type
fellowship learn

# Inline with explicit type
fellowship learn "Always use parameterized queries" --type gotcha

# From a source file
fellowship learn --type decision --source architecture.md

Node Types

Type	Use for
`learning`	General lessons derived from experience
`gotcha`	Technical pitfalls with a specific fix
`decision`	Architectural choices with rationale
`code-pattern`	Reusable implementation patterns
`architecture`	System-level structural knowledge

`fellowship export`

Exports the Memory Graph (nodes + edges) to a portable .jsonl.gz file. Commit this file to version-control your project knowledge so any team member can restore it with fellowship import.

terminal

# Export to default location
fellowship export                              # → .fellowship/graph.jsonl.gz

# Custom output path
fellowship export --output ./my-graph.jsonl.gz

# Uncompressed .jsonl for debugging
fellowship export --pretty

`fellowship import`

Restores the Memory Graph from a .jsonl.gz file. Run after cloning a repo to start with accumulated knowledge from day 0. By default replaces the existing graph; use --merge to combine.

terminal

# Import from default location
fellowship import                              # from .fellowship/graph.jsonl.gz

# Custom input path
fellowship import --input ./my-graph.jsonl.gz

# Merge with existing graph instead of replacing
fellowship import --merge

# Preview without modifying DB
fellowship import --dry-run

`fellowship scribe`

Generate or update project documentation (README, API docs, changelog).

terminal

fellowship scribe --readme
fellowship scribe --api
fellowship scribe --all

`fellowship connect`

Configure your AI provider credentials (stored securely in macOS Keychain / system credential store).

terminal

fellowship connect

`fellowship sanitize`

Scan .fellowship/ files for prompt injection attempts.

terminal

fellowship sanitize

Previous ← Getting Started Next Concepts →