Lock your project tools like you lock your code dependencies.
grip is a per-project dependency manager for the command-line tools and system
packages your repo needs to build, test, lint, release, or run in CI. Declare
jq, kubectl, shellcheck, ripgrep, libssl-dev, or any other required
tool once, then install the exact same versions everywhere.
It works across the sources projects already use — GitHub Releases, direct
download URLs, apt, dnf, and more — and records every resolved artifact in
grip.lock with its version, URL, and SHA-256.
Declare your tools in grip.toml. Run grip sync. Every developer, CI job,
and Docker build gets the same bytes, with no setup wiki, no "latest" drift,
and no machine-specific guessing.
# ── Setup ──────────────────────────────────────────────────────────────────────
grip init # create grip.toml and .gitignore entry
grip suggest # discover tools referenced but not declared
grip add jq rg fd # add tools to grip.toml and install them
grip add BurntSushi/ripgrep # GitHub shorthand (owner/repo)
grip add jq@1.7.1 --repo jqlang/jq \
--source github # pin a specific version
grip remove jq # remove a tool from toml, lock, and .bin/
# ── Install & run ──────────────────────────────────────────────────────────────
grip sync # install all missing tools
grip sync --locked # CI: fail if grip.lock would change
grip sync --frozen # install exactly what is in grip.lock
grip sync --check # verify .bin/ matches lock; no install
grip run jq '.name' package.json # run a tool with .bin/ on PATH
eval "$(grip env)" # add .bin/ to current shell session
# ── Lock management ────────────────────────────────────────────────────────────
grip tree # list installed tools with versions
grip lock # resolve versions → write grip.lock
grip lock --check # assert lock is up to date (CI)
grip lock --upgrade # re-resolve all to latest → update lock
grip lock --upgrade-package kubectl # re-resolve one tool → update lock
grip lock --upgrade --dry-run # preview what would change
grip lock pin # write installed versions into grip.toml
grip lock verify # re-hash .bin/ vs lock (tamper check)
# ── Export & security ──────────────────────────────────────────────────────────
grip export --format dockerfile # Dockerfile RUN lines from grip.lock
grip export --format cyclonedx -o s.json # CycloneDX SBOM to file
grip audit # CVE scan via OSV database
# ── CI (in order) ──────────────────────────────────────────────────────────────
grip suggest --check # fail if any tool is undeclared
grip lock --check # fail if lockfile is stale
grip sync --locked --require-pins # install; fail if lock or pins would change
grip lock verify # detect tampering post-installUse grip when your project depends on tools that usually live outside your language package manager:
- CLI utilities used by scripts, Makefiles, hooks, or CI workflows
- Release and infrastructure tools such as
kubectl,terraform, orprotoc - System packages from
aptordnfthat your Dockerfile currently installs - Libraries such as
libssl-devorpkg-configthat native builds need
Instead of documenting "please install these first", commit grip.toml and
grip.lock. New machines and CI runners can reproduce the toolchain with one
command.
Every project depends on CLI tools but there is no standard way to manage them:
- README says "install
jq >= 1.6" — everyone installs something slightly different - CI pulls the latest release — until a breaking change breaks the build
- Dockerfiles have versions copy-pasted from a wiki that nobody updates
- A new teammate spends an afternoon installing things manually before they can run the project
aptanddnfpackages are scattered across Dockerfiles, bootstrap scripts, and CI YAML
This is a dependency problem, and it deserves a real solution.
Three pieces, one workflow:
- A manifest (
grip.toml) — declare which tools the project needs and where to get them - A lockfile (
grip.lock) — records the exact version, download URL, and SHA-256 of every tool - One command (
grip sync) — installs everything reproducibly from the lockfile
Commit both files. Every developer runs grip sync after pulling. CI runs
grip sync --locked. Dockerfiles can be generated from the lockfile. That is
the entire workflow.
Tools like asdf, mise, and Homebrew are version managers for your machine — they answer "what version do I have installed?" grip answers a different question: "what does this project require?"
| asdf / mise | Homebrew | grip | |
|---|---|---|---|
| Scope | machine-wide | machine-wide | per-project |
| Lockfile checked into repo | no | no | yes |
| Works without root | yes | no | yes |
| Mixed sources in one file | no | no | yes |
| SHA-256 verified install | no | no | yes |
The lockfile is the difference. Commit grip.lock alongside grip.toml and there's nothing to configure per-machine — every install gets identical bytes, not "the latest 1.x" or "whatever was on the wiki."
# 1. Set up grip in your project (run once, from the project root)
$ grip init
Created grip.toml
Created .gitignore with .bin/
# 2. Discover tools your project already uses but hasn't declared
$ grip suggest
jq referenced in .github/workflows/release.yml → grip add jq
shellcheck referenced in Makefile → grip add shellcheck
# 3. Add a tool — grip downloads and installs it immediately
$ grip add jq@1.7.1 --repo jqlang/jq --source github
Added 'jq' to grip.toml
1 installed (1.2s)
# 4. See what is installed
$ grip tree
Installed binaries (from grip.lock)
NAME VERSION SOURCE INSTALLED AT
──────────────────────────────────────────────
jq 1.7.1 github 2025-03-14 09:41
# 5. Commit the manifest and lockfile so everyone gets the same thing
$ git add grip.toml grip.lock
$ git commit -m "add dev tools"Generate Dockerfile instructions from the lockfile — no grip required in the image:
$ grip export --format dockerfileRUN curl -fsSL -o /usr/local/bin/jq \
"https://github.com/jqlang/jq/releases/download/jq-1.7.1/jq-linux-amd64" \
&& chmod +x /usr/local/bin/jqPaste the output into your Dockerfile. The URL and version come straight from grip.lock, so they stay in sync as you update tools.
On a teammate's machine — after git pull, a single command installs everything:
$ grip sync --locked
All up to date (1 skipped, 0.0s)--locked means the build fails if grip.lock would change — no silent version drift in CI.
If your project already has a Dockerfile with RUN apt-get install or RUN dnf install lines,
grip init can import those packages automatically:
# 1. Run grip init in the project root — auto-detects Dockerfile
$ grip init
Created grip.toml
Added .bin/ to .gitignore
Found Dockerfile — 14 apt packages.
Verifying against curated tools and host package manager…
Verified — will import (11):
binary jq 1.6-2.1 via apt (curated)
binary ripgrep via apt (curated) → cmd `rg`
library libssl-dev 1.1.1n-0+deb11u5 via apt
library pkg-config via apt (curated)
library build-essential via apt (curated)
...
Skipped (not verified) — review manually (3):
some-internal-tool not found in curated list or host package manager
Import the 11 verified entries into grip.toml? [Y/n]# 2. Generate grip.lock from inside the same Docker base image
$ docker run --rm -v "$PWD":/work -w /work debian:bookworm \
sh -c 'apt-get update && apt-get install -y curl ca-certificates && \
curl -fsSL https://github.com/omnone/grip/releases/latest/download/grip-x86_64-linux \
-o /usr/local/bin/grip && chmod +x /usr/local/bin/grip && \
grip sync --locked'
# 3. Replace the apt-get install block in your Dockerfile
$ grip export --format dockerfile
# 4. Commit
$ git add grip.toml grip.lock DockerfileAfter this, every developer and CI run gets the same packages via grip sync.
See EXAMPLES.md for the full walkthrough including multi-Dockerfile projects,
--offline mode, and the CI setup.
Use grip run for one-off invocations. Pass -- to avoid ambiguity between grip flags
and tool flags:
$ grip run jq --version
jq-1.7.1
$ grip run -- fd --hidden .$ eval "$(grip env)"
$ jq --version
jq-1.7.1grip sync --check verifies installed binaries against the lockfile and reports consistency
issues — orphaned lock entries, unpinned versions, and missing SHA-256 hashes — without
installing or modifying anything.
$ grip sync --check
Checking installed binaries…
✓ jq
All 1 checks passedIf any consistency issues are found, they appear in a separate section and the command exits non-zero:
$ grip sync --check
Checking installed binaries…
✓ jq
Consistency issues
⚠ binary 'kubectl' (github) has no version pin — run `grip lock pin` to fix
1 check passed, 1 consistency issue$ grip lock pin # write exact versions from grip.lock into grip.toml
$ grip lock pin --dry-run # preview what would be pinned without modifying grip.tomlEntries not yet in grip.lock are skipped with a warning — run grip sync first, then
re-run grip lock pin.
$ grip lock --upgrade --dry-run
BINARY INSTALLED LATEST STATUS
───────────────────────────────────────
jq 1.7.1 1.7.1 up to date
kubectl 1.30.2 1.31.0 outdated
terraform 1.6.6 1.8.1 outdatedRun grip lock --upgrade-package kubectl then grip sync to upgrade a single tool, or
grip lock --upgrade then grip sync to upgrade everything.
$ grip remove jq
✓ removed .bin/jq
✓ removed 'jq' from [binaries] in grip.toml# Pin an exact version from GitHub Releases
[binaries.jq]
source = "github"
repo = "jqlang/jq"
version = "1.7.1"
# Use a semver range — grip resolves to the highest matching release
# and pins the resolved version in grip.lock
[binaries.kubectl]
source = "github"
repo = "kubernetes/kubectl"
version = "^1.30"
# Install from the system package manager (apt or dnf)
[binaries.ripgrep]
source = "apt"
package = "ripgrep"
binary = "rg" # the on-PATH command differs from the package name
# Install from a direct URL (SHA-256 is recorded in grip.lock)
[binaries.protoc]
source = "url"
url = "https://github.com/protocolbuffers/protobuf/releases/download/v26.1/protoc-26.1-linux-x86_64.zip"
binary = "bin/protoc"
# Declare a system library (no binary symlink, just ensures the package is present)
[libraries.libssl-dev]
source = "apt"
package = "libssl-dev"You never edit grip.lock by hand — grip maintains it automatically.
grip suggest --check # fail if any tool is used but not declared
grip lock --check # fail if grip.lock is not up-to-date
grip sync --locked --require-pins # install; fail if lock would change or any version floats
grip lock verify # re-hash every .bin/ binary; catch tamperinggrip suggest --check fails the job if any tool referenced in scripts or CI YAML is not
declared in grip.toml. grip lock --check asserts the lockfile is current without
modifying it. grip sync --locked enforces the lockfile exactly — the job fails if
grip.lock would need to change. grip lock verify re-hashes every binary in .bin/
against the recorded SHA-256 without re-downloading, catching tampering between sync and
execution.
For generating lock-accurate Dockerfile instructions, see Quickstart.
- Byte-for-byte reproducibility —
grip.lockrecords the exact version, download URL, and SHA-256 of every installed binary. - No global pollution — tools land in
.bin/at the project root; nothing touches system directories. - Mixed sources — four source types are currently supported:
github,url,apt, anddnf, all declared in a singlegrip.toml. - Fast installs — a local download cache avoids re-fetching; multiple tools install concurrently.
- Semver ranges —
version = "^1.30"resolves to the highest matching release and locks the result. - Supply chain protection — optional GPG verification, tamper detection, and floating-version enforcement. See SECURITY.md.
grip export can emit a Software Bill of Materials directly from grip.lock — no network
access needed:
$ grip export --format cyclonedx > sbom.json
$ grip export --format spdx > sbom.spdx.json
$ grip export --format cyclonedx -o sbom.json # write to fileCycloneDX 1.5 and SPDX 2.3 are both supported.
grip audit cross-references every installed tool against the OSV database and exits non-zero on findings:
$ grip audit
Checking 3 binaries against OSV…
jq 1.7.1 ✓ no known vulnerabilities
kubectl 1.30.2 ✓ no known vulnerabilities
terraform 1.6.6 ✗ 1 vulnerability
1 vulnerability found — exit code 1Add grip audit to CI to block deploys when new CVEs are published against your declared
tools. Run grip lock --upgrade-package terraform then grip sync to upgrade a vulnerable
tool.
grip runs on Linux and macOS. Windows is not currently supported.
curl -fsSL https://github.com/omnone/grip/releases/latest/download/grip-$(uname -m)-linux -o ~/.local/bin/grip && chmod +x ~/.local/bin/gripOr build from source with the Rust stable toolchain. Install Rust if you don't have it:
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | shClone and install:
git clone https://github.com/omnone/grip.git
cd grip
cargo install --path . # installs grip into ~/.cargo/bin (already on your PATH)Or build a release binary and place it wherever you like:
cargo build --release
sudo cp target/release/grip /usr/local/bin/gripVerify:
grip --versiongrip supports layered supply chain protections:
- GPG signature verification — add
gpg_fingerprintto anygithuborurlentry to verify the release asset signature before installing. - Post-install tamper detection —
grip lock verifyre-hashes every.bin/binary againstgrip.lockwithout re-downloading anything. - Version pin enforcement —
grip sync --require-pinsfails before touching the network if any entry floats to "latest". - Health checks —
grip sync --checkdetects orphaned lock entries, missing SHA-256 hashes, and unpinned entries in addition to verifying installed binaries.
See SECURITY.md for the full guide.
For the full command reference — all flags, source types, shell integration, and CI guidance — see COMMANDS.md.
For copy-pasteable examples covering Dockerfile import, GitHub releases, apt/dnf, pinning, and CI setup see EXAMPLES.md.
See CONTRIBUTING.md for how to build, run the test suites, and add new adapters.