You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 46a0c27
Browse filesBrowse the repository at this point in the historyBrowse files
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.
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:
Copy file name to clipboardExpand all lines: docs/installation.md
+2Lines changed: 2 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,8 @@ specify version
91
91
92
92
This helps verify you are running the official Spec Kit build from GitHub, not an unrelated package with the same name.
93
93
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
+
94
96
After initialization, you should see the following commands available in your coding agent:
Copy file name to clipboardExpand all lines: docs/upgrade.md
+49-9Lines changed: 49 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,17 +8,43 @@
8
8
9
9
| What to Upgrade | Command | When to Use |
10
10
|----------------|---------|-------------|
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. |
15
17
16
18
---
17
19
18
20
## Part 1: Upgrade the CLI Tool
19
21
20
22
The CLI tool (`specify`) is separate from your project files. Upgrade it to get the latest features and bug fixes.
21
23
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
+
22
48
### If you installed with `uv tool install`
23
49
24
50
Upgrade to a specific release (check [Releases](https://github.com/github/spec-kit/releases) for the latest tag):
# Confirms the CLI is working and shows installed tools
49
76
specify check
77
+
78
+
# Confirms the installed version against the latest GitHub release
79
+
specify self check
50
80
```
51
81
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.
53
83
54
84
---
55
85
@@ -178,8 +208,8 @@ Restart your IDE to refresh the command list.
0 commit comments