A declarative, idempotent development environment setup tool powered by CUE.
Tip
The name "tomei" comes from the Japanese word "透明" — transparent. What you write is what you get, with nothing hidden in between.
Write the desired state in CUE manifests, run tomei apply, and the result is always the same no matter how many times you run it.
No containers, no virtual filesystems, no shims. tomei sets up your real environment directly.
Rather than reinventing package managers, tomei delegates to existing tools like go install, cargo install. For tools with their own installer scripts — like mise or uv — you can define install/update/remove commands directly. tomei orchestrates; they execute.
Native aqua registry integration lets you install thousands of CLI tools by just specifying a package name and version.
CUE provides schema validation, platform-aware @tag() injection (_os, _arch, _headless), and type-safe manifest composition.
curl -fsSL https://raw.githubusercontent.com/terassyi/tomei/main/install.sh | shThe script detects your OS and architecture, downloads the binary, verifies the SHA-256 checksum, and installs it to ~/.local/bin.
# Initialize
tomei init
# Set up CUE module
tomei cue init
# Update module deps to latest (after schema/preset releases)
tomei cue update
# Write manifests, then apply
tomei plan .
tomei apply .
# Add runtime env vars to your shell
eval "$(tomei env)"Manifests are CUE files in package tomei. Run tomei cue init to create the cue.mod/ directory, which enables schema imports and preset resolution via OCI registry. For details, see:
Presets provide ready-made definitions for common runtimes and tools. Available presets:
| Import | Provides |
|---|---|
tomei.terassyi.net/presets/go |
#GoRuntime, #GoTool, #GoToolSet |
tomei.terassyi.net/presets/rust |
#RustRuntime, #CargoBinstall, #BinstallInstaller, #BinstallToolSet |
tomei.terassyi.net/presets/aqua |
#AquaTool, #AquaToolSet |
tomei.terassyi.net/presets/node |
#PnpmRuntime, #PnpmTool, #PnpmToolSet |
tomei.terassyi.net/presets/python |
#UvRuntime, #UvTool, #UvToolSet |
tomei.terassyi.net/presets/deno |
#DenoRuntime, #DenoTool, #DenoToolSet |
tomei.terassyi.net/presets/bun |
#BunRuntime, #BunTool, #BunToolSet |
tomei.terassyi.net/presets/brew |
#Homebrew, #BrewInstaller, #Formula, #FormulaSet |
Runtimes:
package tomei
import (
gopreset "tomei.terassyi.net/presets/go"
"tomei.terassyi.net/presets/rust"
)
goRuntime: gopreset.#GoRuntime & {
platform: {os: _os, arch: _arch}
spec: version: "1.26.0" // or "latest"
}
rustRuntime: rust.#RustRuntime & {
spec: version: "stable"
}Tools via ToolSet:
package tomei
import (
gopreset "tomei.terassyi.net/presets/go"
"tomei.terassyi.net/presets/aqua"
)
goTools: gopreset.#GoToolSet & {
metadata: name: "go-tools"
spec: tools: {
gopls: {package: "golang.org/x/tools/gopls", version: "latest"}
staticcheck: {package: "honnef.co/go/tools/cmd/staticcheck", version: "latest"}
}
}
cliTools: aqua.#AquaToolSet & {
metadata: name: "cli-tools"
spec: tools: {
rg: {package: "BurntSushi/ripgrep", version: "latest"}
jq: {package: "jqlang/jq", version: "latest"}
}
}CUE @tag() attributes are automatically injected by tomei apply, tomei plan, and tomei cue eval:
| Tag | Type | Example values |
|---|---|---|
@tag(os) |
string |
linux, darwin |
@tag(arch) |
string |
amd64, arm64 |
@tag(headless) |
bool |
true, false |
Declare them in a platform file:
package tomei
_os: string @tag(os)
_arch: string @tag(arch)
_headless: bool | *false @tag(headless,type=bool)Boolean platform tags (darwin, linux, amd64, arm64, headless) can be used with CUE's @if() attribute to conditionally include entire files:
@if(darwin && arm64)
package tomei
import "tomei.terassyi.net/presets/brew"
homebrew: brew.#Homebrew
brewInstaller: brew.#BrewInstallerThe file is only loaded when the current platform matches the condition. Supports &&, ||, and ! operators (e.g., @if(!headless), @if(linux || darwin)).
Use a pinned version ("1.26.0") for reproducibility, or "latest" for auto-resolution. Running tomei apply --sync re-resolves "latest" versions.
tomei cue scaffold generates a starting template:
tomei cue scaffold tool # Tool template
tomei cue scaffold toolset # ToolSet template
tomei cue scaffold runtime # Runtime templateFor raw CUE examples without presets, see examples/minimal/. For a full multi-runtime setup, see examples/real-world/.
| Command | Description |
|---|---|
tomei init |
Initialize directories and state |
tomei cue init |
Set up CUE module for manifest imports |
tomei cue update |
Update module dependencies to latest |
tomei cue scaffold |
Generate manifest templates |
tomei cue eval |
Evaluate manifests with platform tags |
tomei cue export |
Export manifests as JSON |
tomei validate |
Validate manifests and detect cycles |
tomei plan |
Preview execution plan |
tomei apply |
Install, upgrade, or remove resources |
tomei get |
List installed resources |
tomei env |
Output runtime environment variables |
tomei doctor |
Diagnose environment issues |
tomei logs |
Inspect installation logs |
tomei state diff |
Compare state before/after apply |
tomei upgrade |
Self-update to latest release |
tomei uninit |
Remove tomei directories and state |
tomei completion |
Generate shell completions |
tomei version |
Print version information |
See Usage for full flag reference.
Add to your shell profile to set up runtime environment variables:
# bash / zsh
eval "$(tomei env)"
# fish
tomei env --shell fish | sourceEnable shell completion:
# bash
source <(tomei completion bash)
# zsh
tomei completion zsh > "${fpath[1]}/_tomei"
# fish
tomei completion fish | source- Design
- Architecture
- CUE Schema Reference
- CUE Ecosystem Integration
- Module Publishing
- Cosign Verification
- Releasing
- Usage
- Examples
- aqua and aqua-registry — tomei uses the aqua registry as its primary tool metadata source. Thanks to the aqua project for maintaining a comprehensive registry of CLI tools.
This project is licensed under the MIT License. See LICENSE and NOTICE for details.