Using fledge with AI agents

fledge is designed for humans and AI agents to use the same CLI. Human-facing docs (the rest of this book) cover why and how-to. This page covers what an agent specifically needs to know.

The canonical short-form entrypoint for agents lives at AGENTS.md in the repository root. This page is its long-form companion. Point agents to either. For how specs work and why they matter, see Spec: Spec-sync.

Design principles

fledge follows four rules that make it agent-usable:

Structured output is first-class. Most commands accept --json. Never require an agent to screen-scrape.
Non-interactive bypass exists. Every command that prompts has a --yes flag. Silence isn’t success, it’s a hung process.
Specs are machine-readable. fledge spec list --json and fledge spec show <name> --json let agents discover the codebase’s intent without filesystem spelunking.
The whole CLI introspects. fledge introspect --json dumps the entire command tree (incl. plugin commands). One call teaches an agent the surface.

First-time agent setup

export FLEDGE_NON_INTERACTIVE=1               # silence every prompt
fledge plugins install --defaults             # github + deps + metrics
fledge introspect --json                      # full command tree (incl. plugin commands)
fledge spec list --json                       # semantic project map

After those four lines, every command and flag is discoverable as data.

The agent-facing surface

Core commands with `--json`

Every --json output is {schema_version: 1, ...}. Two patterns coexist:

Pillar list/query commands use {schema_version: 1, <resource>: [...]}.
Cross-cutting commands use {schema_version: 1, action: "<verb>", ...}.

Command	Payload shape
`fledge introspect --json`	`{schema_version: 1, name, about, aliases, args, subcommands}` recursively. Each node’s `args` is the complete set of flags accepted at that level, including inherited globals from ancestors (marked `global: true`). No need to walk up the parent chain
`fledge spec list --json`	`{schema_version: 1, action: "spec_list", specs: [...]}`
`fledge spec show <name> --json`	`{schema_version: 1, action: "spec_show", spec: {...}}`
`fledge spec check --json`	`{schema_version: 1, action: "spec_check", specs, totals, strict}`
`fledge ai status --json`	`{schema_version: 1, action: "ai_status", provider, model, host, *_source}`. What’s active and the source of each value
`fledge ai models --provider {claude,ollama} --json`	`{schema_version: 1, action: "ai_models", provider, models: [...]}`
`fledge ask "..." --json`	`{schema_version: 1, action: "ask", question, answer, provider, model}`
`fledge review --json`	`{schema_version: 1, action: "review", base, file, diff_stats, spec_context, reviews: [...], review?, provider?, model?}`. Top-level `review`/`provider`/`model` only when panel size is 1
`fledge doctor --json`	`{schema_version: 1, action: "doctor", sections: [...], passed, failed}`. Four sections (`fledge`, `Git`, `AI`, `Toolchains`). `Toolchains` is informational, missing tools render dimmed and aren’t counted toward `failed`
`fledge changelog --json`	`{schema_version: 1, action: "changelog", releases: [{tag, date, sections}]}`
`fledge run --list --json`	`{schema_version: 1, action: "run_list", auto_detected, tasks: [...]}`
`fledge run <task> --json`	`{schema_version: 1, action: "run_task", task, command, exit_code, success, stdout, stderr}`
`fledge templates list --json`	`{schema_version: 1, templates: [...]}`
`fledge templates search --json`	`{schema_version: 1, results: [...]}`
`fledge templates validate --json`	`{schema_version: 1, reports: [...]}`
`fledge plugins list --json`	`{schema_version: 1, plugins: [...]}`
`fledge plugins audit --json`	`{schema_version: 1, audit: [...]}`
`fledge plugins search --json`	`{schema_version: 1, results: [...]}`
`fledge plugins validate --json`	`{schema_version: 1, path, plugin_name, errors, warnings}`
`fledge lanes list --json`	`{schema_version: 1, lanes: [...]}`
`fledge lanes search --json`	`{schema_version: 1, results: [...]}`
`fledge lanes run <name> --json`	`{schema_version: 1, lane, success, duration_ms, fail_fast, steps, failures}`. Each `steps` entry has `step, name, success, duration_ms, error`; retried steps additionally carry `attempts: <n>`; skipped steps carry `skipped: true, reason: "when 'X' not met"` or `reason: "--from"` (with `success: null, duration_ms: null, error: null`). `--from <step\|index>` is also supported on `lanes run`.
`fledge lanes validate --json`	`{schema_version: 1, path, lane_count, errors, warnings}`
`fledge work start <name> --json`	`{schema_version: 1, action: "work_start", branch, base, type, prefix, issue}`
`fledge work commit --json`	`{schema_version: 1, action: "work_commit", hash, message, branch}`
`fledge work push --json`	`{schema_version: 1, action: "work_push", branch, remote, force}`
`fledge work status --json`	`{schema_version: 2, action: "work_status", branch, default, ahead, behind, dirty}`

Plugin commands with `--json` (after `plugins install --defaults`)

Command	Plugin
`fledge github checks --json`	`fledge-plugin-github`. Raw GitHub API `check-runs` response
`fledge github issues --json` / `fledge github issues view <n> --json`	`fledge-plugin-github`
`fledge github prs --json` / `fledge github prs view <n> --json`	`fledge-plugin-github`
`fledge github prs create --fill --json`	`fledge-plugin-github`. Returns `{number, url, title}`
`fledge github issues create --title "..." --json`	`fledge-plugin-github`. Returns `{number, url, title}`
`fledge deps --json`	`fledge-plugin-deps`. Ecosystem tool’s native output
`fledge metrics --json` / `--churn --json` / `--tests --json`	`fledge-plugin-metrics`. LOC summary (tokei linked as a library), per-file churn, test/source ratio

Non-interactive mode (one switch)

Important: Without FLEDGE_NON_INTERACTIVE=1, any command with a prompt will hang in a headless environment.

Set FLEDGE_NON_INTERACTIVE=1 in your environment, or pass --non-interactive (alias --ni) per invocation. Both flip a global flag that every prompt site observes. Every --yes/--force is auto-promoted, and prompts that need user input bail cleanly instead of hanging.

Commands covered: fledge templates init, fledge templates create, fledge templates publish, fledge work push, fledge ai use, fledge plugins install, fledge plugins publish, fledge plugins create, fledge lanes publish.

AI-powered commands

fledge ai, fledge ask, and fledge review route through a provider abstraction. Two providers ship in core:

Provider	Transport	Auth	Use case
`claude` (default)	`claude` CLI shell-out	Whatever `claude` is already authenticated with	Best-in-class reasoning, paid
`ollama`	HTTP to `<host>/api/generate`	Optional Bearer token	Local-only, offline, cloud alternatives, self-hosted

Select via fledge ai use <provider> [model] (writes to config), FLEDGE_AI_PROVIDER=ollama, or --provider ollama per invocation. fledge ai status reports the active triplet and the source of each value.

`fledge ask` is spec-aware

By default, every fledge ask invocation prepends a compact one-line-per-module index of every spec into the prompt. Pass --with-specs <names> to include the full spec + companion files for one or more modules.

`fledge review` is multi-model-capable

Pass --with-model <provider[:model]> (repeatable, comma-separated) to run multiple models in parallel against the same diff and spec context. The JSON output’s reviews[] array has one entry per slot. Per-slot failures don’t abort the panel.

fledge review --json
fledge review --with-model ollama --json
fledge review --no-active --with-model claude:sonnet,ollama --json

Typical agent workflow

# 1. Orient
fledge introspect --json
fledge spec list --json

# 2. Branch
fledge work start fix-issue-42 --branch-type fix --issue 42 --json

# 3. Code, test
fledge run test
fledge lanes run pre-commit

# 4. Review (multi-model for high-confidence findings)
fledge review --with-model ollama --json

# 5. Push and open PR
fledge work push --json
fledge github prs create --title "fix: issue 42" --json

# 6. Wait for CI
fledge github checks --json    # via fledge-plugin-github