add-tool
Decide where a new tool slots into the chezmoi bootstrap and README. Use when adding a CLI/binary to the host bootstrap so it lands in the right install pass and the right README block. Routes auth-re
SKILL.md.claude/skills/add-tool/SKILL.md
GitHubAdd a tool to bootstrap
First check the tool belongs on the host, then make two decisions independently.
Libraries with no console script
uv tool install needs an executable, so a PyPI library takes one of
two shapes:
- An installed tool imports it (plugins, optional backends): add it
as a pinned
--withextra on that tool, asbeetscarriespyacoustid. - Otherwise, keep it off the host. The caller runs
uv run --with <pkg>==<version> <script>and owns the pin. Stop here: no bootstrap change, no README line.
Install a CLI front-end that wraps the library only when its command is itself wanted.
Auth axis
Does the tool need interactive auth (login, browser flow, API token) to do real work?
- Yes (gh, claude, gcx, readwise, tailscale): list in README "Interactive logins" with a config-path comment so a fresh-host bootstrap surfaces where state lands. No PATH-check line — running the login command itself proves reachability. Auth state is runtime, never managed by chezmoi.
- No (zellij, lazygit, act, gh-poi): list in README "PATH check" line.
Install mechanism
All passes live under .chezmoiscripts/.
Pick the canonical installer for the ecosystem:
| Source | Where | Pattern |
|---|---|---|
| Debian package | .chezmoidata/packages.yaml |
append to packages.apt |
| Pinned binary release | .chezmoiexternal.toml |
external entry below |
| npm package | run_before_03 |
npm install -g, command -v |
| Cargo crate | run_before_09 |
cargo install, command -v |
gh extension |
run_before_05 |
gh extension install --pin |
| PyPI package | run_after_install-via-externals |
mirror the beets block |
A release binary that needs more than a download (signature check,
source build) gets a script/install/<tool> script, called from
run_before_02 instead; mirror script/install/signal-cli.
Auth and install axes are independent: gcx is auth-required and
a chezmoi external; gh-poi is fire-and-forget and uses
gh extension install.
Pin the version
Annotate each *_VERSION pin on the line directly above it:
| Source | Annotation |
|---|---|
| Script-installed tool | # renovate: datasource=github-releases depName=<owner>/<tool> |
| PyPI package | # renovate: datasource=pypi depName=<pkg>, one per --with extra too |
An external needs no annotation: its version lives in the download URL.
External entry
Add an entry to .chezmoiexternal.toml, mirroring vale or lazygit.
Write the literal release URL, version included wherever the asset name
repeats it:
[".local/bin/<tool>"]
type = "archive-file"
url = "https://github.com/<owner>/<tool>/releases/download/vX.Y.Z/<tool>_X.Y.Z_<arch>.tar.gz"
path = "<tool>"
executable = true
Renovate bumps every copy of the version in the URL. Use
type = "file" for a raw binary asset. A release asset carries no
checksum (ADR 0008); a GitHub source-archive tarball
(archive/refs/tags/…) pins checksum.sha256.
A pass that runs the new binary is run_after_, since externals deploy
during apply.
Shell completion
When the tool prints a bash completion script, add
dot_local/share/bash-completion/completions/<command> holding one
line that evals it, mirroring just. bash-completion sources the file
on the first Tab, so the script always matches the installed version.
Procedure
For a library with no console script, settle its shape first; stop if it stays off the host.
Identify the auth axis and install mechanism.
Wire the installer into the right
.chezmoiscripts/pass, or add the external entry.Update README:
- Auth-required → add to "Interactive logins" with config-path comment
- Fire-and-forget → add to "PATH check" line
Annotate every pin per Pin the version.
Add a Shell completion file if the tool generates one.
Run sensors before claiming done:
pre-commit run --all-files bats --recursive dot_local dot_claude script script/checks/chezmoi-apply