Skip to content

Commit ba2edba

Browse files
committed
feat(cli): embed core pack in wheel + offline-first init (github#1711, github#1752)
Bundle templates, commands, and scripts inside the specify-cli wheel so that `specify init` works without any network access by default. Changes: - pyproject.toml: add hatchling force-include for core_pack assets; bump version to 0.2.1 - __init__.py: add _locate_core_pack(), _generate_agent_commands() (Python port of generate_commands() shell function), and scaffold_from_core_pack(); modify init() to scaffold from bundled assets by default; add --from-github flag to opt back in to the GitHub download path - release.yml: build wheel during CI release job - create-github-release.sh: attach .whl as a release asset - docs/installation.md: add Enterprise/Air-Gapped Installation section - README.md: add Option 3 enterprise install with accurate offline story Closes github#1711 Addresses github#1752
1 parent 65ecd53 commit ba2edba

7 files changed

Lines changed: 355 additions & 13 deletions

File tree

‎.github/workflows/release.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,12 @@ jobs:
3232
env:
3333
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
3434

35+
- name: Build Python wheel
36+
if: steps.check_release.outputs.exists == 'false'
37+
run: |
38+
pip install build
39+
python -m build --wheel --outdir .genreleases/
40+
3541
- name: Create release package variants
3642
if: steps.check_release.outputs.exists == 'false'
3743
run: |

‎.github/workflows/scripts/create-github-release.sh‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ VERSION="$1"
1616
VERSION_NO_V=${VERSION#v}
1717

1818
gh release create "$VERSION" \
19+
.genreleases/specify_cli-"$VERSION_NO_V"-py3-none-any.whl \
1920
.genreleases/spec-kit-template-copilot-sh-"$VERSION".zip \
2021
.genreleases/spec-kit-template-copilot-ps-"$VERSION".zip \
2122
.genreleases/spec-kit-template-claude-sh-"$VERSION".zip \

‎CHANGELOG.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,9 @@
8585
- Scripts updated to use template resolution instead of hardcoded paths
8686
- feat(presets): Preset command overrides now propagate to agent skills when `--ai-skills` was used during init
8787
- feat: `specify init` persists CLI options to `.specify/init-options.json` for downstream operations
88+
- feat(cli): embed core templates/commands/scripts in wheel for air-gapped deployment; `specify init` now works offline by default (#1711)
89+
- feat(cli): add `--from-github` flag to `specify init` to force download from GitHub releases instead of using bundled assets
90+
- feat(release): build and publish `specify_cli-*.whl` Python wheel as a release asset for enterprise/offline installation (#1752)
8891
- feat(extensions): support `.extensionignore` to exclude files/folders during `specify extension add` (#1781)
8992

9093
## [0.2.1] - 2026-03-11

‎README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,17 @@ uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai c
9797
- Better tool management with `uv tool list`, `uv tool upgrade`, `uv tool uninstall`
9898
- Cleaner shell configuration
9999

100+
#### Option 3: Enterprise / Air-Gapped Installation
101+
102+
If your environment blocks PyPI access, download the pre-built `specify_cli-*.whl` wheel from the [releases page](https://github.com/github/spec-kit/releases/latest) and install it directly:
103+
104+
```bash
105+
pip install specify_cli-*.whl
106+
specify init my-project --ai claude # works fully offline — no api.github.com needed
107+
```
108+
109+
The wheel bundles all templates, commands, and scripts, so `specify init` works without any network access after install. See the [Enterprise / Air-Gapped Installation](./docs/installation.md#enterprise--air-gapped-installation) section for fully offline (no-PyPI) instructions.
110+
100111
### 2. Establish project principles
101112

102113
Launch your AI assistant in the project directory. Most agents expose spec-kit as `/speckit.*` slash commands; Codex CLI in skills mode uses `$speckit-*` instead.

‎docs/installation.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,50 @@ The `.specify/scripts` directory will contain both `.sh` and `.ps1` scripts.
7575

7676
## Troubleshooting
7777

78+
### Enterprise / Air-Gapped Installation
79+
80+
If your environment blocks access to PyPI (you see 403 errors when running `uv tool install` or `pip install`), you can install Specify using the pre-built wheel from the GitHub releases page.
81+
82+
**Step 1: Download the wheel**
83+
84+
Go to the [Spec Kit releases page](https://github.com/github/spec-kit/releases/latest) and download the `specify_cli-*.whl` file.
85+
86+
**Step 2: Install the wheel**
87+
88+
```bash
89+
pip install specify_cli-*.whl
90+
```
91+
92+
**Step 3: Initialize a project (no network required)**
93+
94+
```bash
95+
specify init my-project --ai claude
96+
```
97+
98+
The CLI bundles all templates, commands, and scripts inside the wheel, so `specify init` works completely offline — no connection to `api.github.com` needed.
99+
100+
**If you also need runtime dependencies offline** (fully air-gapped machines with no access to any PyPI), use a connected machine with the same OS and Python version to download them first:
101+
102+
```bash
103+
# On a connected machine (same OS and Python version as the target):
104+
pip download -d vendor specify_cli-*.whl
105+
106+
# Transfer the wheel and vendor/ directory to the target machine
107+
108+
# On the target machine:
109+
pip install --no-index --find-links=./vendor specify_cli-*.whl
110+
```
111+
112+
> **Note:** Python 3.11+ is required. The wheel is a pure-Python artifact, so it works on any platform without recompilation.
113+
114+
**Getting the latest templates without upgrading the CLI:**
115+
116+
If you want to pull freshly generated command files from the latest GitHub release instead of the bundled copy, use:
117+
118+
```bash
119+
specify init my-project --ai claude --from-github
120+
```
121+
78122
### Git Credential Manager on Linux
79123

80124
If you're having issues with Git authentication on Linux, you can install Git Credential Manager:

‎pyproject.toml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,13 @@ build-backend = "hatchling.build"
2727
[tool.hatch.build.targets.wheel]
2828
packages = ["src/specify_cli"]
2929

30+
[tool.hatch.build.targets.wheel.force-include]
31+
# Bundle core assets so `specify init` works without network access (air-gapped / enterprise)
32+
"templates" = "specify_cli/core_pack/templates"
33+
"templates/commands" = "specify_cli/core_pack/commands"
34+
"scripts/bash" = "specify_cli/core_pack/scripts/bash"
35+
"scripts/powershell" = "specify_cli/core_pack/scripts/powershell"
36+
3037
[project.optional-dependencies]
3138
test = [
3239
"pytest>=7.0",

0 commit comments

Comments
 (0)