This guide shows how to iterate on the writekit CLI locally without publishing a release or committing to main first.
Scripts now have both Bash (
.sh) and PowerShell (.ps1) variants. The CLI auto-selects based on OS unless you pass--script sh|ps.
git clone https://github.com/hskksk/spec-writing-kit.git
cd spec-writing-kit
# Work on a feature branch
git checkout -b your-feature-branch
You can execute the CLI via the module entrypoint without installing anything:
# From repo root
python -m src.writekit_cli --help
python -m src.writekit_cli init demo-project --ai claude --ignore-agent-tools --script sh
If you prefer invoking the script file style (uses shebang):
python src/writekit_cli/__init__.py init demo-project --script ps
Create an isolated environment using uv so dependencies resolve exactly like end users get them:
# Create & activate virtual env (uv auto-manages .venv)
uv venv
source .venv/bin/activate # or on Windows PowerShell: .venv\Scripts\Activate.ps1
# Install project in editable mode
uv pip install -e .
# Now 'writekit' entrypoint is available
writekit --help
Re-running after code edits requires no reinstall because of editable mode.
uvx can run from a local path (or a Git ref) to simulate user flows:
uvx --from . writekit init demo-uvx --ai copilot --ignore-agent-tools --script sh
You can also point uvx at a specific branch without merging:
# Push your working branch first
git push origin your-feature-branch
uvx --from git+https://github.com/hskksk/spec-writing-kit.git@your-feature-branch writekit init demo-branch-test --script ps
If you’re in another directory, use an absolute path instead of .:
uvx --from /mnt/c/GitHub/spec-writing-kit writekit --help
uvx --from /mnt/c/GitHub/spec-writing-kit writekit init demo-anywhere --ai copilot --ignore-agent-tools --script sh
Set an environment variable for convenience:
export SPEC_WRITING_KIT_SRC=/mnt/c/GitHub/spec-writing-kit
uvx --from "$SPEC_WRITING_KIT_SRC" writekit init demo-env --ai copilot --ignore-agent-tools --script ps
(Optional) Define a shell function:
writekit-dev() { uvx --from /mnt/c/GitHub/spec-writing-kit writekit "$@"; }
# Then
writekit-dev --help
After running an init, check that shell scripts are executable on POSIX systems:
ls -l scripts | grep .sh
# Expect owner execute bit (e.g. -rwxr-xr-x)
On Windows you will instead use the .ps1 scripts (no chmod needed).
Currently no enforced lint config is bundled, but you can quickly sanity check importability:
python -c "import writekit_cli; print('Import OK')"
Validate packaging before publishing:
uv build
ls dist/
Install the built artifact into a fresh throwaway environment if needed.
When testing init --here in a dirty directory, create a temp workspace:
mkdir /tmp/spec-test && cd /tmp/spec-test
python -m src.writekit_cli init --here --ai claude --ignore-agent-tools --script sh # if repo copied here
Or copy only the modified CLI portion if you want a lighter sandbox.
If you need to bypass TLS validation while experimenting:
writekit check --skip-tls
writekit init demo --skip-tls --ai gemini --ignore-agent-tools --script ps
(Use only for local experimentation.)
| Action | Command |
|---|---|
| Run CLI directly | python -m src.writekit_cli --help |
| Editable install | uv pip install -e . then writekit ... |
| Local uvx run (repo root) | uvx --from . writekit ... |
| Local uvx run (abs path) | uvx --from /mnt/c/GitHub/spec-writing-kit writekit ... |
| Git branch uvx | uvx --from git+URL@branch writekit ... |
| Build wheel | uv build |
Remove build artifacts / virtual env quickly:
rm -rf .venv dist build *.egg-info
| Symptom | Fix |
|---|---|
ModuleNotFoundError: typer |
Run uv pip install -e . |
| Scripts not executable (Linux) | Re-run init or chmod +x scripts/*.sh |
| Git step skipped | You passed --no-git or Git not installed |
| Wrong script type downloaded | Pass --script sh or --script ps explicitly |
| TLS errors on corporate network | Try --skip-tls (not for production) |
main