toolkit

Toolkit

Toolkit is a collection of reusable Go components exposed through a modular CLI and optional TUI (built with Bubble Tea).
It targets day-to-day DevOps & development automation: querying Kubernetes, parsing Terraform plans, mass-editing config files, and inspecting large data tables directly in your terminal.

• User Manual
• Kubernetes Client Fakes & Testing Patterns

Feature Highlights

Architecture at a glance

flowchart LR
    subgraph CFG ["Config sources"]
        flags["CLI flags<br/>TOOLKIT_* env"]
        file["~/.config/toolkit/config.yaml"]
    end
    flags --> viper((viper<br/>merge))
    file --> viper
    viper --> Cfg["config.Config"]

    subgraph SRC ["Data sources"]
        tf["Terraform repo<br/>(repo_path)"]
        k8s["Kubernetes API<br/>(kubeconfig)"]
        oci["OCI APIs<br/>(env_realm)"]
    end

    Cfg --> Loader
    tf --> Loader
    k8s --> Loader
    oci --> Loader
    Loader["internal/infra/loader<br/>(composite)"]

    Loader --> TUI["TUI<br/>toolkit"]
    Loader --> Get["Headless<br/>toolkit get / config / doctor"]
    Loader --> MCP["MCP server<br/>toolkit mcp"]
    Loader --> Mut["Mutations<br/>cordon · drain · reboot<br/>scale · delete · terminate"]

The loader composite is the single funnel every entry point goes through, so the four surfaces (TUI, headless get, MCP, mutations) all see identical data and the same partial-load semantics.

Install

# Latest release
go install github.com/jingle2008/toolkit/cmd/toolkit@latest

# From source
git clone https://github.com/jingle2008/toolkit.git
cd toolkit && make

# From Homebrew (macOS/Linux)
brew tap jingle2008/homebrew-toolkit
brew install toolkit

Getting Started

After installation, try these quick commands:

toolkit init
# Scaffold an example config file at ~/.config/toolkit/config.yaml

toolkit config --validate
# Sanity-check the effective config; exits non-zero on failure

toolkit completion bash   # or zsh/fish
# Output shell completion script for your shell

toolkit version --check
# Print your installed version and check for updates

Usage

toolkit --help                # all global flags

Global Flags

(See internal/cli/flags.go for the authoritative list.)

Headless get (for scripts and LLM integration)

toolkit get <category> is the non-TUI equivalent of selecting a category in the interactive UI. It uses the same loaders and emits machine-friendly output for piping into jq, posting to LLM tools, feeding spreadsheets, or driving shell pipelines.

Supported formats (-o): table (default), json, jsonl, yaml, csv, tsv.

# JSON array (default pretty-printed)
toolkit get tenant -o json

# Line-delimited JSON (great for streaming / `xargs`)
toolkit get gpunode -f us-ashburn-1 -o jsonl

# Plain table (default)
toolkit get dac

# YAML
toolkit get basemodel -f cohere -o yaml

# CSV for spreadsheets (proper quoting via encoding/csv)
toolkit get tenant -o csv > tenants.csv

# TSV for `cut` / `awk` pipelines
toolkit get gpupool -o tsv | cut -f1,3

# Suppress headers (table/csv/tsv)
toolkit get tenant --no-headers

Category aliases match the TUI (t, bm, gn, dac, …). Run toolkit get alias for the full list, or enable shell completion (toolkit completion zsh) for tab-completion. Logs are written to --log_file (default toolkit.log) so stdout stays clean for parsing.

For gpunode, dac, modelartifact, and the tenancy-override categories, the structured outputs (json, jsonl, yaml) are a flat array of objects with the originating group key injected as pool, tenant, or model — easier for jq and LLM consumers than the previous map-shaped output.

Inspect effective config (toolkit config)

toolkit config prints the merged view every other subcommand sees — defaults + TOOLKIT_* env + config file + flags — so you can see what's actually in effect without opening the YAML by hand:

toolkit config                    # YAML (default)
toolkit config -o json            # JSON for `jq`
toolkit config --pretty=false     # compact JSON
toolkit config --validate         # run config.Validate(); exit non-zero on failure

--validate mode emits a structured {valid, config_file, error?} payload and exits non-zero on failure — suitable for if ! toolkit config --validate; then abort; fi precondition checks in CI/scripts.

Cluster mutations

Maintenance operations the TUI exposes via keyboard shortcuts are also available as scriptable subcommands. All mutations support --dry-run (preview the action) and --yes / -y (skip the interactive prompt). Each call writes a JSON line to the audit log.

Example:

toolkit drain node-42 --dry-run     # preview
toolkit drain node-42 -y            # run without prompt

See docs/recipes.md for end-to-end flows (MCP setup, maintenance windows, audit exports, Slack digests).

MCP server (toolkit mcp)

For agent integration via the Model Context Protocol, toolkit mcp boots a stdio MCP server that exposes the same loader surface as get — but as typed tools an AI agent can call directly, no shell-out needed.

Configure once in your MCP client. Claude Desktop / Claude Code use JSON:

{
  "mcpServers": {
    "toolkit": {
      "command": "toolkit",
      "args": ["mcp"]
    }
  }
}

Codex CLI (~/.codex/config.toml) uses TOML:

[mcp_servers.toolkit]
command = "toolkit"
args = ["mcp"]

See docs/recipes.md for the per-client file paths and first prompts to try.

Read tools — return a { "items": [...], "count": N, "warnings": [...] } envelope:

Every read tool takes an optional filter (fuzzy substring) and optional env_type / env_region / env_realm to override the startup env per-call, so a single running server can answer questions across multiple environments.

Mutation tools — gated on confirm: true. The same safety model as the CLI: failures surface via notifications/message, every call writes to the audit log:

By default, mutation tools ignore any per-call env_type / env_region / env_realm and only act in the startup env — the operator's credentials decide the maximum blast radius, not the agent. Pass --mutation_env_override_allowed at server start to opt in to per-call env routing.

Project Layout

.
├── cmd/
│   └── toolkit/            # main()
├── internal/
│   ├── cli/                # cobra root & sub-commands
│   ├── ui/tui/             # Bubble Tea models & views
│   ├── infra/
│   │   ├── k8s/            # K8s data sources
│   │   └── terraform/      # Terraform provider
│   ├── config/             # typed config structs
│   ├── configloader/       # env + file loader
│   ├── collections/        # generic filter/sort
│   └── encoding/jsonutil/  # JSON helpers
├── pkg/
│   ├── infra/logging/      # zap-based logging
│   └── models/             # domain models and types
└── test/
    └── integration/

Build

make

or

go build -o bin/toolkit ./cmd/toolkit

Run

./bin/toolkit --help

or, if built with Go:

go run ./cmd/toolkit --help

Testing

Run all tests with:

go test ./...

Running tests

• Unit tests (default):

  make test
  

• Integration tests (with build tag):

  make test-int
  

• Coverage reports:

  make cover      # unit test coverage
  make cover-int  # integration test coverage
  

Continuous Integration

• Unit tests run on all pushes and pull requests.
• Integration tests run on pushes to main and nightly (see .github/workflows/ci.yml).
• CI target: Run make ci to execute both lint and test in one step (recommended for local and CI use).

Developer Workflow

• One-time setup: make setup (installs golangci-lint, gofumpt, goimports)
• Optional: enable git hooks with pre-commit: pre-commit install
• Run make ci before pushing to ensure code passes lint and tests.
• Use make lint to check for style and static analysis issues.
• Use make test for a full race-enabled test run.
• Use make fmt and make tidy to auto-format and tidy dependencies.

Architecture Overview

Toolkit follows a modular, testable architecture:

• Loaders: internal/infra/loader provides concrete and interface-based loaders for datasets (K8s, Terraform, OCI), enabling dependency injection and testability.
• TUI Model: internal/ui/tui contains Bubble Tea models, views, and update loop; composed via functional options.
• Domain types: pkg/models defines strongly-typed domain models used across loaders and UI.
• Category enum: internal/domain/category.go provides strongly-typed categories and parsing.
• Logging: pkg/infra/logging wraps zap for structured logs with configurable format and file path.

Logging

Toolkit uses zap for structured, machine-readable logging. By default logs are written to toolkit.log (configurable via --log_file) and support --log_format of console, json, or slog. The minimum log level can be set via --log_level (debug, info, warn, error).

Contributing

Contributions are welcome! Please open issues or submit pull requests for new features, bug fixes, or improvements.

License

This project is licensed under the MIT License.