fledge 0.11.1

Dev-lifecycle CLI — scaffolding, tasks, lanes, plugins, and more.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

# Configuration

## Quick Setup

Use a preset to get started fast:

```bash
# 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:

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

| Key | What it does | Fallback |
|-----|-------------|----------|
| `author` | Default author name | `git config user.name` |
| `github_org` | Default GitHub org | Prompted |
| `license` | Default license | `MIT` |

### [templates]

Where to find templates:

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

| Key | What it does |
|-----|-------------|
| `paths` | Local directories with templates |
| `repos` | GitHub repos to pull templates from (`owner/repo`) |

### [github]

```toml
[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:**

| Feature | Scopes needed |
|---------|--------------|
| Issues, PRs, CI checks | `repo` (or `public_repo` for public repos only) |
| Create PRs, push branches | `repo` |
| Search templates/plugins | `public_repo` |
| Publish templates | `repo`, `delete_repo` (if republishing) |

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

```toml
[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

| Variable | What it does |
|----------|-------------|
| `FLEDGE_GITHUB_TOKEN` | GitHub token (highest priority) |
| `GITHUB_TOKEN` | GitHub token (fallback after FLEDGE_GITHUB_TOKEN) |

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](./lanes.md) — defining lanes, step types, parallel groups, importing community lanes
- [Plugins](./plugins.md) — 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