Introduction

One CLI, six stages, your whole dev lifecycle.

fledge is a Rust CLI that replaces the pile of tools you’re currently juggling. Instead of cookiecutter + make + gh + custom scripts, you get one binary that handles everything from project creation to changelog generation.

Why I built this

I kept setting up the same boilerplate across projects. CI workflows, linters, task runners, the works. Every new repo meant copy-pasting from the last one and fixing whatever broke. fledge started as a scaffolding tool and grew into a full dev lifecycle CLI because once you have a tool that understands your project structure, it makes sense to keep going.

What it does

Start a project, build your tasks and config, develop features on branches, review quality before merging, ship releases. Extend runs alongside everything with plugins and completions.

It auto-detects your project type (Rust, Node, Go, Python, Ruby, Java, Swift) and generates sensible defaults. You don’t need fledge templates init to get started – just cd into any existing project and run fledge run test. It works with zero config. When you want more control, fledge run --init generates a fledge.toml tailored to your stack. Compose tasks into lanes, and you’ve got a consistent workflow across all your projects – new and existing.

Getting Started

Install fledge and get started in about two minutes – whether you’re creating a new project or adding fledge to an existing one.

Installation

From crates.io

Fastest way to get going:

cargo install fledge

Homebrew

brew install CorvidLabs/tap/fledge

Install Script

Detects your OS and arch, grabs the right binary:

curl -fsSL https://raw.githubusercontent.com/CorvidLabs/fledge/main/install.sh | sh

Nix

nix run github:CorvidLabs/fledge

Or add it to your flake inputs.

From Source

git clone https://github.com/CorvidLabs/fledge.git
cd fledge && cargo install --path .

Shell Completions

Tab completion makes everything better:

# Auto-install for your shell
fledge completions --install

# Or do it manually
fledge completions bash >> ~/.bashrc
fledge completions zsh > ~/.zfunc/_fledge
fledge completions fish > ~/.config/fish/completions/fledge.fish

Verify It Works

fledge --version
fledge templates list

You should see the version and a list of built-in templates. If you do, you’re good.

Quick Start

Use Fledge in an Existing Project

Already have a project? Just cd in and go:

cd my-project
fledge run test     # auto-detects your stack, runs the right command
fledge run build
fledge run lint

No config file needed. When you want to customize, generate one:

fledge run --init   # creates fledge.toml with detected defaults

See Existing Projects for the full guide.

Create a New Project

Pick a template and go:

fledge templates init my-tool --template rust-cli

That gives you a full Rust CLI project with clap, CI, and release automation in a my-tool directory.

Browse Templates

Not sure what you want? Just run init without a template and fledge will walk you through it:

fledge templates init my-project

Use a Remote Template

Any GitHub repo works as a template source:

fledge templates init my-app --template CorvidLabs/fledge-templates/python-api

Dry Run First

Preview what you’d get before writing anything:

fledge templates init my-tool --template rust-cli --dry-run

Set Up Tasks

Once your project exists, generate a fledge.toml with auto-detected tasks:

cd my-tool
fledge run --init    # generates fledge.toml based on what it finds
fledge run build
fledge run test

Workflow Pipelines

Lanes chain tasks together. Think of fledge lanes run ci as your local CI:

fledge lanes init            # generate default lanes for your project type
fledge lanes list            # see what's available
fledge lanes run ci          # run the full pipeline
fledge lanes run ci --dry-run  # just show the plan

Lanes support parallel groups and inline commands. More on that in Lanes & Pipelines.

Project Health

fledge doctor            # anything broken in your env?
fledge metrics           # LOC by language
fledge metrics --churn   # most-changed files
fledge deps              # list deps
fledge deps --outdated   # find stale ones
fledge deps --audit      # security check

Plugins

Community extensions, git-style:

fledge plugins search deploy
fledge plugins install someone/fledge-deploy           # latest
fledge plugins install someone/fledge-deploy@v1.0.0    # pinned version
fledge plugins list

Work Branches + PRs

fledge work start add-logging                # creates leif/feat/add-logging (default: {author}/{type}/{name})
fledge work start fix-typo --branch-type fix        # creates leif/fix/fix-typo
fledge work start bump-deps --branch-type chore     # creates leif/chore/bump-deps
# ... hack on your branch ...
fledge work pr                               # opens a PR
fledge work status                           # where are we?

CI + Code Review

fledge checks                    # CI status
fledge review                    # AI code review
fledge ask "how does X work?"    # ask about the codebase

Changelog

fledge changelog                 # from git tags + conventional commits
fledge changelog --unreleased    # what's new since last tag

All Templates

fledge templates list

Shows everything available: built-in, configured repos, and local paths.

Built-in Templates

More templates (Angular, MCP server, Deno, Swift, etc.) available at CorvidLabs/fledge-templates.

Using Fledge with Existing Projects

Fledge isn’t just for new projects. Most of its features work in any git repo, no setup required.

Zero-Config: Just Run It

cd into any project and fledge auto-detects your stack:

cd my-existing-project
fledge run test    # detects Rust/Node/Go/Python/Ruby/Java and runs the right command
fledge run build
fledge run lint

No fledge.toml needed. Fledge looks for marker files (Cargo.toml, package.json, go.mod, etc.) and provides sensible default tasks.

What Gets Detected

For Node.js projects, fledge also detects your package manager (npm, bun, yarn, pnpm) from lockfiles and uses the right one.

Lock It In: Generate a Config

When you want to customize tasks, generate a fledge.toml:

fledge run --init

This creates a config file pre-filled with the detected tasks. Edit it to add custom commands, change defaults, or define lanes:

[tasks]
build = "cargo build"
test = "cargo test"
lint = "cargo clippy -- -D warnings"
fmt = "cargo fmt --check"

[lanes.ci]
description = "Full CI pipeline"
steps = ["fmt", "lint", "test", "build"]

Once fledge.toml exists, it takes full precedence over auto-detection.

Everything Else Works Too

These commands work in any git repo regardless of how the project was created:

Turn Your Project into a Template

Have a project structure you want to reuse? Turn it into a fledge template:

fledge templates create my-stack

This scaffolds a template directory by examining your project. Add Tera variables for the parts that should change (project name, author, etc.), then use it for future projects:

fledge templates init new-project --template ./my-stack

Or publish it for others:

fledge templates publish ./my-stack

Typical Workflow

1. Start using fledge today: cd your-project && fledge run test
2. Optionally lock in config: fledge run --init to generate fledge.toml
3. Set up lanes: fledge lanes init for CI pipelines
4. Use the full toolkit: fledge review, fledge work start feature-x, fledge checks
5. Create templates: Once you have a setup you like, fledge templates create to reuse it

The Six Pillars

fledge organizes your dev workflow into six stages. Each one maps to a set of commands, and they flow naturally from project creation to release.

Start --> Build --> Develop --> Review --> Ship
                                              \
                       Extend (runs alongside all stages)

Start: Scaffold and discover

Get a project off the ground. Pick a template (built-in, remote, or your own), scaffold it, and you’re writing code in under a minute.

Commands: templates init, templates list, templates search, templates create, templates publish, templates validate, templates update

Build: Configure and run

Define your tasks, wire them into pipelines, set your defaults, and make sure your environment is ready. This is where fledge.toml lives.

Commands: run, lanes, config, doctor

Develop: Branch and spec

Work on features with proper branch isolation and keep your specs in sync with the code.

Commands: work, spec

Review: Quality and insight

Check your code before it ships. AI review, codebase Q&A, code metrics, and dependency health. All from the terminal.

Commands: review, ask, metrics, deps

Ship: Track and release

Manage issues, review PRs, check CI status, generate changelogs, and cut releases. Everything you need to get code out the door.

Commands: issues, prs, checks, changelog, release

Extend: Grow the tool

Install community plugins, write your own, and set up shell completions.

Commands: plugins, completions

Templates

Templates are how fledge scaffolds projects. They come from three places: built-in, remote repos, and local directories.

Built-in Templates

These ship with the binary. Always there, no setup needed:

For Angular, MCP server, Deno, Swift, monorepo, and more, check the official template repo:

fledge templates init my-app --template rust-cli
fledge templates init my-service --template CorvidLabs/fledge-templates/go-cli

Remote Templates

Any GitHub repo can be a template. Just use owner/repo:

fledge templates init my-app --template CorvidLabs/fledge-templates/deno-cli

# Pin to a specific version
fledge templates init my-app --template CorvidLabs/fledge-templates/mcp-server@v1.0

Templates get cached locally after the first pull. Use --refresh to force a re-download:

fledge templates init my-app --template CorvidLabs/fledge-templates/deno-cli --refresh

Official Template Collection

CorvidLabs/fledge-templates has a growing set of community templates:

Add it to your config so these show up in fledge templates list:

fledge config add templates.repos "CorvidLabs/fledge-templates"

Or use the preset which sets everything up:

fledge config init --preset corvidlabs

Local Templates

Point fledge at a directory on disk:

fledge config add templates.paths "~/my-templates"

Or just pass a path directly:

fledge templates init my-app --template ./path/to/template

Finding Templates

Search GitHub

Templates on GitHub use the fledge-template topic:

fledge templates search                  # browse everything
fledge templates search "react"          # filter by keyword
fledge templates search --limit 50
fledge templates search --author CorvidLabs

List What You Have

fledge templates list    # built-in + configured repos + local paths

Updating Projects

When a template gets updated, you can re-apply it to an existing project:

fledge templates update              # re-apply source template
fledge templates update --dry-run    # preview what would change
fledge templates update --refresh    # force re-clone remote template

fledge tracks file hashes in .fledge/meta.toml to detect changes:

• New files from the template are always added.
• User-modified files are skipped with a warning (your changes are preserved).
• Unmodified files are updated to the latest template version.
• Removed files in the new template version trigger a warning.

Projects created with older fledge versions using .fledge.toml are automatically migrated to .fledge/meta.toml on the first update.

Publishing Your Own

# Start with the skeleton
fledge templates create my-template

# Edit template files and template.toml

# Ship it
fledge templates publish --org MyOrg

Add the fledge-template topic to your GitHub repo so it shows up in search results.

Validate Before You Ship

fledge templates validate .
fledge templates validate . --strict    # warnings become errors
fledge templates validate ./templates   # validate a whole directory
fledge templates validate . --json      # machine-readable output

The validator checks for:

• Valid template.toml with required fields (name, description)
• Tera syntax errors in template files
• Undefined variables (not built-in and not in [prompts])
• Render globs that don’t match any files
• template.toml in the ignore list

You can also just test it:

fledge templates init test-output --template ./my-template --dry-run

For the full format reference, see the Template Authoring Guide.

Resolution Order

When you run fledge templates init --template <name>, fledge looks in this order:

1. Exact path - starts with . or /
2. Built-in templates - the 6 bundled ones
3. Configured repos - templates.repos in your config
4. Local paths - templates.paths in your config
5. GitHub shorthand - treats it as owner/repo and fetches it

Security

Hooks from remote templates (post_create commands) always ask for confirmation before running. This way random templates can’t execute whatever they want on your machine. Pass --yes if you trust the source and want to skip the prompt.

Template Authoring Guide

How to build your own fledge templates.

Overview

A template is a directory with a template.toml manifest and whatever files you want. Files get rendered through Tera (Jinja2-style) before being written to the output.

Directory Structure

my-template/
├── template.toml          # manifest (required)
├── src/
│   └── main.rs            # template files, Tera syntax works here
├── README.md
├── Cargo.toml
└── .github/
    └── workflows/
        └── ci.yml

template.toml Reference

This is where you define metadata, prompts, file rules, and hooks.

Basic Structure

[template]
name = "my-template"
description = "A short description"
min_fledge_version = "0.1.0"          # optional

[prompts]
description = { message = "Project description", default = "A new project" }
port = { message = "Default port", default = "3000" }

# Defaults can reference earlier variables:
repo_url = { message = "Repository URL", default = "https://github.com/{{ github_org }}/{{ project_name }}" }

[files]
render = ["**/*.rs", "**/*.toml", "**/*.md", "**/*.yml"]
copy = ["**/*.png", "**/*.ico"]
ignore = ["template.toml"]

[hooks]
post_create = ["cargo fmt", "npm install"]

[template] section

[prompts] section

Each key becomes a template variable that gets prompted to the user.

[prompts]
# With a default
description = { message = "Project description", default = "A new project" }

# No default, user has to answer
main_author = { message = "Primary author" }

# Default can reference other variables
repo_url = { message = "Repository URL", default = "https://github.com/{{ github_org }}/{{ project_name }}" }

[files] section

Controls which files get rendered, copied, or skipped. Rules apply in order, first match wins.

• render - process through Tera
• copy - copy as-is (for binary files, images, etc.)
• ignore - skip entirely

Anything not matching a rule gets rendered by default.

[files]
render = ["**/*.rs", "**/*.toml", "**/*.md", "**/*.yml"]
copy = ["**/*.png", "**/*.ico", "assets/**"]
ignore = ["template.toml", "node_modules/**"]

[hooks] section

Commands that run after scaffolding, inside the new project directory.

[hooks]
post_create = ["cargo fmt", "cargo test", "git add -A && git commit -m 'Initial commit'"]

Built-in templates run hooks automatically. Remote templates show the commands and ask for confirmation (unless you pass --yes).

Built-in Variables

These are always available. You don’t need to define them in [prompts]:

Tera Syntax

Templates use Tera syntax. Here’s the stuff you’ll actually use:

Variables

# {{ project_name }}

{{ description }}

Conditionals

{% if license == "MIT" %}
This project is MIT licensed.
{% endif %}

Loops

{% for dep in dependencies %}
- {{ dep }}
{% endfor %}

Filters

Project slug: {{ project_name | slugify }}
Uppercase: {{ author | upper }}

Putting it together

# {{ project_name }}

{{ description }}

## Author

Created by {{ author }} ({{ github_org }}) in {{ year }}.

{% if license == "MIT" %}
This project is MIT licensed.
{% endif %}

## Quick Start

```
cd {{ project_name_snake }}
cargo build
```

Quick Start with fledge templates create

The fastest way to start a new template:

fledge templates create my-template
fledge templates create my-template --hooks --prompts --yes

This scaffolds a ready-to-edit template directory with template.toml and example files. See the CLI reference for all options.

Building a Template from Scratch

1. Make the directory

mkdir python-api && cd python-api

2. Write template.toml

[template]
name = "python-api"
description = "Python FastAPI project with Docker"

[prompts]
description = { message = "Project description", default = "A FastAPI application" }
python_version = { message = "Python version", default = "3.12" }

[files]
render = ["**/*.py", "**/*.toml", "**/*.md", "**/*.yml", "Dockerfile"]
ignore = ["template.toml"]

[hooks]
post_create = ["python -m venv .venv"]

3. Add your files

# app/main.py
"""{{ description }}"""
from fastapi import FastAPI

app = FastAPI(title="{{ project_name_pascal }}")

@app.get("/")
def root():
    return {"name": "{{ project_name }}"}

# Dockerfile
FROM python:{{ python_version }}-slim
WORKDIR /app
COPY . .
RUN pip install -e .
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0"]

4. Test it

fledge templates init test-api --template ./python-api --dry-run
fledge templates init test-api --template ./python-api

Testing

Add your template directory to config:

# ~/.config/fledge/config.toml
[templates]
paths = ["~/dev/my-templates"]

Or point at it directly:

fledge templates init test-project --template ./my-template

The loop is: edit files → fledge templates init test-output --template my-template → check the output → delete test output → repeat.

Sharing

GitHub

Push your template to a GitHub repo. Anyone can use it with:

fledge templates init my-app --template user/my-template

Template Repos

Users can register your repo so it shows up in fledge templates list:

[templates]
repos = ["CorvidLabs/fledge-templates", "myorg/templates"]

Tips

• Name it clearly. python-api beats template-1.
• Write a README. Explain what the template does and what variables it uses.
• Default everything you can. Only prompt for things that actually vary.
• Test your hooks. Make sure post_create commands handle missing tools gracefully.
• Use min_fledge_version if you depend on newer features.

Lanes & Pipelines

Lanes let you chain tasks into named pipelines. Define them in fledge.toml, run them with fledge lanes run ci. All lane commands live under fledge lanes. They support parallel groups and configurable failure behavior.

Quick Start

Already have tasks in fledge.toml? Generate lanes automatically:

fledge lanes init

This looks at your project type and creates sensible defaults. Then just run one:

fledge lanes run ci

Defining Lanes

Lanes go in fledge.toml alongside your tasks:

[tasks]
fmt = "cargo fmt --check"
lint = "cargo clippy -- -D warnings"
test = "cargo test"
build = "cargo build"

[lanes.ci]
description = "Full CI pipeline"
steps = ["fmt", "lint", "test", "build"]

[lanes.check]
description = "Quick quality check"
steps = [
  { parallel = ["fmt", "lint"] },
  "test"
]

Lane Options

Step Types

You can mix these freely in a lane:

Task References

Just name a task from your [tasks] section. Dependencies (deps) get resolved automatically.

steps = ["lint", "test", "build"]

Inline Commands

One-off shell commands without cluttering your task list:

steps = [
  "test",
  { run = "cargo build --release" },
  { run = "echo 'Build complete'" },
]

Parallel Groups

Run multiple items at the same time. Everything in the group finishes before the next step starts. Items can be task references or inline commands.

steps = [
  { parallel = ["fmt", "lint"] },
  "test",
  "build"
]

Here fmt and lint run concurrently, then test, then build.

You can mix task references and inline commands in a parallel group:

steps = [
  { parallel = ["lint", { run = "echo checking..." }, "fmt"] },
  "test"
]

Failure Behavior

Default is fail_fast = true. Pipeline stops on the first failure.

[lanes.ci]
description = "Stop on first failure"
steps = ["lint", "test", "build"]

Set fail_fast = false when you want the full picture:

[lanes.audit]
description = "Run everything, report all failures"
fail_fast = false
steps = ["lint", "test", "security-check", "license-check"]

Step Timing

Every step prints its elapsed time, and the lane summary shows total time:

▶️ Lane: ci — Full CI pipeline
  ▶️ Running parallel: fmt, lint
  ✔ Step 1 done (245ms)
  ▶️ Running task: test
  ✔ Step 2 done (1.032s)
  ▶️ Running task: build
  ✔ Step 3 done (3.456s)
✅ Lane ci completed (3 steps in 4.733s)

This helps identify slow steps in your pipeline without any extra tooling.

Task Configuration

Short Form

[tasks]
lint = "cargo clippy"

Full Form

[tasks.build]
cmd = "cargo build --release"
description = "Build release binary"
deps = ["lint"]
env = { RUST_LOG = "info" }
dir = "crates/core"

Examples

CI Pipeline

[lanes.ci]
description = "Full CI pipeline"
steps = [
  { parallel = ["fmt", "lint"] },
  "test",
  "build"
]

Release

[lanes.release]
description = "Build and package a release"
steps = [
  "test",
  { run = "cargo build --release" },
  { run = "strip target/release/my-app" },
  { run = "tar -czf release.tar.gz -C target/release my-app" },
]

Full Audit

[lanes.audit]
description = "All quality checks"
fail_fast = false
steps = [
  "lint",
  "test",
  { run = "cargo audit" },
  { run = "cargo deny check" },
]

Auto-Generated Defaults

fledge lanes init detects your project type:

CLI

fledge lanes run ci                   # run a lane
fledge lanes run ci --dry-run         # preview the plan
fledge lanes list                     # list lanes
fledge lanes list --json
fledge lanes init                     # generate defaults
fledge lanes search                   # find community lanes
fledge lanes search rust              # search with keyword
fledge lanes import owner/repo        # import lanes from GitHub
fledge lanes import owner/repo@v1.0.0 # pin to a version
fledge lanes publish --org MyOrg      # publish lanes to GitHub
fledge lanes create my-lanes          # scaffold a new lane repo
fledge lanes validate                 # validate lane definitions
fledge lanes validate --strict        # treat warnings as errors
fledge lanes validate --json          # machine-readable output

Community Lane Registry

Share and discover lanes via GitHub. Repos with the fledge-lane topic are discoverable through fledge lanes search.

Official Examples

CorvidLabs/fledge-lanes is the official collection of language-specific lane examples. Each subdirectory contains a fully-documented fledge.toml.

Creating Lanes

Use fledge lanes create to scaffold a ready-to-publish lane repo:

fledge lanes create my-lanes

This creates a directory with a starter fledge.toml containing example tasks and lanes, a README, and a .gitignore. Edit the lanes, then validate and publish:

fledge lanes validate ./my-lanes     # check for errors
fledge lanes publish ./my-lanes      # push to GitHub (validates first)

Publishing Lanes

1. Create a repo with a fledge.toml containing your lanes and tasks (or use fledge lanes create)
2. Validate with fledge lanes validate (publish does this automatically)
3. Publish with fledge lanes publish — sets the fledge-lane topic automatically
4. Others can find it with fledge lanes search and import it

Importing Lanes

fledge lanes import CorvidLabs/fledge-lanes

This fetches the remote repo’s fledge.toml, extracts its lanes and any required tasks, and merges them into your local fledge.toml. Existing lanes with the same name are skipped (not overwritten).

You can pin to a specific branch or tag:

fledge lanes import CorvidLabs/fledge-lanes@v1.0.0

Related

• Configuration — global config, GitHub tokens
• Plugins — extend fledge with community commands, use plugins in lanes
• CLI Reference — full fledge lanes subcommand reference
• Example Lanes — official community lane collection

Tips

• Start with fledge lanes init and customize from there.
• Use parallel groups for independent checks. Linting and formatting don’t need to wait for each other.
• Keep fail_fast = true for CI. No point building if tests fail.
• Use fail_fast = false for audit lanes where you want the full report.
• Inline commands are great for one-off steps that don’t need to be named tasks.

Configuration

Quick Setup

Use a preset to get started fast:

# CorvidLabs preset - sets author, org, license, template repo
fledge config init --preset corvidlabs

# Default config
fledge config init

Config File

Lives at:

~/.config/fledge/config.toml

Sections

[defaults]

Default values for new projects:

[defaults]
author = "Your Name"
github_org = "YourOrg"
license = "MIT"

[templates]

Where to find templates:

[templates]
paths = ["~/my-templates", "~/work/templates"]
repos = ["CorvidLabs/fledge-templates", "myorg/templates"]

[github]

[github]
token = "ghp_..."

Token priority:

1. FLEDGE_GITHUB_TOKEN env var
2. GITHUB_TOKEN env var
3. Config file
4. gh auth token (GitHub CLI fallback)

Required token scopes:

A classic token with repo covers everything. For fine-grained tokens, grant Read/Write on Contents, Pull Requests, and Issues for each repo you work with.

Full Example

[defaults]
author = "Leif"
github_org = "CorvidLabs"
license = "MIT"

[templates]
paths = ["~/.fledge/templates", "~/projects/templates"]
repos = ["CorvidLabs/fledge-templates", "my-org/my-templates"]

[github]
token = "ghp_1234567890abcdefghijklmnopqrstuvwxyz"

Environment Variables

If neither env var nor config is set, fledge falls back to gh auth token (GitHub CLI) automatically.

Project Configuration (fledge.toml)

Per-project settings live in fledge.toml in your project root. This file defines tasks, lanes, and project metadata. It’s created by fledge run --init or fledge templates init.

For task and lane configuration, see:

• Lanes & Pipelines — defining lanes, step types, parallel groups, importing community lanes
• Plugins — extending fledge with community plugins

Priority Order

When creating a project, values come from (highest to lowest):

1. Command-line arguments
2. Config file
3. Git config (author only)
4. Built-in defaults

Doctor: Environment Diagnostics

fledge doctor checks your environment for issues that might cause problems. Run it when something isn’t working right, or proactively before starting a new project.

Usage

fledge doctor
fledge doctor --json

What It Checks

Doctor auto-detects your project type and checks relevant tools:

Toolchain (project-type-specific):

Dependencies — checks for lockfiles and build artifacts (e.g. Cargo.lock, node_modules/, go.sum).

Git — git installed, repository initialized, remote configured, working tree status.

AI — claude CLI installed (enables fledge review and fledge ask).

Output

Doctor reports each check as passing or failing:

• Pass (✅): tool is installed and working, with version info
• Fail (❌): tool is missing or errored, with a suggested fix command

When to Run It

• Before your first fledge templates init to make sure your environment is ready
• When fledge run can’t find the right command for your project type
• When GitHub commands (issues, prs, checks, work pr) fail with auth errors
• After upgrading your toolchain or switching machines

JSON Output

fledge doctor --json

Returns a structured report for scripting or CI checks. Each entry includes the check name, status, version (if applicable), and any diagnostic message.

Develop: Branch and Spec

Work on features with proper branch isolation and keep your specs in sync with the code.

Work branches with fledge work

Instead of manually creating branches and PRs, fledge work handles the git ceremony for you.

# Start a work branch (defaults to feat/ type)
fledge work start add-auth

# Start a bug fix branch
fledge work start login-crash --branch-type fix

# Link to a GitHub issue
fledge work start login-crash --branch-type fix --issue 42

# Check where you are
fledge work status

# Open a PR when ready
fledge work pr --title "Add auth middleware"

This creates a branch using your configured format (default: {author}/{type}/{name}), and fledge work pr opens a pull request against your base branch with sensible defaults.

Options for work start:

• -t, --branch-type <TYPE> - Branch type: feat, feature, fix, bug, chore, task, docs, hotfix, refactor [default: feat]
• -i, --issue <NUMBER> - Link to GitHub issue (prefixes branch name with issue number)
• --prefix <PREFIX> - Override branch prefix entirely (e.g. user/leif)
• --base <branch> - Base branch (defaults to main)

Options for work pr:

• -t, --title <title> - PR title
• -b, --body <body> - PR description
• --draft - Open as draft
• --base <branch> - Target branch

Spec-sync with fledge spec

Specs are markdown files in specs/ that define how a module should work. fledge spec check validates that the code matches the spec.

# Set up spec-sync
fledge spec init

# Create a new spec
fledge spec new auth

# Check specs against code
fledge spec check
fledge spec check --strict   # warnings become errors

Spec format

Each spec is a markdown file with a YAML frontmatter block:

---
module: auth
version: 1
status: active
---

# Auth Module

Description of what this module does.

## Public API

List the public functions/types and what they do.

## Invariants

Any guarantees the code must uphold.

fledge reads the frontmatter to track the module name, version, and status. The body is free-form markdown.

Validation rules

fledge spec check verifies:

1. Every spec in specs/ has a corresponding source file (no orphaned specs)
2. Every tracked module has a spec (no undocumented modules)
3. Spec frontmatter is valid YAML with required fields (module, version, status)
4. Version field is present (integer)

With --strict, warnings (missing optional fields, minor drift) become errors.

Workflow

Write the spec first, then write the code to match. Before committing, run:

fledge spec check

Add it to your CI lane:

[lanes.ci]
steps = ["fmt", "lint", "test", "spec-check"]

[tasks.spec-check]
cmd = "fledge spec check"

The .specsync/hashes.json file tracks content hashes. Commit it alongside spec changes so CI can detect drift.

Review: Quality and Insight

Check your code before it ships. AI-powered review, codebase Q&A, code metrics, and dependency auditing.

AI code review with fledge review

Get feedback on your changes before opening a PR. Diffs your branch against the base and runs it through Claude.

fledge review
fledge review --base main
fledge review --file src/auth.rs    # review a single file
fledge review --json                # machine-readable output

Ask your codebase with fledge ask

Got a question about how something works? Ask it.

fledge ask "how does the template rendering work?"
fledge ask "what tests cover the config module?"
fledge ask "what does the release command do?" --json

Code metrics with fledge metrics

Lines of code by language, file churn from git history, and test coverage ratio.

fledge metrics
fledge metrics --churn           # most-changed files
fledge metrics --tests           # test file ratio
fledge metrics --churn --tests --json

Dependency health with fledge deps

Find outdated packages, run security audits, and scan licenses. Works across Rust, Node, Go, Python, and Ruby.

fledge deps
fledge deps --outdated
fledge deps --audit
fledge deps --licenses
fledge deps --outdated --audit --licenses --json

Ship: Track and Release

Manage issues, review PRs, check CI status, generate changelogs, and cut releases. Everything you need to get code out the door without leaving the terminal.

GitHub issues with fledge issues

List and view issues for the current repo.

fledge issues
fledge issues --state closed
fledge issues --label bug
fledge issues view 42
fledge issues --json

Pull requests with fledge prs

List and view PRs.

fledge prs
fledge prs --state all
fledge prs view 85
fledge prs --json

CI/CD status with fledge checks

See what’s passing and what’s failing on any branch.

fledge checks
fledge checks --branch feat/add-auth
fledge checks --json

Changelogs with fledge changelog

Generate a changelog from git tags and conventional commits.

fledge changelog
fledge changelog --unreleased     # changes since last tag
fledge changelog --tag v0.7.0     # specific release
fledge changelog --limit 5        # last 5 releases
fledge changelog --json

Releases with fledge release

Cut a release — bump the version, generate changelog, create a git tag, and optionally push.

fledge release patch                          # bump patch version
fledge release minor --push                   # bump minor + push to remote
fledge release major --pre-lane ci            # run CI lane first, then bump major
fledge release 2.0.0 --dry-run               # preview a specific version bump
fledge release patch --no-tag --no-changelog  # just bump version, skip extras
fledge release minor --allow-dirty            # release even with uncommitted changes

Options:

• --dry-run - Preview without making changes
• --no-tag - Skip git tag
• --no-changelog - Skip changelog generation
• --push - Push commit and tag to remote
• --pre-lane <name> - Run a lane before releasing (e.g. ci)
• --allow-dirty - Allow uncommitted changes

Plugins

Plugins extend fledge with community-built commands. They’re external executables distributed as GitHub repos, following the git-style subcommand pattern. fledge-<name> becomes fledge <name>.

Installing

All plugin commands live under fledge plugins.

# From GitHub
fledge plugins install someone/fledge-deploy

# Pin to a specific version (tag, branch, or commit)
fledge plugins install someone/fledge-deploy@v1.2.0

# Full URL works too
fledge plugins install https://github.com/someone/fledge-deploy.git

# Full URL with version pin
fledge plugins install https://github.com/someone/fledge-deploy.git@v1.2.0

# Reinstall (or upgrade a pinned plugin)
fledge plugins install someone/fledge-deploy@v2.0.0 --force

What happens when you install:

1. Repo gets cloned to ~/.config/fledge/plugins/<name>/
2. If @ref was specified, that tag/branch/commit is checked out
3. fledge reads plugin.toml
4. Build hook runs (or auto-detects Rust/Swift/Go/Node)
5. Command binaries get symlinked to ~/.config/fledge/plugins/bin/
6. Plugin is registered in ~/.config/fledge/plugins.toml (with pinned_ref if pinned)

Using Plugins

# Via fledge
fledge plugins run deploy --target production

# Or directly if the binary is on PATH
fledge deploy --target production

Managing

fledge plugins list              # what's installed
fledge plugins search deploy     # find plugins on GitHub
fledge plugins update            # update all unpinned plugins
fledge plugins update fledge-deploy  # update a specific plugin
fledge plugins remove fledge-deploy
fledge plugins list --json       # for scripting

Version Pinning

Use @ref to pin a plugin to a specific version:

fledge plugins install someone/fledge-deploy@v1.2.0

Pinned plugins behave differently on update:

• Unpinned plugins get git pull and rebuild automatically
• Pinned plugins check for newer tags and suggest an upgrade command, but don’t change automatically

To upgrade a pinned plugin:

fledge plugins install someone/fledge-deploy@v2.0.0 --force

Discovery

Plugins use the fledge-plugin topic on GitHub. To make yours findable:

1. Add fledge-plugin as a topic on your repo
2. Include a plugin.toml manifest

fledge plugins search            # browse all plugins
fledge plugins search deploy     # search by keyword

Building a Plugin

1. Create the repo

The fastest way to start a plugin:

fledge plugins create fledge-deploy
cd fledge-deploy

This scaffolds plugin.toml, a starter executable in bin/, a README, and a .gitignore. Or create one manually:

mkdir fledge-deploy && cd fledge-deploy

2. Write plugin.toml

[plugin]
name = "fledge-deploy"
version = "0.1.0"
description = "Deploy to cloud providers"
author = "Your Name"

[capabilities]
exec = true
store = true

[[commands]]
name = "deploy"
description = "Deploy the project"
binary = "fledge-deploy"

[[commands]]
name = "rollback"
description = "Rollback to previous deployment"
binary = "fledge-rollback"

[hooks]
build = "cargo build --release"
post_install = "echo 'fledge-deploy installed'"
post_work_start = "scripts/setup-env.sh"

3. Add the executables

Each [[commands]] entry points to an executable in the repo. Can be compiled binaries, shell scripts, whatever:

#!/usr/bin/env bash
# fledge-deploy
echo "Deploying $(basename $(pwd))..."

Make them executable:

chmod +x fledge-deploy fledge-rollback

4. Validate

Check your plugin before publishing:

fledge plugins validate

This checks: plugin.toml is valid, name/version are set, binaries exist (or a build hook will create them), and commands are well-formed. Use --strict to fail on warnings, --json for machine-readable output.

5. Publish

Publish to GitHub (validates automatically before pushing):

fledge plugins publish

Or push manually and add the fledge-plugin topic. Users install with:

fledge plugins install yourname/fledge-deploy

plugin.toml Reference

[plugin]

[[commands]]

Each entry registers a subcommand.

[capabilities]

Capabilities declare what protocol features the plugin uses. All default to false — plugins must opt in.

[capabilities]
exec = true
store = true
metadata = false

During installation, fledge displays the requested capabilities and the user must approve them. Granted capabilities are recorded in plugins.toml and enforced at runtime:

• Blocked exec → returns exit code 126
• Blocked store → silently dropped
• Blocked metadata → returns empty object

Plugins without a [capabilities] section work fine but cannot use exec, store, or metadata protocol features.

[hooks]

Hooks fire in response to fledge lifecycle events. All fields are optional — plugins only participate in events they declare.

Values can be a path to a script (relative to plugin root) or an inline shell command.

Using Plugins in Lanes

Plugin commands can be called from lane steps as inline commands:

[lanes.deploy]
description = "Test, build, and deploy"
steps = [
  "test",
  { run = "cargo build --release" },
  { run = "fledge deploy --target production" },
]

You can also run plugin commands in parallel with other tasks:

[lanes.ci]
steps = [
  { parallel = ["lint", "test"] },
  "build",
  { parallel = [{ run = "fledge deploy --target staging" }, { run = "fledge notify --channel ci" }] },
]

See Lanes & Pipelines for full step type documentation.

Plugin Protocol (fledge-v1)

Plugins that declare capabilities communicate with fledge via a JSON-over-stdin/stdout protocol. When a plugin starts, fledge sends an init message with the plugin’s granted capabilities, then the plugin sends requests and fledge responds.

Message Types

See the plugin protocol spec for full details.

Authentication

Plugin install, update, and search operations use your GitHub token when available. This enables installing plugins from private repositories.

The token is resolved in order:

1. FLEDGE_GITHUB_TOKEN environment variable
2. GITHUB_TOKEN environment variable
3. github.token in ~/.config/fledge/config.toml
4. gh auth token (GitHub CLI fallback)

If you have the GitHub CLI (gh) installed and authenticated, fledge will use it automatically — no extra config needed.

# Set via config
fledge config set github.token ghp_your_token_here

# Or via environment
export GITHUB_TOKEN=ghp_your_token_here

# Or just use gh (zero config)
gh auth login

The token is injected via git’s http.extraheader mechanism — it is never embedded in remote URLs or persisted to disk.

Security Model

Plugins run arbitrary code. Fledge has several safeguards:

• Install confirmation — before cloning, fledge warns that plugins can execute arbitrary code and asks for confirmation. Pass --force to skip (CI/scripts).
• Plugin name validation — repo names are checked for path traversal (.., /, \, leading .)
• Command name validation — command names that become symlinks (fledge-<name>) are validated to reject /, \, . prefix, - prefix, and null bytes
• Binary path traversal — plugin binaries cannot reference paths outside the plugin directory (both sides are canonicalized to defeat symlink bypass)
• Hook execution — hooks run as direct processes, not via a shell. This prevents shell injection but means pipes, redirects, and shell expansions won’t work in hook commands. Use a wrapper script if you need shell features.

CI / Non-Interactive Usage

Without these flags, interactive prompts will cause CI pipelines to hang.

File Locations

GitHub Integration

fledge talks to GitHub for issues, PRs, CI status, and a branch-based dev workflow. All from the terminal.

Setup

You need a GitHub token:

# Environment variable (recommended)
export GITHUB_TOKEN="ghp_..."

# Or store it in config
fledge config set github.token "ghp_..."

Token priority: FLEDGE_GITHUB_TOKEN > GITHUB_TOKEN > config file > gh auth token (GitHub CLI).

If you have the GitHub CLI (gh) installed and authenticated, fledge uses it automatically as a fallback — no extra config needed.

The repo is auto-detected from your git remote.

Feature Branch Workflow

Start a Branch

fledge work start add-dark-mode
# → creates leif/feat/add-dark-mode (default: {author}/{type}/{name})

fledge work start login-crash --branch-type fix
# → creates leif/fix/login-crash

fledge work start fix-login --base develop
# → branches from develop instead of main

fledge work start login-crash --issue 42
# → creates leif/feat/42-login-crash (linked to issue #42)

fledge work start my-feature --prefix user/leif
# → creates user/leif/my-feature (custom prefix, overrides format)

Branch names get sanitized automatically (spaces → hyphens, special chars removed). The default type is feat, but you can use feature, fix, bug, chore, task, docs, hotfix, or refactor via --branch-type (or -t for short). The branch format is configurable in fledge.toml.

Open a PR

fledge work pr                                    # auto-title from branch
fledge work pr --title "Add dark mode" --body "Adds dark mode toggle to settings" # custom
fledge work pr --draft                            # draft PR
fledge work pr --base develop                     # target branch

Check Status

fledge work status    # current branch + PR status

Issues

fledge issues                    # open issues
fledge issues --state closed     # closed ones
fledge issues --label bug        # filter by label
fledge issues view 42            # specific issue
fledge issues --limit 50
fledge issues --json

Pull Requests

fledge prs                       # open PRs
fledge prs --state closed
fledge prs view 75
fledge prs --json

CI Status

fledge checks                    # current branch
fledge checks --branch main
fledge checks --json

AI Code Review

Uses Claude to review your changes:

fledge review                    # all changes on current branch
fledge review --base develop     # diff against develop
fledge review --file src/main.rs # just one file

AI Q&A

Ask questions about your codebase:

fledge ask "how does the template rendering work?"
fledge ask "what tests cover the config module?"

Typical Workflow

fledge work start user-auth      # 1. start a work branch
fledge run test                  # 2. code + test
fledge lanes run ci              # 3. run the full pipeline
fledge review                    # 4. AI review
fledge work pr --title "Add user auth"  # 5. open PR
fledge checks                    # 6. watch CI

CLI Reference

Every command, every flag. If it’s in fledge, it’s here.

Jump to: Start | Build | Develop | Review | Ship | Extend

Start: Scaffold and discover

All template commands live under fledge templates (alias: fledge template).

fledge templates init <name>

Create a new project from a template.

fledge templates init <name> [OPTIONS]

Arguments:

• <name> - Project name

Options:

• -t, --template <TEMPLATE> - Template to use (skips interactive selection)
• -o, --output <OUTPUT> - Where to put it [default: .]
• --author <AUTHOR> - Author name (bypasses prompt; overrides config)
• --org <ORG> - GitHub organization (bypasses prompt; overrides config)
• --no-git - Skip git init and initial commit
• --no-install - Skip post-create hooks
• --refresh - Force re-clone of cached remote templates
• --dry-run - Preview without writing anything
• -y, --yes - Accept all defaults, skip prompts

Behavior:

• If the template specifies min_fledge_version, fledge checks compatibility before proceeding.
• If the template specifies requires (tool dependencies), fledge checks they’re on PATH and warns about missing ones.
• If the template doesn’t include a fledge.toml, one is auto-generated from detected project type defaults.
• If no git user is configured, defaults to user.name=fledge and user.email=fledge@localhost.
• Plugin pre_init lifecycle hooks run before config loading (if any plugins define them).

Examples:

fledge templates init my-tool --template rust-cli
fledge templates init my-app --template ts-bun --dry-run
fledge templates init my-lib --template go-cli --yes
fledge templates init my-project --template python-cli -o ~/projects
fledge templates init my-app --template CorvidLabs/fledge-templates/deno-cli@v2.0
fledge templates init my-tool --template rust-cli --author "Leif" --org CorvidLabs --yes

fledge templates list

Show all available templates (built-in, configured repos, and local paths).

fledge templates list

fledge templates create <name>

Scaffold a new template directory with template.toml and example files.

fledge templates create <name> [OPTIONS]

Options:

• -o, --output <OUTPUT> - Parent directory [default: .]
• -d, --description <DESC> - Template description (bypasses prompt)
• --render-patterns <PATTERNS> - Comma-separated file patterns to render through Tera (bypasses prompt)
• --hooks [BOOL] - Include post-create hooks scaffold (bypasses prompt; accepts optional true/false, defaults to true)
• --prompts [BOOL] - Include custom prompts scaffold (bypasses prompt; accepts optional true/false, defaults to true)
• -y, --yes - Skip all interactive prompts (accept defaults)

Examples:

fledge templates create my-template
fledge templates create my-template -d "FastAPI starter" --render-patterns "**/*.py,**/*.toml" --hooks --yes

fledge templates validate [path]

Check a template for issues: manifest parsing, Tera syntax, undefined variables, glob coverage. GitHub Actions ${{ }} syntax is automatically filtered out so it isn’t flagged as Tera.

fledge templates validate [path] [OPTIONS]

Arguments:

• [path] - Template directory or directory of templates [default: .]

Options:

• --strict - Warnings become errors (non-zero exit)
• --json - Machine-readable output

Examples:

fledge templates validate ./my-template
fledge templates validate ./templates
fledge templates validate ./templates --strict   # for CI
fledge templates validate ./templates --json

fledge templates search [query]

Find templates on GitHub (looks for the fledge-template topic).

fledge templates search [query] [OPTIONS]

Options:

• -a, --author <OWNER> - Filter by author/owner
• -l, --limit <N> - Max results [default: 20, max: 100]
• --json - JSON output

Output format: Results show repo name, star count (abbreviated with “k” suffix for 1000+), and description (truncated to 60 characters). Topics are shown below each result.

fledge templates publish [path]

Push a template to GitHub as a new repo tagged with fledge-template.

fledge templates publish [path] [OPTIONS]

Options:

• --org <ORG> - Publish under an org
• --private - Private repo
• --description <DESC> - Override repo description (falls back to description in template.toml)

Behavior:

• If the repo already exists on GitHub, prompts for confirmation before updating.
• Auto-initializes git (.git) if the template directory doesn’t have one.
• Cleans up embedded tokens from the remote URL after push.

fledge templates update

Re-apply the source template to an existing project. Handy when the template gets updated.

fledge templates update [OPTIONS]

Options:

• --dry-run - Preview changes
• --refresh - Force re-clone

Build: Configure and run

fledge run [task]

Run tasks. Works with zero config (auto-detects your project type) or from fledge.toml when you want full control.

fledge run [task] [OPTIONS]

Options:

• --init - Generate fledge.toml with detected defaults
• -l, --list - List available tasks
• --lang <LANG> - Override detected project language (swift, python, rust, node, go, ruby, java-gradle, java-maven)

Zero-config mode (no fledge.toml): Fledge detects your project type from marker files and provides default tasks automatically. For Node.js projects, it also detects your package manager (npm, bun, yarn, pnpm) from lockfiles.

Config mode (fledge.toml exists): The config file takes full precedence. No mixing with auto-detection.

Auto-detection:

fledge run test          # works immediately in any detected project
fledge run --list        # see what's available
fledge run --init        # generate fledge.toml to customize
fledge run build         # run a specific task
fledge run test --lang swift  # override detected language

fledge lanes

Manage and run composable workflow pipelines.

fledge lanes <run|list|init|search|import|publish|create|validate>

Subcommands:

• run <name> - Run a lane by name (--dry-run to preview)
• list - List available lanes (--json for JSON output)
• init - Add default lanes to fledge.toml
• search [query] - Search GitHub for community lanes (--author, --json)
• import <source> - Import lanes from a GitHub repo (owner/repo or owner/repo@ref)
• publish [path] - Publish lanes to GitHub (--org, --private, --description)
• create <name> - Scaffold a new lane repo (--output, --description, --yes)
• validate [path] - Validate lane definitions in fledge.toml (--strict, --json)

Shortcut: fledge lanes ci is equivalent to fledge lanes run ci.

Lane config in fledge.toml:

[lanes.ci]
description = "Full CI pipeline"
steps = ["lint", "test", "build"]

[lanes.check]
steps = [
  { parallel = ["lint", "fmt"] },
  "test"
]

[lanes.release]
fail_fast = false
steps = [
  "test",
  { run = "cargo build --release" },
  "publish"
]

Step types:

fledge lanes run ci           # run a lane
fledge lanes run ci --dry-run
fledge lanes list
fledge lanes list --json
fledge lanes init
fledge lanes search
fledge lanes search rust
fledge lanes import CorvidLabs/fledge-lanes
fledge lanes publish --org MyOrg
fledge lanes create my-lanes
fledge lanes create my-lanes --yes --description "My CI lanes"
fledge lanes validate
fledge lanes validate ./my-lanes --strict
fledge lanes validate --json

fledge config <action>

Manage ~/.config/fledge/config.toml.

fledge config <get|set|unset|add|remove|list|path|init>

Valid keys:

• defaults.author, defaults.github_org, defaults.license
• github.token
• templates.paths, templates.repos

fledge config set defaults.author "Leif"
fledge config add templates.repos "CorvidLabs/fledge-templates"
fledge config list

fledge doctor

Check your environment for issues (missing tools, bad config, etc). Run this before fledge run if something seems off.

fledge doctor [OPTIONS]

Options:

• --json - JSON output

Develop: Branch and spec

fledge work <action>

Work branch and PR workflow. Supports any branch type, not just features.

fledge work <start|pr|status> [OPTIONS]

Subcommands:

• start <name> - Create a work branch
• pr - Open a PR (-t, --title, -b, --body, --draft, --base)
• status - Current branch + PR status

Options for work start:

• -t, --branch-type <TYPE> - Branch type: feat, feature, fix, bug, chore, task, docs, hotfix, refactor [default: feat]
• -i, --issue <NUMBER> - Link to GitHub issue (prefixes branch name with issue number)
• --prefix <PREFIX> - Override branch prefix entirely (e.g. user/leif)
• --base <BRANCH> - Base branch [default: main]

The branch format is configurable via [work] in fledge.toml:

[work]
default_type = "feat"
branch_format = "{author}/{type}/{name}"

Examples:

fledge work start add-auth                    # leif/feat/add-auth (default: {author}/{type}/{name})
fledge work start login-crash --branch-type fix      # leif/fix/login-crash
fledge work start bump-deps --branch-type chore      # leif/chore/bump-deps
fledge work start login-crash --issue 42      # leif/feat/42-login-crash
fledge work start my-feature --prefix user/leif  # user/leif/my-feature

fledge spec <action>

Spec-sync management. Specs are the source of truth for module design.

fledge spec <check|init|new> [OPTIONS]

Subcommands:

• check - Validate specs against code (--strict for warnings as errors)
• init - Set up spec-sync for the project
• new <name> - Scaffold a new spec

Review: Quality and insight

fledge review

AI code review via Claude. Diffs your branch against the base and gives feedback.

fledge review [OPTIONS]

Options:

• -b, --base <BRANCH> - Base branch [default: auto-detect]
• -f, --file <FILE> - Review a single file
• --json - JSON output

Default branch detection: When --base is not specified, fledge tries git symbolic-ref refs/remotes/origin/HEAD, then checks for main and master branches. Falls back to main if none exist.

fledge ask <question>

Ask about your codebase. Claude reads your code and answers.

fledge ask <question> [OPTIONS]

Options:

• --json - JSON output

fledge ask "how does the template rendering work?"
fledge ask "what tests cover the config module?"

fledge metrics

Code stats: LOC by language, file churn, test ratio.

fledge metrics [OPTIONS]

Options:

• --churn - Most-changed files from git history
• --tests - Test file detection and ratio
• -l, --limit <N> - Max churn entries [default: 20]
• --json - JSON output

fledge metrics
fledge metrics --churn
fledge metrics --tests
fledge metrics --churn --tests --json

fledge deps

Dependency health checks.

fledge deps [OPTIONS]

Options:

• --outdated - Find stale dependencies
• --audit - Security audit
• --licenses - License scan
• --json - JSON output

Works with:

fledge deps
fledge deps --outdated
fledge deps --audit
fledge deps --outdated --audit --licenses --json

Ship: Track and release

fledge issues [view <number>]

List and view GitHub issues.

fledge issues [OPTIONS]
fledge issues view <number> [OPTIONS]

Options:

• -s, --state <STATE> - open, closed, all [default: open]
• -l, --limit <N> - Max results [default: 20]
• --label <LABEL> - Filter by label
• --json

fledge prs [view <number>]

List and view pull requests.

fledge prs [OPTIONS]
fledge prs view <number> [OPTIONS]

Options:

• -s, --state <STATE> - open, closed, all [default: open]
• -l, --limit <N> - Max results [default: 20]
• --json

fledge checks

CI/CD status for a branch.

fledge checks [OPTIONS]

Options:

• -b, --branch <BRANCH> - Branch to check [default: current]
• --json

fledge changelog

Generate a changelog from git tags and conventional commits.

fledge changelog [OPTIONS]

Options:

• -l, --limit <N> - Releases to show [default: 10]
• -t, --tag <TAG> - Specific tag
• --unreleased - Changes since last tag
• --json - JSON output

fledge changelog
fledge changelog --unreleased
fledge changelog --json
fledge changelog --tag v0.7.0

fledge release <bump>

Cut a release — bump version, generate changelog, create a git tag, and optionally push.

fledge release <bump> [OPTIONS]

Arguments:

• <bump> - Version bump: major, minor, patch, or an explicit version (e.g. 1.0.0)

Options:

• --dry-run - Show what would happen without making changes
• --no-tag - Skip creating a git tag
• --no-changelog - Skip changelog generation
• --push - Push commit and tag to remote after release
• --pre-lane <NAME> - Run a lane before releasing (e.g. ci)
• --allow-dirty - Allow releasing with uncommitted changes

Examples:

fledge release patch                          # bump patch version
fledge release minor --push                   # bump minor + push
fledge release major --pre-lane ci            # run CI lane first, then bump major
fledge release 2.0.0 --dry-run               # preview a specific version bump
fledge release patch --no-tag --no-changelog  # just bump version

Extend: Grow the tool

fledge plugins <action>

Install, manage, and run community plugins.

fledge plugins <install|remove|update|list|search|run|publish|create|validate> [OPTIONS]

Subcommands:

• install <source[@ref]> - Install from GitHub (owner/repo[@tag] or URL). --force to reinstall. Use @ref to pin to a tag, branch, or commit.
• remove <name> - Uninstall a plugin
• update [name] - Update plugins. Unpinned plugins get git pull; pinned plugins check for newer tags.
• list - Show installed plugins (includes pinned version info)
• search [query] - Find plugins on GitHub (--author, --limit)
• run <name> [args...] - Run a plugin command
• publish [path] - Publish a plugin to GitHub (--org, --private, --description)
• create <name> - Scaffold a new plugin (--output, --description, --yes)
• validate [path] - Validate a plugin manifest (--strict, --json)

--json works with list and search.

Plugin format (plugin.toml):

[plugin]
name = "fledge-deploy"
version = "0.1.0"
description = "Deploy to cloud providers"
author = "someone"

[[commands]]
name = "deploy"
description = "Deploy the project"
binary = "fledge-deploy"

[hooks]
build = "cargo build --release"
post_install = "echo 'Deploy plugin ready'"

fledge plugins install someone/fledge-deploy
fledge plugins install someone/fledge-deploy@v1.2.0   # pin to version
fledge plugins update                                   # update all
fledge plugins list
fledge plugins search deploy
fledge plugins remove fledge-deploy
fledge plugins publish --org MyOrg
fledge plugins create my-tool
fledge plugins create my-tool --yes --description "My deploy tool"
fledge plugins validate
fledge plugins validate ./my-tool --strict
fledge plugins validate --json

fledge completions [shell]

Shell completions for bash, zsh, fish.

fledge completions [shell] [OPTIONS]

Options:

• --install - Auto-install for your current shell

fledge completions --install
fledge completions bash >> ~/.bashrc
fledge completions zsh > ~/.zfunc/_fledge
fledge completions fish > ~/.config/fish/completions/fledge.fish

Troubleshooting

Common issues and how to fix them.

“command not found: fledge”

fledge isn’t on your PATH. If you installed via cargo install:

# Make sure ~/.cargo/bin is on your PATH
export PATH="$HOME/.cargo/bin:$PATH"

Add that line to your .bashrc, .zshrc, or shell profile. Then restart your terminal or run source ~/.zshrc.

GitHub commands fail with “no token”

Commands that talk to GitHub (issues, prs, checks, work pr, review, templates search) need a GitHub personal access token.

# Easiest: use the GitHub CLI (zero config)
gh auth login

# Or set it as an environment variable
export GITHUB_TOKEN="ghp_..."

# Or store it in fledge config
fledge config set github.token "ghp_..."

The token needs repo scope for private repos, or just public_repo for public ones. If you have gh installed and authenticated, fledge uses it automatically as a fallback.

“no template found” when running init

Check what’s available:

fledge templates list

If you expect remote templates, make sure the repo is configured:

fledge config add templates.repos "CorvidLabs/fledge-templates"

Or use the full path:

fledge templates init my-app --template CorvidLabs/fledge-templates/python-api

Tasks not detected (fledge run shows nothing)

fledge auto-detects your project type from marker files. If it doesn’t find anything:

1. Make sure you’re in the project root (where Cargo.toml, package.json, etc. live)
2. Run fledge doctor to check your environment
3. If auto-detection doesn’t fit, create a fledge.toml manually:

fledge run --init

Template hooks won’t run

Remote template hooks require confirmation for security. If you trust the template:

fledge templates init my-app --template user/repo --yes

If hooks fail after confirmation, check that the required tools are installed (e.g., npm, pip, cargo fmt).

“rate limit exceeded” from GitHub

GitHub’s API has rate limits. Authenticated requests get 5,000/hour vs 60/hour for unauthenticated.

# Set your token to get higher limits
export GITHUB_TOKEN="ghp_..."

Cached templates are stale

Templates from remote repos are cached locally. To force a fresh download:

fledge templates init my-app --template user/repo --refresh

fledge review / fledge ask not working

These commands use the Claude CLI. Make sure it’s installed and authenticated:

claude --version

If Claude isn’t installed, see Claude CLI docs for setup instructions.

Clippy or fmt warnings in CI

Run these locally before pushing:

cargo clippy -- -D warnings
cargo fmt --check

If clippy finds issues, fix them. If formatting is off, run cargo fmt (without --check) to auto-fix.

Still stuck?

1. Run fledge doctor for a full environment check
2. Check GitHub Issues for known problems
3. Open a new issue with:
   • Your OS and fledge version (fledge --version)
   • The command you ran
   • The full error output

Changelog

fledge generates changelogs from your git tags and conventional commits.

Usage

fledge changelog                 # recent releases
fledge changelog --unreleased    # changes since last tag
fledge changelog --tag v0.7.0    # specific release
fledge changelog --limit 5       # last 5 releases
fledge changelog --json          # machine-readable

Commit Format

fledge follows Conventional Commits. The format is:

<type>[optional scope]: <description>

Types and how they appear in the changelog:

Commits that don’t match any type are grouped under “Other”.

Examples:

feat: add dark mode toggle
fix(auth): handle expired tokens
chore: bump dependencies
refactor: simplify config loader

Versioning

fledge reads git tags that follow semver (v1.2.3). Each tag becomes a changelog section. Commits without a tag end up in the --unreleased section.

Config

No config required. fledge reads your git history directly.

Full Changelog

See CHANGELOG.md for the complete release history.