From tsuku-user
Use when helping someone manage tools with tsuku -- installing, configuring .tsuku.toml project files, setting up shell integration, or debugging PATH and update issues.
How this skill is triggered — by the user, by Claude, or both
Slash command
/tsuku-user:tsuku-userThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
A `.tsuku.toml` file at your project root declares which tools the project needs. When a collaborator clones the repo and runs `tsuku install -y`, they get the same toolchain.
A .tsuku.toml file at your project root declares which tools the project needs. When a collaborator clones the repo and runs tsuku install -y, they get the same toolchain.
tsuku init
This writes a starter .tsuku.toml in the current directory. Use --force to overwrite an existing one.
[tools]
node = "20"
python = "3.12.0"
jq = "latest"
go = { version = "1.23" }
Each key is a tool name. The value controls how tightly the version is pinned:
| Pin Level | Syntax | Example | Auto-Update Behavior |
|---|---|---|---|
| Latest | "" or "latest" | jq = "latest" | Updates to any new version |
| Major | "N" | node = "20" | Updates within 20.x.y |
| Minor | "N.M" | python = "3.12" | Updates within 3.12.z |
| Exact | "N.M.P" | go = "1.23.4" | No auto-updates |
| Channel | "@name" | rust = "@nightly" | Provider-specific |
# Install all tools from .tsuku.toml (prompts for confirmation)
tsuku install
# Skip confirmation
tsuku install -y
# Preview without installing
tsuku install --dry-run
tsuku finds .tsuku.toml by walking up from the current directory, stopping at $HOME (or directories listed in TSUKU_CEILING_PATHS).
| Command | Description | Common Flags |
|---|---|---|
tsuku install <tool> | Install a tool (supports @version suffix) | --force, --sandbox, --dry-run |
tsuku install | Install all tools from .tsuku.toml | --yes, --dry-run, --fresh |
tsuku remove <tool> | Remove a tool (or specific version with @version) | --force |
tsuku update <tool> | Update within pin boundaries | --dry-run |
tsuku update --all | Update all tools (skips exact-pinned) | --dry-run |
tsuku list | List installed tools | --json, --all |
tsuku outdated | Show tools with available updates | --json |
| Command | Description | Common Flags |
|---|---|---|
tsuku search <query> | Search recipes by name or description | --json |
tsuku recipes | List all available recipes | --local, --json |
tsuku info <tool> | Tool details (homepage, deps, status) | --json |
tsuku versions <tool> | Available versions for a tool | --refresh, --json |
tsuku which <command> | Which recipe provides a command |
| Command | Description | Common Flags |
|---|---|---|
tsuku run <tool> [args] | Install if missing, then execute | --mode suggest/confirm/auto |
tsuku verify <tool> | Check binary integrity and deps | --system-deps, --integrity |
tsuku doctor | Environment health check | --rebuild-cache |
tsuku cache clear | Clear download and version caches | --downloads, --versions |
tsuku update-registry | Refresh recipe cache and binary index | --force |
All commands accept --verbose (-v), --quiet (-q), and --debug for log control.
tsuku needs two directories on your PATH: $TSUKU_HOME/bin (wrapper scripts) and $TSUKU_HOME/tools/current (active tool symlinks). The shellenv command sets this up.
Add one line to your shell profile:
bash (~/.bashrc):
eval "$(tsuku shellenv)"
zsh (~/.zshrc):
eval "$(tsuku shellenv)"
fish (~/.config/fish/config.fish):
tsuku shellenv | source
tsuku shellenv prints the PATH exports and sources any tool-specific shell init scripts from $TSUKU_HOME/share/shell.d/.
tsuku doctor
Doctor checks that $TSUKU_HOME exists, both directories are on PATH, the state file is accessible, shell init caches are current, and no orphaned staging directories remain. If something's wrong, it tells you what to fix.
Use --rebuild-cache to force a rebuild of shell init caches.
When a command fails, the exit code tells you what went wrong:
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | General error |
| 2 | Invalid arguments or usage |
| 3 | Recipe not found |
| 4 | Version not found |
| 5 | Network error |
| 6 | Installation failed (or all tools failed in batch install) |
| 7 | Verification failed |
| 8 | Dependency resolution failed |
| 15 | Partial failure (some tools failed in batch install) |
| 130 | Cancelled (Ctrl+C) |
Tool won't run after install? Check that shell integration is set up:
tsuku doctor
Suspect a corrupted install? Verify the binary:
tsuku verify <tool>
This checks that the binary exists, its version matches the recorded state, and runs the tool's verification command if one is defined.
Registry out of date? Refresh it:
tsuku update-registry
By default, tsuku checks for updates in the background and applies them within your pin boundaries.
updates.auto_apply is enabled, updates within pin boundaries are installed automatically.Exact-pinned tools (go = "1.23.4") are never auto-updated.
| Setting | Effect |
|---|---|
TSUKU_NO_UPDATE_CHECK=1 | Disable all background checks |
TSUKU_AUTO_UPDATE=1 | Force auto-apply even in CI |
CI=true | Suppresses auto-apply (unless overridden) |
TSUKU_NO_SELF_UPDATE=1 | Disable tsuku self-updates |
Or configure via config.toml (see below).
# See what's outdated
tsuku outdated
# Update one tool
tsuku update node
# Update everything
tsuku update --all
# Preview changes
tsuku update --all --dry-run
User settings live in $TSUKU_HOME/config.toml. View and modify them with:
# Show all settings
tsuku config
# Get a specific value
tsuku config get telemetry
# Set a value
tsuku config set telemetry false
Telemetry: Opt out of anonymous usage stats with tsuku config set telemetry false, or set environment variables: TSUKU_NO_TELEMETRY=1 or TSUKU_TELEMETRY=0.
Updates ([updates] section):
enabled -- toggle background update checks (default: true)auto_apply -- auto-install updates within pin boundaries (default: true)check_interval -- minimum time between checks, e.g. "12h" (default: "24h")self_update -- check for tsuku self-updates (default: true)version_retention -- how long to keep old versions, e.g. "168h" (default: 7 days)Registries: Add third-party recipe sources:
tsuku config set registries.myorg/recipes.url https://github.com/myorg/recipes
Custom home directory: Set TSUKU_HOME in your shell profile to move tsuku's data out of ~/.tsuku:
export TSUKU_HOME="$HOME/.local/share/tsuku"
Secrets: Store API keys (for LLM-powered recipe generation):
echo "sk-..." | tsuku config set secrets.anthropic_api_key
Secrets can also be provided via TSUKU_SECRET_<NAME> environment variables, which take precedence over config.toml.
Configures tsk Docker container images by detecting project stacks (rust/go/node/python/java/lua), migrating deprecated Dockerfiles to tsk.toml layers, running dry-run builds, and troubleshooting issues.
Provides mise.toml patterns for tool version management, tasks, env vars, presets, and hk git hooks setup. Useful for dev environments, project onboarding, and pre-commit migration.
Manages development tool versions with Mise: installs specific/latest versions, pins in mise.toml, sets project/global/aliases for Node, Python, Rust, Go, Terraform, Deno, and more.
npx claudepluginhub tsukumogami/tsuku --plugin tsuku-user