Pin your first project's tools

By the end of this page a repository pins CMake in ocx.toml, locks it in ocx.lock and runs it with ocx exec. Every teammate and CI runner then gets the same binary. It assumes ocx is installed, including the shell hook that ocx self setup wires.

Pin the tools

Create a project directory and write an empty ocx.toml into it:

mkdir my-project && cd my-project
ocx init

created /home/you/my-project/ocx.toml

Add CMake. The command resolves the tag to a digest for each platform, writes ocx.lock and downloads the package:

ocx add kitware/cmake:3.31

Binding  Group    Digest
cmake    default  sha256:...

Look at the file ocx add changed:

cat ocx.toml

#:schema https://ocx.sh/schemas/project/v1.json

[tools]
cmake = "ocx.sh/kitware/cmake:3.31"

The left side is the binding name. The right side is the full package identifier, including the registry.

Run a command with the pinned tools

ocx exec reads ocx.lock and runs the command with the locked tools on PATH. The -- before the command is required:

ocx exec -- cmake --version

cmake version 3.31.12

CMake suite maintained and supported by Kitware (kitware.com/cmake).

The tool came from the lock, not from your machine. A change to the tag in ocx.toml makes the lock stale, and ocx exec then fails with exit code 65 until you run ocx lock.

Share the pin

Commit both files. The rendered tools live in .ocx/toolchain/, which carries its own .gitignore, so git status stays clean:

git add ocx.toml ocx.lock

A teammate who clones the repository downloads the locked packages with one command, then runs the tool:

ocx pull
ocx exec -- cmake --version

They get the same build you did.

Get the tools in your shell

ocx add also recorded this project’s consent stamp. Leave the directory and enter it again:

cd .. && cd my-project
cmake --version

cmake version 3.31.12

CMake suite maintained and supported by Kitware (kitware.com/cmake).

At the next prompt the locked tools are on PATH. When you leave the directory they disappear again.

Next steps

• Set up a project toolchain covers groups, updates and lifecycle commands.
• Run project tools explains ocx exec with named bindings and groups.
• Shell integration lists which shells need extra setup, such as nushell and the strict-POSIX family, and how direnv fills the gap.
• GitHub Actions installs the same pinned toolchain in CI.
• The OCX VS Code extension, also on Open VSX, brings the project toolchain into your editor. Its terminal and tasks then resolve the same locked binaries.
• Flags and exit codes are in the ocx exec reference and the project file reference.