Toolkit — User Manual

Toolkit is an interactive terminal application for DevOps & infrastructure management. It provides a keyboard-driven TUI (Terminal User Interface) for inspecting and operating on Kubernetes clusters, Terraform configurations, OCI resources, and large tabular datasets — all without leaving your terminal.

Installation
Initial Setup
Configuration Reference
Launching Toolkit
Interface Overview
Navigation
Categories
Filtering & Searching
Sorting
Detail View
Infrastructure Operations
Live Updates
Exporting Data
Clipboard Integration
Keyboard Reference
Shell Completion
Logging & Debugging
Subcommands

Installation

Option A — Go install (latest release)

go install github.com/jingle2008/toolkit/cmd/toolkit@latest

Option B — Homebrew (macOS / Linux)

brew install jingle2008/tap/toolkit

Migrating from the older jingle2008/homebrew-toolkit tap (order matters — brew untap refuses while the formula is still installed):

brew uninstall toolkit
brew untap jingle2008/toolkit              # canonical short name; the homebrew- prefix is implied
brew install jingle2008/tap/toolkit

Option C — Build from source

git clone https://github.com/jingle2008/toolkit.git
cd toolkit
make
# binary is placed in ./bin/toolkit

Verify the install:

toolkit version

Initial Setup

Run init to generate an example config file:

toolkit init

This creates ~/.config/toolkit/config.yaml with all available options pre-populated. Open it in your editor and fill in the required fields:

# Path to your Terraform / infrastructure repository
repo-path: "/path/to/your/repo"

# Kubernetes config (defaults to ~/.kube/config)
kubeconfig: "/path/to/.kube/config"

# Environment identifiers
env-type:   "dev"          # e.g. dev, staging, prod
env-region: "us-phoenix-1" # OCI region
env-realm:  "oc1"          # OCI realm

# Default category to open on startup
category: "tenant"

# Optional: path to extra metadata (tenants, etc.)
metadata-file: ""

# Logging
log-file:   "toolkit.log"
log-format: "console"   # console | json | slog
log-level:  ""           # debug | info | warn | error (empty = default)
debug:      false

Tip: You can override any config value at runtime with CLI flags (see Configuration Reference).

Configuration Reference

All flags can be set in the config file or passed directly on the command line. CLI flags take precedence.

Config Key	CLI Flag	Default	Required	Description
`repo-path`	`--repo-path`	—	Yes	Path to Terraform / config repository
`kubeconfig`	`--kubeconfig`	`~/.kube/config`	No	Path to kubeconfig file
`env-type`	`--env-type`	—	Yes	Environment type (`dev`, `prod`, …)
`env-region`	`--env-region`	—	Yes	Cloud region (e.g. `us-phoenix-1`)
`env-realm`	`--env-realm`	—	Yes	Cloud realm (e.g. `oc1`)
`category`	`-c / --category`	—	Yes	Initial data category to display
`filter`	`-f / --filter`	`""`	No	Pre-applied filter on startup
`metadata-file`	`--metadata-file`	`~/.config/toolkit/metadata.yaml`	No	Optional extra metadata file
`config`	`--config`	`~/.config/toolkit/config.yaml`	No	Path to the config file itself
`log-file`	`--log-file`	`toolkit.log`	No	Log output path
`debug`	`-d / --debug`	`false`	No	Enable debug-level logging
`log-format`	`--log-format`	`console`	No	Log format: `console`, `json`, or `slog`
`log-level`	`--log-level`	`""`	No	Minimum log level: `debug` `info` `warn` `error`

Launching Toolkit

# Use values from config file
toolkit

# Override category and filter inline
toolkit -c gpunode -f "phoenix"

# Point to a different environment
toolkit --env-type prod --env-region us-ashburn-1

# Show all flags
toolkit --help

Interface Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│  Tenant  LimitDefinition  PropertyDefinition  GPUPool  GPUNode  ...         │  ← Category tabs
├─────────────────────────────────────────────────────────────────────────────┤
│  NAME           │  OCIDS                            │  INTERNAL ↕ │  NOTE   │  ← Column headers (↕ = sortable)
│  ───────────────┼───────────────────────────────────┼─────────────┼──────── │
│  acme-corp      │  ocid1.tenancy.oc1..aaa…xyz       │  false      │         │
│  ▶ beta-tenant  │  ocid1.tenancy.oc1..bbb…uvw,…(+1) │  true       │  pilot  │  ← Selected row
│  gamma-inc      │  ocid1.tenancy.oc1..ccc…rst       │  false      │         │
├─────────────────────────────────────────────────────────────────────────────┤
│  Filter: _                                                                   │  ← Filter / status bar
│  [?] Help  [q] Quit  [/] Filter  [tab] Next  [y] Details  [e] Export CSV   │  ← Key hints
└─────────────────────────────────────────────────────────────────────────────┘

The interface has four zones:

Zone	Description
Category tabs (top)	Navigate between data categories with `Tab` / `Shift+Tab`
Table (center)	Scrollable, sortable, filterable data rows
Status bar	Shows current filter text, aggregate statistics, and a `● LIVE` indicator when the current category is updating automatically (see Live Updates)
Key hints (bottom)	Context-sensitive reminder of available keys

Navigation

Moving around the table

Key	Action
`↑` / `↓`	Move selection up / down
`PgUp` / `PgDn`	Jump one page
`Home` / `End`	Jump to first / last row

Switching categories

Key	Action
`Tab`	Next category
`Shift+Tab`	Previous category
`:` + alias + `Enter`	Jump directly to a category by alias (Command mode)

Category aliases — type : then one of these shortcuts:

Alias	Category
`t` / `tenant`	Tenant
`l` / `ld`	LimitDefinition
`cpd`	ConsolePropertyDefinition
`pd`	PropertyDefinition
`lto`	LimitTenancyOverride
`cpto`	ConsolePropertyTenancyOverride
`pto`	PropertyTenancyOverride
`lro`	LimitRegionalOverride
`cpro`	ConsolePropertyRegionalOverride
`pro`	PropertyRegionalOverride
`bm`	BaseModel
`im` / `importedmodel`	ImportedModel
`ma`	ModelArtifact
`e` / `env`	Environment
`st`	ServiceTenancy
`gp`	GPUPool
`gn`	GPUNode
`dac`	DedicatedAICluster

History navigation

Navigate back and forward through the categories you've visited:

Key	Action
`[`	History back
`]`	History forward

Scoping into a context

Some categories are parent scopes — pressing Enter on a row zooms in to the child category filtered to that parent.

Parent	Child categories available
Tenant	LimitTenancyOverride, ConsolePropertyTenancyOverride, PropertyTenancyOverride, DedicatedAICluster, ImportedModel
LimitDefinition	LimitTenancyOverride, LimitRegionalOverride
ConsolePropertyDefinition	ConsolePropertyTenancyOverride, ConsolePropertyRegionalOverride
PropertyDefinition	PropertyTenancyOverride, PropertyRegionalOverride
GPUPool	GPUNode

Press Esc to exit the scoped context and return to the parent.

Category	Description
Tenant	Tenant-level data; supports faulty tracking, internal flag, and scoping into overrides
Environment	Cloud environment configurations
ServiceTenancy	Service-to-tenancy mappings

Category	Description
LimitDefinition	Service quota / limit definitions
ConsolePropertyDefinition	Console feature-flag definitions
PropertyDefinition	Generic property definitions

Category	Description
LimitTenancyOverride	Per-tenant quota overrides
ConsolePropertyTenancyOverride	Per-tenant console property overrides
PropertyTenancyOverride	Per-tenant property overrides

Category	Description
LimitRegionalOverride	Region-specific limit overrides
ConsolePropertyRegionalOverride	Region-specific console property overrides
PropertyRegionalOverride	Region-specific property overrides

Category	Description
BaseModel	AI model definitions; supports faulty tracking
ImportedModel	Tenant-imported models (namespaced BaseModel CRs + ClusterBaseModel CRs with a `tenancy-id` label)
ModelArtifact	Model artifact versions
GPUPool	OCI GPU instance pools; supports scaling
GPUNode	Individual Kubernetes GPU compute nodes
DedicatedAICluster	OCI Dedicated AI Clusters

Filtering & Searching

Enter filter mode

Press / to open the filter input at the bottom of the screen. Start typing and the table updates in real time (100 ms debounce).

Filter: phoenix█

Matching is case-insensitive and substring-based.
Press Esc to clear the filter and exit filter mode.

Paste a filter from clipboard

If you have a filter expression already copied:

p    → paste clipboard contents directly as the filter

This is useful for pasting long IDs or complex strings.

Pre-apply a filter on startup

toolkit -c gpunode -f "us-phoenix"

Sorting

Sort by name (always available in list view)

Shift+N    → sort by Name (ascending / descending toggle)

Category-specific sort keys

Each category exposes additional sort columns. In the TUI, the column headers that participate in sorting are marked with a ↕ indicator so you can see at a glance which columns the keys below will reach.

Category	Key	Sorts by
BaseModel	`Shift+S`	Size
BaseModel	`Shift+C`	Context
Tenant	`Shift+I`	Internal
Environment	`Shift+T`	Type
ServiceTenancy	`Shift+T`	Type
ConsolePropertyDefinition	`Shift+V`	Value
PropertyDefinition	`Shift+V`	Value
GPUPool	`Shift+S`	Size
GPUNode	`Shift+F`	Free
GPUNode	`Shift+T`	Type
GPUNode	`Shift+A`	Age
DedicatedAICluster	`Shift+T`	Tenant
DedicatedAICluster	`Shift+I`	Internal
DedicatedAICluster	`Shift+U`	Usage
DedicatedAICluster	`Shift+S`	Size
DedicatedAICluster	`Shift+A`	Age
ImportedModel	`Shift+T`	Tenant
ImportedModel	`Shift+V`	Vendor
LimitTenancyOverride	`Shift+T`	Tenant
LimitTenancyOverride	`Shift+R`	Regions
ConsolePropertyTenancyOverride	`Shift+T`	Tenant
ConsolePropertyTenancyOverride	`Shift+R`	Regions
ConsolePropertyTenancyOverride	`Shift+V`	Value
PropertyTenancyOverride	`Shift+T`	Tenant
PropertyTenancyOverride	`Shift+R`	Regions
PropertyTenancyOverride	`Shift+V`	Value
LimitRegionalOverride	`Shift+R`	Regions
PropertyRegionalOverride	`Shift+R`	Regions
PropertyRegionalOverride	`Shift+V`	Value
ConsolePropertyRegionalOverride	`Shift+R`	Regions
ConsolePropertyRegionalOverride	`Shift+V`	Value

Pressing the same key again reverses the sort direction.

Toggle alias view

Ctrl+A    → toggle between full category names and short aliases in the UI

Detail View

Press y on any selected row to open the Detail View, which shows the full JSON object for that item.

┌─────────────────────────────────────────────────┐
│  DETAIL — acme-corp (Tenant)                    │
├─────────────────────────────────────────────────┤
│  {                                              │
│    "name":     "acme-corp",                     │
│    "internal": false,                           │
│    "status":   "Active",                        │
│    "region":   "us-phoenix-1",                  │
│    ...                                          │
│  }                                              │
├─────────────────────────────────────────────────┤
│  [y/esc] Back  [c] Copy Name  [o] Copy Object  │
└─────────────────────────────────────────────────┘

Key	Action
`y` or `Esc`	Return to list view
`↑` / `↓`	Scroll the JSON content
`c`	Copy the item's name to clipboard
`o`	Copy the entire JSON object to clipboard

Infrastructure Operations

Certain categories expose live infrastructure operations. These require Kubernetes or OCI credentials to be configured.

Warning: Operations like Drain, Reboot, and Delete are irreversible. Toolkit guards against duplicate in-flight requests automatically.

GPU Nodes (`GPUNode`)

Select a node in the GPUNode category:

Key	Operation	Description
`Shift+C`	Toggle Cordon	Mark node unschedulable / schedulable
`Shift+D`	Drain	Evict all pods from the node
`Shift+R`	Reboot	Soft-reset (reboot) the node
`Ctrl+X`	Delete	Terminate the node instance
`r`	Refresh	Reload GPU node data
`Ctrl+Z`	Toggle Faulty	Show/hide nodes flagged as faulty

GPU Pools (`GPUPool`)

Key	Operation	Description
`Shift+U`	Scale Up	Request an increase in pool capacity
`r`	Refresh	Reload pool data
`Ctrl+Z`	Toggle Faulty	Show/hide pools with faulty status

Dedicated AI Clusters (`DedicatedAICluster`)

Key	Operation	Description
`Ctrl+X`	Delete	Delete the selected Dedicated AI Cluster
`r`	Refresh	Reload cluster data
`Ctrl+Z`	Toggle Faulty	Show/hide faulty clusters

Refreshing cluster-derived categories

The r key reloads the current list from the live cluster. In addition to GPUNode / GPUPool / DedicatedAICluster above, it is also bound on the read-only cluster-derived categories:

Category	Key	Operation
BaseModel	`r`	Reload base models from the cluster
ImportedModel	`r`	Reload tenant-imported models from the cluster

Most categories also update on their own — see Live Updates. r remains useful to force an immediate reload and to recover a watch that has dropped.

Faulty item tracking

Several categories support a faulty toggle (Ctrl+Z). When enabled, only items that are in a faulty state are shown. The status bar displays counts like Faulty: 2, Healthy: 10.

Live Updates

Toolkit keeps the current view fresh automatically. When the category on screen is being watched, the status bar shows a ● LIVE indicator. Updates are debounced (~5 s): a burst of changes collapses into a single reload, and reloads preserve your active filter and selected row.

There are two independent watch mechanisms:

Source	Categories	Triggers on
Cluster watch (Kubernetes)	BaseModel, ImportedModel, GPUNode, GPUWorkload, DedicatedAICluster	Changes to the watched cluster resources (requires a working kubeconfig)
Working-tree watch (local files)	Tenants, Definitions, Overrides, Environments, Service Tenancies, Model Artifacts, GPU Pools, Aliases	Saving any file under the repo path (`.git` and dotfiles are ignored)

So editing a config file in your repo, or a change landing in the cluster, shows up on screen within a few seconds without pressing a key.

Notes:

No credentials / unreadable repo: if a watch can't be established it simply doesn't run — the data still loads once and r reloads on demand. No ● LIVE indicator is shown.
Switching environments keeps live updates working: the working-tree watch continues and the cluster watch re-establishes for the new environment as you navigate.
Recovering a dropped watch: the working-tree watch has no auto-reconnect. If it drops (rare — e.g. a filesystem error), press r to re-establish it.
Not watched: the optional external metadata file (metadata-file, default ~/.config/toolkit/metadata.yaml) lives outside the repo and is read at startup. Tenant metadata you edit in-app updates immediately; external edits to that file require a restart.

Exporting Data

Press e in any list view to open the Export CSV dialog.

A file picker appears — navigate to your desired output directory.
Select or type a filename ending in .csv.
Press Enter to confirm.

The exported CSV reflects the current filter and sort state — what you see is what you get.

Clipboard Integration

Key	Available in	Copies
`c`	List & Detail view	Item name or ID (on ImportedModel, the full OCID)
`t`	Tenant, DedicatedAICluster, ImportedModel, tenancy override categories	Tenant ID
`o`	Detail view only	Full JSON object
`p`	List view	Pastes clipboard content as a filter

Keyboard Reference

Always available (Global)

Key	Action
`q` / `Ctrl+C`	Quit
`?` / `h`	Toggle help overlay
`Esc`	Back / Clear filter
`y`	Toggle detail view
`c`	Copy item name / ID

List view

Key	Action
`Tab`	Next category
`Shift+Tab`	Previous category
`/`	Enter filter mode
`:`	Enter command mode (alias jump)
`p`	Paste clipboard as filter
`Enter`	View item / scope into context
`[`	History back
`]`	History forward
`e`	Export table as CSV
`Ctrl+A`	Toggle alias view
`Shift+N`	Sort by name

Detail view

Key	Action
`y` / `Esc`	Return to list
`↑` / `↓`	Scroll content
`c`	Copy item name
`o`	Copy full JSON object

In-app help

Press ? or h at any time to display the full keybinding help overlay. The help is context-sensitive — it only shows keys relevant to your current category and view mode.

Shell Completion

Generate and install completion scripts for your shell:

# Bash
toolkit completion bash > /etc/bash_completion.d/toolkit

# Zsh
toolkit completion zsh > "${fpath[1]}/_toolkit"

# Fish
toolkit completion fish > ~/.config/fish/completions/toolkit.fish

# PowerShell
toolkit completion powershell > toolkit.ps1

After sourcing the file / restarting your shell, pressing Tab while typing toolkit commands will auto-complete flags and subcommands.

Logging & Debugging

Toolkit writes structured logs to a file (default: toolkit.log in your working directory).

# Enable verbose debug logging
toolkit --debug

# Write logs to a custom path
toolkit --log-file /tmp/tk-debug.log

# Use JSON format for log shipping / parsing
toolkit --log-format json

# Set minimum log level
toolkit --log-level warn

Supported log levels (from most to least verbose): debug → info → warn → error.

Supported log formats: console (human-readable), json (structured), slog (Go slog).

Subcommands

Subcommand	Description
`toolkit init`	Scaffold `~/.config/toolkit/config.yaml` with example values
`toolkit completion <shell>`	Print shell completion script for `bash`, `zsh`, `fish`, or `powershell`
`toolkit version [--check-updates]`	Print installed version; `--check-updates` fetches the latest release from GitHub and compares

Tips & Tricks

Start with a filter — pass -f <term> on the command line to pre-filter noisy categories like GPUNode or Tenant.
Scope then drill — select a LimitDefinition and press Enter to instantly view all tenancy overrides for that specific limit.
Use command mode for fast navigation — press :dac Enter to jump straight to DedicatedAICluster from any category.
Copy-then-filter workflow — copy a tenant ID with t, switch to another category, then paste it as a filter with p to quickly cross-reference data.
Export after filtering — apply a filter first, then press e to export only the rows you care about.
History saves context — use [ and ] to bounce between parent and child category views without re-typing.

For bugs and feature requests, open an issue at github.com/jingle2008/toolkit.

FilesExpand file tree

USER_MANUAL.md

Latest commit

History