Skip to content
omnonePublic

About

Like cargo.toml but for CLI tools. Pin, sync, and verify binaries across your whole team with a single manifest and lockfile.

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

51 Commits

Folders and files

Repository files navigation

grip

MIT License Rust stable Build

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.


Common commands

# ── 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-install

What grip is for

Use 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, or protoc
  • System packages from apt or dnf that your Dockerfile currently installs
  • Libraries such as libssl-dev or pkg-config that 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.


The problem

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
  • apt and dnf packages are scattered across Dockerfiles, bootstrap scripts, and CI YAML

This is a dependency problem, and it deserves a real solution.


The 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.


Why grip?

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."


Quickstart

# 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 dockerfile
RUN 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/jq

Paste 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.


Integrating grip into a Dockerfile project

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 Dockerfile

After 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.


Day-to-day workflow

Run a tool without changing your shell PATH

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 .

Add your project's .bin/ to PATH for the current shell session

$ eval "$(grip env)"
$ jq --version
jq-1.7.1

Check that what is installed matches the lockfile

grip 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 passed

If 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

Pin unpinned tools to their installed versions

$ 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.toml

Entries not yet in grip.lock are skipped with a warning — run grip sync first, then re-run grip lock pin.

See what has newer versions available

$ 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     outdated

Run grip lock --upgrade-package kubectl then grip sync to upgrade a single tool, or grip lock --upgrade then grip sync to upgrade everything.

Remove a tool

$ grip remove jq
  ✓  removed .bin/jq
  ✓  removed 'jq' from [binaries] in grip.toml

Example 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.


CI

Recommended setup

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 tampering

grip 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.


Features

  • Byte-for-byte reproducibility — grip.lock records 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, and dnf, all declared in a single grip.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.

SBOM generation

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 file

CycloneDX 1.5 and SPDX 2.3 are both supported.

Vulnerability scanning

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 1

Add 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.


Installation

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/grip

Or 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 | sh

Clone 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/grip

Verify:

grip --version

Security

grip supports layered supply chain protections:

  • GPG signature verification — add gpg_fingerprint to any github or url entry to verify the release asset signature before installing.
  • Post-install tamper detection — grip lock verify re-hashes every .bin/ binary against grip.lock without re-downloading anything.
  • Version pin enforcement — grip sync --require-pins fails before touching the network if any entry floats to "latest".
  • Health checks — grip sync --check detects orphaned lock entries, missing SHA-256 hashes, and unpinned entries in addition to verifying installed binaries.

See SECURITY.md for the full guide.


CLI reference

For the full command reference — all flags, source types, shell integration, and CI guidance — see COMMANDS.md.


Recipes

For copy-pasteable examples covering Dockerfile import, GitHub releases, apt/dnf, pinning, and CI setup see EXAMPLES.md.


Contributing

See CONTRIBUTING.md for how to build, run the test suites, and add new adapters.


License

MIT

About

Like cargo.toml but for CLI tools. Pin, sync, and verify binaries across your whole team with a single manifest and lockfile.

Topics

Resources

Contributing

Security policy

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages