toolbelt · v2.3.2 · 2026-09-09 · sha256 c1fdf69d3437b83f
toolbelt v2.3.2A
Immutable. This exact content is served forever at /api/v1/blob/c1fdf69d3437b83f.
---
name: toolbelt
description: Choose haru's preferred CLI tools for terminal search, inspection, HTTP, structured data, and benchmarking when tool selection or usage guidance is needed.
metadata:
author: haru
version: 2.3.2
---
# Toolbelt Skill
Prefer these tools for interactive terminal work. Check availability on the current machine; repository tooling and the host agent's editing rules take precedence over these defaults.
## Table of Contents
- [Resolve uncertainty](#resolve-uncertainty)
- [Substitution table (always-on)](#substitution-table-always-on)
- [Tooling discipline (carried from global defaults)](#tooling-discipline-carried-from-global-defaults)
- [Runtimes & package managers](#runtimes--package-managers)
- [Search & navigate](#search--navigate)
- [Edit text](#edit-text)
- [HTTP / API debugging](#http--api-debugging)
- [GitHub and GitLab](#github-and-gitlab)
- [Data & SQL](#data--sql)
- [Debug & inspect](#debug--inspect)
- [Benchmark](#benchmark)
- [Domain & infra tools (know these exist)](#domain--infra-tools-know-these-exist)
- [When NOT to substitute](#when-not-to-substitute)
Rule of thumb: classic tools for piping inside scripts that must be portable; modern tools for interactive/agent work where clarity and ergonomics win.
## Resolve uncertainty
Use `command -v`, the installed tool's `--help`, and repository configuration to resolve missing tools or unfamiliar flags. Continue with a supported fallback when it preserves the requested result. Ask when the remaining uncertainty changes scope, risks user data, or requires authority the user has not supplied. A recipe here is not permission to install tools, load-test a service, or mutate remote state.
## Substitution table (always-on)
Reach for the right-hand tool by default; fall back to the classic only when the modern one is absent.
| Instead of | Use | For |
| -------------------- | --------------------------------------- | ------------------------------- |
| `ls` / `cat` / `du` | `eza` / `bat` / `dust` | listing, viewing, disk usage |
| `grep` / `find` | `ripgrep` (`rg`) / `fd` | text/file search |
| `grep` for code structure | `ast-grep` (`sg`) | AST-aware search & rewrite |
| `sed` (substitute) | `sd` | find & replace |
| `git diff` | `delta` — already wired as the pager | `diff`/`log`/`show`/`blame` |
| a noisy reflow diff | `difftastic` (`difft`) | AST diff, opt-in |
| `ps` / `dig` / `xxd` | `procs` / `doggo` / `hexyl` | processes, DNS, hex |
| `curl` (API testing) | `xh` | HTTP requests |
| `jq` for non-JSON | `dasel` | YAML/TOML/XML/CSV query+convert |
| `wc -l` (code count) | `tokei` | code statistics (LOC) |
| ad-hoc regex design | `grex` | generate regular expressions |
| spell-check source | `typos` | typo linting in code + docs |
| ad-hoc SQL | `duckdb`; `psql`/`sqlx-cli` per project | data + migrations |
| benchmarking | `hyperfine` (CLI), `oha` (HTTP) | perf checks |
| `python` / `pip` / `pipx` | `uv` / `uvx` | Python runtime, deps, tools |
| `node` / `npm` / `npx` | `bun` / `bunx` | JS/TS runtime, deps, tools |
## Tooling discipline (carried from global defaults)
Use these defaults when the project does not specify its own tooling:
- **Mise for project tools** — pin tools and runtimes in `.mise.toml`, and run them with `mise exec -- <tool>`. Nix/Home Manager supplies the global machine environment. Honor an existing project's devShell until its toolchain is deliberately migrated.
- **`make` is the task runner** — use the repository's own targets; run `make check` before commits and `make validate` before PRs. Verify actual hook configuration before claiming these gates run automatically.
- **JSON → `jq`** — always `jq` for JSON processing; never `python3 -c` or inline Python. Reach for `dasel` the moment the format isn't JSON.
## Runtimes & package managers
Use the project's declared runtime and lockfile. For ad-hoc work, prefer `uv` and `bun` when compatible.
- **`uv`** — Python runtime + dependency + project manager (replaces `python`/`pip`/`venv`/`pipx`/`poetry`):
- `uv run script.py` (auto-resolves deps), `uv run pytest` (run a tool in the project env)
- `uv add httpx` / `uv remove httpx` (manage `pyproject.toml`), `uv sync` (install lockfile)
- `uv venv` (create env), `uv pip install -r req.txt` (pip-compatible shim)
- **`uvx`** — run a Python CLI tool one-off without installing: `uvx ruff check`, `uvx ruff@0.6 format`.
- **`bun`** — JS/TS runtime + package manager + bundler (replaces `node`/`npm`/`npx`/`yarn`/`pnpm`):
- `bun run script.ts` (runs TS directly, no compile step), `bun test`
- `bun install` (fast install), `bun add zod` / `bun remove zod`
- **`bunx`** — execute a package, downloading it if needed: `bunx prettier --check config.json`, `bunx tsx file.ts`.
Caveats: preserve the project's package manager, interpreter, and CI contract; changing runners can change compatibility or lockfiles. For one-off commands, inspect the installed version's help before using version-sensitive flags.
## Search & navigate
| Task | Tool | Idiom |
| ---------- | ---------------- | ------------------------------------------------------------- |
| Find text | `ripgrep` (`rg`) | `rg -n "pattern"`, `rg -t rust foo`, `rg -l pat` (files only) |
| Find files | `fd` | `fd -e nix`, `fd -t f name`, `fd -H` (include hidden) |
| List dir | `eza` | `eza -la --git`, `eza --tree --level=2` |
| View file | `bat` | `bat file`, `bat -p` (plain, no decorations for piping) |
| Disk usage | `dust` | `dust -d 2` (depth 2) |
| Jump dirs | `zoxide` | `z proj` after visiting once |
Prefer `rg`/`fd` over `grep -r`/`find` — faster, respects `.gitignore`, sane defaults. When piping `bat` output, add `-p` to strip line numbers/borders.
- **`ast-grep` (`sg`)** — structural, syntax-aware code search & rewrite (matches by AST, not regex — immune to formatting/whitespace):
- `sg run -p 'console.log($A)' -l ts` (find every `console.log(...)` call, any argument)
- `sg run -p 'foo($$$ARGS)' --rewrite 'bar($$$ARGS)' -l py -U` (rename a call, preserving all args; `-U` applies in place)
- Reach for `sg` over `rg` the moment the pattern is about code *shape* (a call, an import, a JSX element) rather than literal text — no brittle regex, no false hits inside strings/comments.
## Edit text
- **`sd`** — find & replace, literal-friendly, real regex (no `sed` escaping pain):
- `sd 'foo' 'bar' file.txt` (in-place, no `-i` needed)
- `sd -p 'foo' 'bar' file.txt` (preview diff, don't write)
- `sd '(\w+)@(\w+)' '$2.$1' file` (capture groups with `$1`)
- Reach for `sed` only for stream edits in portable scripts.
- For *code-structure* rewrites (rename a call, swap an API) use `ast-grep --rewrite` instead — it edits by AST, not text, so formatting and string/comment matches can't trip it up.
## HTTP / API debugging
- **`xh`** — httpie-style client, faster than `curl` for hand-driven requests:
- `xh get https://api.example.com/users` (auto-pretty JSON)
- `xh post api.local/items name=example` (JSON body from `k=v`)
- `xh -f post url field=val` (form), `xh --headers get url` (headers only)
- `xh get url Authorization:"Bearer $TOK"` (header with `:`)
- Use `curl` in scripts / when exact wire control or `--resolve` is needed.
- **`oha`** — load testing: `oha -n 1000 -c 50 https://api.local/health`.
## GitHub and GitLab
- **`gh`** — GitHub-native repository, PR, release, and workflow operations:
- `gh repo view OWNER/REPO --json nameWithOwner,defaultBranchRef`
- `gh api repos/OWNER/REPO/releases/tags/v1.2.3 --jq '{name,body,html_url}'`
- `gh pr create --fill`, `gh pr view`, `gh run view`
- Prefer `gh api` over raw HTTP for GitHub metadata; use `--jq` to keep responses focused.
- **`glab`** — GitLab-native equivalent for projects, merge requests, releases, and pipelines:
- `glab mr create --fill`, `glab mr view`, `glab pipeline view`
Use the provider-native CLI when the task targets GitHub or GitLab state. Keep `xh` for generic HTTP APIs and `curl` for scripts requiring exact wire control.
## Data & SQL
- **`dasel`** — one tool to query/convert JSON/YAML/TOML/XML/CSV:
- `dasel -f config.yaml '.services.web.port'`
- `dasel -f data.json -r json -w yaml` (convert JSON→YAML)
- `dasel put -f config.yaml -v 8080 '.services.web.port'` (edit YAML/TOML/etc. in place)
- Use `jq` for pure-JSON pipelines (it's still the default for JSON); reach for `dasel` the moment the format isn't JSON. `dasel` handles YAML query *and* edit — it's the one tool for non-JSON structured data here.
- **`tokei`** — count lines of code quickly:
- `tokei .` (recursive code statistics by language)
- **`duckdb`** — fast analytical SQL over files, no server:
- `duckdb -c "select * from 'data.csv' limit 5"`
- `duckdb -c "select count(*) from read_parquet('*.parquet')"`
- **`miller`** (`mlr`) — CSV/TSV/JSON record processing:
- `mlr --csv cut -f a,b then sort -nr b data.csv`
- **`psql`** (from `postgresql`) — Postgres client. Not installed globally: it arrives through a project's `.mise.toml` (`mise exec -- psql`) or `, psql` for a one-off, so check before assuming it is on `PATH`.
- `psql "$DATABASE_URL" -c '\dt'`, `psql -h host -U user db`
- **`sqlx-cli`** — Rust SQL toolkit / migrations:
- `sqlx database create`, `sqlx migrate add <name>`, `sqlx migrate run`
- `sqlx migrate revert`, `cargo sqlx prepare` (offline query cache)
## Debug & inspect
- **`procs`** — modern `ps`:
- `procs` (all), `procs nginx` (filter by name), `procs --tree`
- `procs --sortd cpu` (sort by CPU desc), shows ports/TTY/user.
- **`doggo`** — modern `dig` for DNS debugging:
- `doggo example.com`, `doggo MX example.com`
- `doggo example.com @1.1.1.1` (specific resolver), `--json` for parsing.
- **`hexyl`** — colored hex viewer:
- `hexyl file.bin`, `hexyl -n 64 file` (first 64 bytes), inspect encodings/headers.
- **`tailspin`** (`tspin`) — auto-highlight logs: `tspin app.log` or `cmd | tspin`.
- **`btop`** — interactive system monitor.
- **`grex`** — generate regular expressions from user-provided test cases:
- `grex a b c` (returns `^[a-c]$`)
- `grex -d -w -p email@example.com` (generate with digits, words, non-space)
- **`typos`** — fast source-code spell checker (skips code identifiers sensibly):
- `typos` (check the tree), `typos -w` (auto-fix), `typos path/to/file`
- Good as a pre-commit gate and before shipping docs; low false-positive rate.
- **`delta`** — the git pager, wired in by `programs.delta`. `git diff`/`log`/`show`/`blame` render side-by-side with line numbers and `n`/`N` to jump hunks. Use `git --no-pager diff` for raw unified text to parse, or in a narrow terminal.
- **`difftastic` (`difft`)** — the opt-in structural diff: compares ASTs, so reflow is not a change. `delta` highlights a line diff; `difft` changes what counts as a difference.
- `difft old.rs new.rs` (standalone), or for one command: `GIT_EXTERNAL_DIFF=difft git diff`
- Reach for it only when a plain diff is noisy because indentation or wrapping moved but the code didn't.
Terminal multiplexing: `tmux`.
## Benchmark
- **`hyperfine`** — CLI command benchmarking with stats:
- `hyperfine 'rg foo' 'grep -r foo .'` (compare), `--warmup 3`.
- **`oha`** — HTTP load (see above).
## Domain & infra tools (know these exist)
Candidates for specialized work. Availability varies by machine; check the executable and the project's own targets before choosing one.
| Domain | Tools | Reach for it when |
| --- | --- | --- |
| **Nix workflow** | `nh` (ergonomic nix/home-manager wrapper), `nom` (`nix-output-monitor`), `nix-tree` (closure explorer), `nix-locate` (which package owns a binary), `comma` (invoked as a lone `,` — runs a binary without installing it) | rebuilding a config, watching a build, asking why something is in the closure, finding or borrowing a missing tool |
| **Git extras** | `git-cliff` (changelog from conventional commits), `gh`, `git-lfs` | generating a release changelog, driving GitHub, large files |
| **Kubernetes** | `k9s` (TUI), `kubectl`, `stern` (multi-pod log tail) | inspecting/driving a cluster, tailing pod logs |
| **Cloud & sync** | `rclone` | syncing to/from cloud/object storage |
| **Containers (Linux)** | `podman`, `buildah`, `skopeo` | building/running/inspecting OCI images (rootless, daemonless) |
| **Secrets** | `sops`, `age` | encrypting/decrypting secrets in the repo |
| **Watch & run** | `watchexec` | re-run a command on file changes (tests, builds) |
| **Lint & format** | `shellcheck`, `shfmt`, `yamlfmt`, `prettier`, `markdownlint-cli2`, `typos`, `pre-commit` | linting/formatting shell, YAML, JS/TS, Markdown; spell-check; hook setup |
| **Lang tooling** | `golangci-lint`, `ruff`/`ty` (Python), `cargo-update`/`-sweep`/`-cache` | project-local linting, Rust cargo maintenance |
| **Archives & docs** | `ouch` (compress/extract), `typst` (doc compiler) | packing/unpacking archives, typesetting |
| **Shell & nav** | `navi` (interactive cheat sheet), `fzf`, `zoxide`, `yazi` (file manager) | fuzzy-finding, cheat lookups, browsing files |
| **Runtime pinning** | `mise` (per-project versions via `.mise.toml`, run with `mise x -- <tool>`), `rustup` (Rust toolchains) | a project pins a language version; switching Rust toolchains |
For tools outside this list, prefer an existing dependency or native capability. Install only within the task's authorization and the project's tool-management convention.
## When NOT to substitute
- Portable shell scripts that may run on minimal/other machines → stick to POSIX (`grep`, `sed`, `find`, `curl`) so they don't depend on this toolbelt.
- Pure-JSON pipelines → `jq` remains the default (per global CLAUDE.md).
- For a tool `command -v` cannot find, `comma` fetches and runs any nixpkgs binary on demand. Its command name is a single comma, so it reads oddly inline:
```bash
, ffmpeg -i in.mov out.mp4
```
Good for a one-off; reaching for the same tool repeatedly is a signal to add it to `harus-config`. Fall back to the classic when `comma` is unavailable too.
- **`command -v <tool>` is the check.** Tool inventories drift: `scripts/tools` is hand-maintained help text, `packages.nix` declares intent a machine may not have switched to, and this skill's own table is a third copy. Verify against the machine.