block

command module

v0.7.0 Latest Latest Go to latest Published: Aug 24, 2026 License: MIT Imports: 5 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/nao1215/block

Links

Open Source Insights

README ¶

Coverage GitHub

demo

block is a reproducible toolchain manager for blockchain development. Declare the CLIs your project builds with in block.toml; everyone and CI install the same versions from block.lock.

Documentation: https://nao1215.github.io/block/

Try it in 30 seconds

printf '[tools]\nfoundry = "1.7"\n' > block.toml
go run github.com/nao1215/block@latest lock   # block.toml -> block.lock
go run github.com/nao1215/block@latest sync   # install what block.lock pins
go run github.com/nao1215/block@latest exec forge --version

Commit both files. Everyone else runs block sync and gets the same binaries.

Foundry ships Linux and macOS builds only. On Windows, the same four lines with a tool that does:

printf '[tools]\nsolc = "0.8"\n' > block.toml
go run github.com/nao1215/block@latest lock
go run github.com/nao1215/block@latest sync
go run github.com/nao1215/block@latest exec solc --version

Which CLIs are available: Tools.

Commands


`block lock [tool...]`	resolve `block.toml` into `block.lock` — the only command that moves a pin
`block sync`	install what `block.lock` pins, or fail
`block exec <cmd>`	run a command with the locked toolchain on `PATH`
`block which <cmd>`	the executable `exec` would run, as an absolute path — never `PATH`
`block status [--json]`	what the two files and the store say, read-only
`block list [ecosystem]`	the tools block can install
`block explain <code>`	what a `BLK` error code means
`block completion <shell>`	a completion script for bash, zsh, fish or PowerShell

sync never resolves, exec never installs, and nothing updates by itself. foundry = "nightly" works too: it pins the release under the tag that moves. So does foundry = "nightly-<commit>", which names one nightly outright and never moves at all — when to use which.

block installs prebuilt artifacts that upstreams publish, and does not build tools from source. go install, cargo install, make and upstream build scripts are outside what a recipe can ask for, so adding a tool cannot add a way to run something during installation. Every resolved artifact is pinned in block.lock with its SHA-256.

That is a deliberate boundary. Not building at install time keeps a tool's dependency resolver, its build scripts and the system toolchain out of the step, which narrows the installation-time attack surface. It is worth having where CI and developer machines can reach signing keys and other credentials. It does not make an artifact safe: a digest pins what you get, not who built it. Security has the reasoning and the limits.

Install

go install github.com/nao1215/block@latest

brew install --cask nao1215/tap/block        # macOS, Linux
scoop bucket add nao1215 https://github.com/nao1215/block && scoop install nao1215/block

The releases page also has .deb, .rpm, .apk and archives. In GitHub Actions:

- uses: nao1215/setup-block@v0
  with:
    sync: "true"
- run: block exec forge test

Supported OS (unit testing with GitHub Actions)

Linux
macOS
Windows

Documentation


Getting started	from nothing to a pinned toolchain
Cookbook	recipes indexed by task
examples/	ready-made `block.toml` files
Commands	every command, in detail
Reference	file formats, the store, how versions resolve
Error codes	every `BLK` code and what to do about it
CI	GitHub Actions, GitLab, CircleCI, Docker
Security	what block does and does not guarantee while installing binaries

block-registry — where the recipes are written
setup-block — GitHub Action that installs block and caches its toolchain

Contributing

Issues and pull requests are welcome; see CONTRIBUTING.md. make test, make e2e and make lint are what CI runs. Contributions are not only about code: a GitHub Star also motivates development.

LICENSE

The block project is licensed under the terms of MIT LICENSE.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

_{CHIKAMATSU Naohiro}
💻 📖

Documentation ¶

Overview ¶

Command block locks a project's blockchain toolchain: declare tools in block.toml, pin them in block.lock, and reproduce them anywhere.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Package cmd defines the block command line: lock, sync, exec.	Package cmd defines the block command line: lock, sync, exec.
e2e
fakegh command Command fakegh serves the offline fake GitHub (internal/fakegh) for the atago end-to-end suite.	Command fakegh serves the offline fake GitHub (internal/fakegh) for the atago end-to-end suite.
faketool command Command faketool stands in for a real blockchain CLI in the end-to-end suite.	Command faketool stands in for a real blockchain CLI in the end-to-end suite.
internal
archive Package archive extracts the tar.gz and zip archives upstreams publish.	Package archive extracts the tar.gz and zip archives upstreams publish.
block Package block implements the three operations behind the CLI:	Package block implements the three operations behind the CLI:
cmdinfo Package cmdinfo carries the build-time identity of the binary.	Package cmdinfo carries the build-time identity of the binary.
diag Package diag defines block's diagnostic codes: the stable, searchable names for the refusals block reports.	Package diag defines block's diagnostic codes: the stable, searchable names for the refusals block reports.
doc Package doc renders the parts of block's documentation that are derived from the registry rather than written by hand.	Package doc renders the parts of block's documentation that are derived from the registry rather than written by hand.
fakegh Package fakegh is an offline stand-in for the GitHub API and release downloads.	Package fakegh is an offline stand-in for the GitHub API and release downloads.
fetch Package fetch downloads artifacts into a content-addressed cache and verifies their SHA-256 digests.	Package fetch downloads artifacts into a content-addressed cache and verifies their SHA-256 digests.
fserr Package fserr answers one question about an error the operating system returned: did the write fail because there was nowhere to put the bytes?	Package fserr answers one question about an error the operating system returned: did the write fail because there was nowhere to put the bytes?
github Package github is the minimal GitHub REST client block needs: list the tags of a repository and fetch one release by tag.	Package github is the minimal GitHub REST client block needs: list the tags of a repository and fetch one release by tag.
lockfile Package lockfile reads and writes block.lock: the facts block resolved from a block.toml.	Package lockfile reads and writes block.lock: the facts block resolved from a block.toml.
manifest Package manifest reads block.toml: the human-written statement of which tools a project wants and roughly which versions.	Package manifest reads block.toml: the human-written statement of which tools a project wants and roughly which versions.
platform Package platform names the operating system / CPU pairs block can install artifacts for.	Package platform names the operating system / CPU pairs block can install artifacts for.
recipe Package recipe defines how block discovers versions and artifacts of one tool from its upstream.	Package recipe defines how block discovers versions and artifacts of one tool from its upstream.
resolver Package resolver turns a recipe plus a version constraint into a concrete upstream version and its per-platform artifacts.	Package resolver turns a recipe plus a version constraint into a concrete upstream version and its per-platform artifacts.
shim Package shim makes a project's locked tools runnable by their own names.	Package shim makes a project's locked tools runnable by their own names.
snapshot Package snapshot records where block's vendored registry came from and proves that it still is what was vendored.	Package snapshot records where block's vendored registry came from and proves that it still is what was vendored.
store Package store lays out block's per-user directory: a content-addressed download cache and the extracted tool installs.	Package store lays out block's per-user directory: a content-addressed download cache and the extracted tool installs.
version Package version parses the semantic versions that upstream tools publish and the constraints a block.toml declares against them.	Package version parses the semantic versions that upstream tools publish and the constraints a block.toml declares against them.
registry Package registry holds the built-in recipes that tell block how to find a tool's releases upstream, and answers which tools exist for a blockchain system.	Package registry holds the built-in recipes that tell block how to find a tool's releases upstream, and answers which tools exist for a blockchain system.
scripts
gen-docs command Command gen-docs writes the documentation block generates rather than writes by hand: doc/tools.md from the recipes embedded in this repository, and doc/errors.md from the diagnostic-code registry.	Command gen-docs writes the documentation block generates rather than writes by hand: doc/tools.md from the recipes embedded in this repository, and doc/errors.md from the diagnostic-code registry.
registry-snapshot command Command registry-snapshot writes and checks registry/SNAPSHOT, the record of which block-registry revision block's vendored recipes came from.	Command registry-snapshot writes and checks registry/SNAPSHOT, the record of which block-registry revision block's vendored recipes came from.