hostctl

hostctl is a modern task runner for managing fleets of hosts. It executes TypeScript or JavaScript automations locally or over SSH while keeping inventories, tags, and secrets in one place.

Why hostctl

• Treat remote automation like regular code: tasks are modules with strong typing and structured logging.
• First-class inventory and secrets management built around AGE.
• Layered runtime cleanly separates CLI parsing, orchestration, and execution for easy extension.

System Requirements

• Node.js 24+ (CLI runs through tsx).
• age for encrypting secrets.
• Git (recommended) for cloning packages and publishing tasks.

Check your toolchain:

node -v
npm -v
age --version

Install hostctl

Clone & Develop

git clone https://github.com/monopod/hostctl.git
cd hostctl
npm install

Use ./hostctl during development or npm run build && ./dist/bin/hostctl.js ... to test the bundled CLI.

Global CLI

npm install -g hostctl
hostctl --help

One-off Execution

Run straight from npm without installing globally:

npx hostctl run core.echo message:hello

Bootstrap identities, inventory, and secrets

1. Generate AGE identities

   mkdir -p ~/.hostctl/age
   age-keygen -o ~/.hostctl/age/you.priv
   age-keygen -y ~/.hostctl/age/you.priv > ~/.hostctl/age/you.pub

2. Author an inventory at ~/.hostctl/hostctl.yaml:

   hosts:
     ubuntu-vm:
       hostname: 192.168.56.15
       user: vagrant
       password: !secret vagrant-password
       tags: [ubuntu, testvm]
   secrets:
     vagrant-password:
       ids: you
       value: vagrant
   ids:
     you: age1...

3. Manage the file

   hostctl inventory encrypt   # wrap with AGE recipients
   hostctl inventory decrypt   # view/edit locally
   hostctl inventory list      # inspect hosts & tags

   Set AGE_IDS="~/.hostctl/age/*.priv" before running commands if the file is encrypted.

Running tasks

• Local script

  npm run build
  ./dist/bin/hostctl.js run example/echo.ts args:hello

• Local package

  hostctl run ./my-package hello name:Sam

• Remote orchestration

  hostctl run -r -t ubuntu core.net.interfaces --json

  • -r/--remote targets hosts selected by tags via SSH.
  • -t/--tag is greedy; use -- before positional args when needed.
• From npm or git

  hostctl run hostctl-hello greet name:Phil
  hostctl run https://github.com/monopod/hostctl-example echo args:hello,world

• Install Docker anywhere

  hostctl run -r -t ubuntu core.docker.install users:hostctl

  The task follows Docker’s official installation guides for Ubuntu/Debian and Fedora/RHEL/Rocky (matching the current xcpng-e2e templates), so the same invocation works across your lab images.
• Run containers

  hostctl run core.docker.run-container image:alpine command:'["/bin/sh","-c","echo from container"]'
  hostctl run core.docker.run-container-detached image:redis name:ci-cache

  The first task streams container output back to the CLI; the detached variant returns the created container ID/name so you can manage it later.

Passing parameters

• key:value pairs after the task name.
• --params '{"key":"value"}' for JSON blobs.
• --file params.json to load structured arguments.

Managing task packages

hostctl pkg commands wrap the npm-only package manager:

hostctl pkg create my-task --lang typescript
hostctl pkg install hostctl-hello
hostctl pkg list
hostctl pkg remove hostctl-hello

Installed packages live under ~/.hostctl/packages and can be run offline once cached.

Designing tasks

Define tasks with the task helper and a typed TaskContext:

import { task, type TaskContext } from 'hostctl';

interface EchoParams { message: string }
interface EchoResult { repeated: string }

async function run(context: TaskContext<EchoParams>): Promise<EchoResult> {
  const { params, info } = context;
  info(`Echo: ${params.message}`);
  return { repeated: params.message };
}

export default task(run, { name: 'example.echo', description: 'Prints a message' });

Key TaskContext capabilities (see docs/task-api.md for details):

• Structured logging via info, warn, error, debug, or log(level, ...).
• Command execution with exec(command, { sudo, env, cwd, stdin, pty }).
• Remote fan-out using ssh(tags, remoteFn).
• Subtask orchestration with run(otherTask(params)).
• Secrets & credentials via getSecret(name) and getPassword().
• Inventory helpers: inventory(tags) and selectedInventory(tags?).
• File helpers: file.read, file.write, file.exists, file.mkdir, file.rm that respect local vs. remote runtime.

Building & testing task packages

1. Scaffold: hostctl pkg create awesome-firewall --lang typescript.
2. Install deps: cd awesome-firewall && npm install.
3. Build: npm run build (defaults to tsc).
4. Test locally without publishing: npx hostctl run . args:foo.
5. Add unit tests with Vitest if needed, or invoke tasks directly in scripts.

Publishing task packages

1. Update package.json metadata (name, version, description, files).
2. Build artifacts (npm run build or rely on prepublishOnly).
3. Authenticate with npm (npm login or NPM_TOKEN).
4. Publish:

   npm version patch   # or minor/major
   npm publish --access public

5. Tag releases in git or automate with tools like release-it (this repo ships release.sh as an example flow).
6. Verify: npm info your-package version.

Consuming published packages

• One-off: npx hostctl run your-package taskName param:value.
• Cache locally: hostctl pkg install [email protected] then run offline.
• Compose in other codebases by adding the package to dependencies and importing its exported tasks.

Troubleshooting

• Task not found: confirm the package exports the task name and that exports exposes it.
• Version mismatch: keep package.json, src/version.ts, and jsr.json in sync before releasing.
• SSH failures: verify inventory entries (hostname, user, auth) and only pass -r when you intend remote execution.
• Secrets: when inventories are encrypted, ensure AGE_IDS includes the private keys so hostctl can decrypt secrets.
• Environment drift: run hostctl runtime to inspect prerequisites or hostctl runtime install to bootstrap them.

Developer workflow

• Format & typing: npm run format (Prettier) and npm run lint (tsc --noEmit).
• Build artifacts: npm run build (tsup) produces dist/ bundles for the CLI and published package.
• Tests:
  • npm run test → unit + functional suites.
  • npm run test:unit, npm run test:functional, npm run test:e2e for focused runs.
• VM helpers (npm run vm:*) are legacy while XCP-ng provisioning matures; see docs/xcp-ng-operations.md.
• Releases rely on npm run release + release-it; see NPM_MIGRATION_PLAN.md for npm-only context.

Documentation map

• Task API reference: docs/task-api.md.
• Operational guides: docs/*.md (process, package, system management, etc.).
• Architecture & design: ARCHITECTURE.md and supporting design docs.
• Contributor guide: CONTRIBUTING.md and AGENTS.md.
• Issue tracking: https://github.com/monopod/hostctl/issues.

Explore the examples under example/, get familiar with the task API, and share automations with the community via npm-compatible packages.