NAME

homelab - operator CLI for a single-node homelab

SYNOPSIS

homelab

DESCRIPTION

homelab is a realistic multi-level operator CLI projected as an MCP server over stdio. Mirrors the shape of a real ops CLI (cluster / node / pod / deploy / obs / backup) so the rendered tool surface has the same depth and breadth an MCP client sees in production.

Tool name formation rules:

Every leaf in the tree becomes one MCP tool. The tool name is
the underscore-joined command path with the root stripped:

    homelab cluster node drain    -> tool: cluster_node_drain
    homelab cluster pod ls        -> tool: cluster_pod_ls
    homelab deploy service        -> tool: deploy_service
    homelab obs query             -> tool: obs_query
    homelab backup                -> tool: backup

The joiner is configurable (Options.NameJoiner). Default is
underscore. Dotted joiners ("." or ".tools.") interact poorly
with mcporter selectors that split on dot to address tool by
server.tool, so the default got flipped to underscore in
cli-mcp v0.x. Override only if your client speaks a different
addressing convention.

Why this example exists:

- Renderer stress test. A real ops tree has enough depth to
  reveal layout bugs that a one-leaf demo cannot.
- Tool-name readability test. `cluster_pod_ls` is fine for an
  agent; `cluster_pod_ls_namespace_filter` is not. Watch the
  generated tool names; consider flattening or renaming if
  they get unwieldy.
- Input-schema test. Flags with aliases, repeating positional
  arg shapes, optional vs required, all exercise the schema
  generation path.

Operating model for an agent calling this tree as MCP tools:

- The tools/list response is the full inventory. Cache it.
- The MCP description for each tool comes from Usage. ArgsUsage
  becomes part of the input schema description. Description
  becomes the longer help text the agent's UI may surface.
- These Actions are stubs (print "[pretend] <verb>"). Real
  versions would call into the ops infrastructure with the
  argv passed through. The shape of the MCP projection does
  not depend on the Action body.

Usage:

homelab [GLOBAL OPTIONS] [command [COMMAND OPTIONS]] [ARGUMENTS...]

COMMANDS

cluster

manage the homelab cluster

node

operate on a single node

drain

cordon and drain a node before maintenance

uncordon

mark a node schedulable again

labels

show or set node labels

pod

operate on individual pods

ls

list pods, optionally filtered by namespace

--namespace, -n="":

logs

tail logs for a pod

--follow, -f:

exec

run a one-shot command inside a pod

deploy

deploy and roll out services

service

deploy a named service from the manifest repo

--dry-run:

--version="":

rollback

rollback a service to a previous revision

obs

observability stack helpers

tail

tail aggregated logs

query

PromQL helper

dashboards

list deployed Grafana dashboards

backup

kick off ad-hoc backups

--target="": (default: "all")

cli-mcp examples/large-tree