Skip to content

Commit 46a0c27

Browse files
committed
feat(cli): implement specify self upgrade
Replace the v0.7.5 reserved stub from github#2316 with an actually working self-upgrade command. Detects the install method (uv tool / pipx / uvx-ephemeral / source-checkout / unsupported) via a 3-tier ladder (path-prefix match -> editable-install marker -> PATH+registry reconciliation), runs the appropriate installer subprocess, and verifies the result by spawning a child `specify --version`. - Bare `specify self upgrade` executes immediately, matching the `pip install -U` / `uv tool upgrade` / `npm update` convention. - `--dry-run` prints the preview (method, current, target, argv) and exits 0 without launching any subprocess. - `--tag vX.Y.Z[suffix]` pins a specific release tag (validated against `^v\d+\.\d+\.\d+(?:[a-z0-9.+\-]*)?$`; rejects bare `latest`, branch names, and hash refs). - Token scrubbing: GH_TOKEN / GITHUB_TOKEN are never forwarded to the installer subprocess environment or surfaced in argv. - Exit codes: 0 (success / no-op-success), 1 (resolution failure), 2 (verification mismatch), 3 (installer missing), 124 (subprocess timeout when SPECIFY_UPGRADE_TIMEOUT_SECS is set), other (installer exit propagated verbatim). - uvx-ephemeral runs and source checkouts emit path-specific guidance and exit 0 instead of running an installer. Documentation: README and docs/upgrade.md now lead with the self-management commands as the recommended path; manual `uv tool install --force` / `pipx install --force` remain as fallback for older installs and explicit-control users. docs/installation.md adds a "Stay current" pointer. Closes the unresolved portion of github#2282.
1 parent abb5fe7 commit 46a0c27

6 files changed

Lines changed: 1750 additions & 55 deletions

File tree

‎README.md‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,25 @@ specify init --here --integration copilot
9292
specify check
9393
```
9494

95-
To upgrade Specify, see the [Upgrade Guide](./docs/upgrade.md) for detailed instructions. Quick upgrade:
95+
To upgrade Specify, the CLI ships with two self-management commands that handle the common case for you. See the [Upgrade Guide](./docs/upgrade.md) for detailed scenarios and customization options.
96+
97+
```bash
98+
# Check whether a newer release is available (read-only — does not modify anything)
99+
specify self check
100+
101+
# Preview what would run, without actually upgrading
102+
specify self upgrade --dry-run
103+
104+
# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
105+
specify self upgrade
106+
107+
# Or pin a specific release tag
108+
specify self upgrade --tag vX.Y.Z
109+
```
110+
111+
Bare `specify self upgrade` executes immediately, matching the `pip install -U` / `uv tool upgrade` / `npm update` convention. `uvx`-ephemeral runs and source checkouts are detected and produce path-specific guidance instead of running an installer. Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed).
112+
113+
If you prefer to drive the installer yourself, the manual equivalents still work:
96114

97115
```bash
98116
uv tool install specify-cli --force --from git+https://github.com/github/[email protected]

‎docs/installation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ specify version
9191

9292
This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
9393

94+
**Stay current:** Run `specify self check` periodically to learn whether a newer release is available — it is read-only and never modifies your installation. When you are ready to upgrade, follow the [Upgrade Guide](./upgrade.md).
95+
9496
After initialization, you should see the following commands available in your coding agent:
9597

9698
- `/speckit.specify` - Create specifications

‎docs/upgrade.md‎

Lines changed: 49 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -8,17 +8,43 @@
88

99
| What to Upgrade | Command | When to Use |
1010
|----------------|---------|-------------|
11-
| **CLI Tool Only** | `uv tool install specify-cli --force --from git+https://github.com/github/[email protected]` | Get latest CLI features without touching project files |
12-
| **CLI Tool Only (pipx)** | `pipx install --force git+https://github.com/github/[email protected]` | Reinstall/upgrade a pipx-installed CLI to a specific release |
13-
| **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project |
14-
| **Both** | Run CLI upgrade, then project update | Recommended for major version updates |
11+
| **CLI Tool (recommended)** | `specify self upgrade` | Latest stable release, in place. Auto-detects whether you installed via `uv tool` or `pipx`. |
12+
| **CLI Tool — pin a version** | `specify self upgrade --tag vX.Y.Z` | Upgrade to a specific release tag instead of the latest stable. |
13+
| **CLI Tool — manual fallback** | `uv tool install specify-cli --force --from git+https://github.com/github/[email protected]` | When `specify self upgrade` isn't available (older installs) or when you want explicit control. |
14+
| **CLI Tool — manual fallback (pipx)** | `pipx install --force git+https://github.com/github/[email protected]` | Same as above, for pipx installs. |
15+
| **Project Files** | `specify init --here --force --integration <your-agent>` | Update slash commands, templates, and scripts in your project. |
16+
| **Both** | Run CLI upgrade, then project update | Recommended for major version updates. |
1517

1618
---
1719

1820
## Part 1: Upgrade the CLI Tool
1921

2022
The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
2123

24+
### Recommended: `specify self upgrade`
25+
26+
The CLI ships with two self-management commands that handle the common case automatically:
27+
28+
```bash
29+
# Check whether a newer release is available (read-only — does not modify anything)
30+
specify self check
31+
32+
# Preview what would run, without actually upgrading
33+
specify self upgrade --dry-run
34+
35+
# Upgrade in place to the latest stable release (auto-detects uv tool vs pipx install)
36+
specify self upgrade
37+
38+
# Or pin a specific release tag
39+
specify self upgrade --tag vX.Y.Z
40+
```
41+
42+
Bare `specify self upgrade` executes immediately, matching the `pip install -U` / `uv tool upgrade` / `npm update` convention. The CLI classifies your runtime into one of: `uv tool`, `pipx`, `uvx (ephemeral)`, source checkout, or unsupported. Only `uv tool` and `pipx` are upgraded automatically; the other paths print path-specific guidance and exit 0 without touching anything.
43+
44+
Set `SPECIFY_UPGRADE_TIMEOUT_SECS` to cap how long the installer subprocess may run (default: no timeout — interrupt with `Ctrl+C` if needed).
45+
46+
If `specify self upgrade` isn't available on your install (it shipped in a recent release) or you want explicit control over the installer command, use the manual equivalents below.
47+
2248
### If you installed with `uv tool install`
2349

2450
Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
@@ -46,10 +72,14 @@ pipx install --force git+https://github.com/github/[email protected]
4672
### Verify the upgrade
4773

4874
```bash
75+
# Confirms the CLI is working and shows installed tools
4976
specify check
77+
78+
# Confirms the installed version against the latest GitHub release
79+
specify self check
5080
```
5181

52-
This shows installed tools and confirms the CLI is working.
82+
`specify check` shows the surrounding tool environment; `specify self check` is read-only and tells you whether you're now on the latest release (`Up to date: X.Y.Z`) or if a newer one became available between releases.
5383

5484
---
5585

@@ -178,8 +208,8 @@ Restart your IDE to refresh the command list.
178208
### Scenario 1: "I just want new slash commands"
179209

180210
```bash
181-
# Upgrade CLI (if using persistent install)
182-
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
211+
# Upgrade CLI (auto-detects uv tool vs pipx install)
212+
specify self upgrade
183213

184214
# Update project files to get new commands
185215
specify init --here --force --integration copilot
@@ -196,7 +226,7 @@ cp .specify/memory/constitution.md /tmp/constitution-backup.md
196226
cp -r .specify/templates /tmp/templates-backup
197227

198228
# 2. Upgrade CLI
199-
uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git
229+
specify self upgrade
200230

201231
# 3. Update project
202232
specify init --here --force --integration copilot
@@ -380,7 +410,17 @@ Only Spec Kit infrastructure files:
380410

381411
### "CLI upgrade doesn't seem to work"
382412

383-
Verify the installation:
413+
First, ask the CLI itself:
414+
415+
```bash
416+
# Read-only — prints "Up to date: X.Y.Z" or "Update available: X.Y.Z → Y.Z.W"
417+
specify self check
418+
419+
# Preview the install method, current version, and target tag the upgrade would use
420+
specify self upgrade --dry-run
421+
```
422+
423+
If `self check` shows the wrong version, verify the installation:
384424

385425
```bash
386426
# Check installed tools

0 commit comments

Comments
 (0)