km

km is a lightweight operational script runner built with Perl modules.

Goals

• Single entrypoint CLI: km
• Convention-based modules: each .pm is a runnable script module
• Core-only dependencies (avoid external CPAN modules by default)
• Automation-friendly: non-interactive, stable outputs, standardized exit codes

Quick start

List available modules:

perl bin/km list

Install (cpanm from GitHub)

Install directly from a GitHub repository:

cpanm https://github.com/kevin197011/km.git

After install, you should be able to run km as a command:

km list
km help ping
km install-nginx --dry-run

Upgrade notes (removing legacy installed files)

Because this project moved some modules from the legacy flat layout to lifecycle directories, old installed .pm files may remain on hosts after upgrade (cpanm/MakeMaker does not reliably remove moved/renamed files).

km will also attempt a best-effort auto-prune of legacy flat modules when it detects lifecycle-vs-legacy duplicates (requires write permission to the installed Perl library path).

You can prune legacy files safely:

km tool-prune-legacy          # dry-run
km tool-prune-legacy --yes    # delete (may require root)

User-local install (no sudo)

cpanm -l "$HOME/perl5" https://github.com/kevin197011/km.git
export PATH="$HOME/perl5/bin:$PATH"

Show help:

perl bin/km help
perl bin/km help ping

Run a module:

perl bin/km hello --name=kevin
perl bin/km ping --host=127.0.0.1 --port=22 --count=1 --timeout=1

Module layout

Modules live under lib/KM/Script/:

lib/KM/Script/Hello.pm   # -> km hello
lib/KM/Script/Ping.pm    # -> km ping
lib/KM/Script/Install/Docker.pm  # -> km install-docker
lib/KM/Script/Install/Nginx.pm   # -> km install-nginx
lib/KM/Script/Deploy/Example.pm  # -> km deploy-example
lib/KM/Script/Install/Example.pm # -> km install-example
lib/KM/Script/Update/Example.pm  # -> km update-example
lib/KM/Script/Remove/Example.pm  # -> km remove-example
lib/KM/Script/Other/Example.pm   # -> km other-example
lib/KM/Script/Tool/Example.pm    # -> km tool-example

Lifecycle stages (recommended layout):

lib/KM/Script/
  Install/
  Deploy/
  Update/
  Remove/
  Other/
  Tool/

Mapping rules:

• lib/KM/Script/Deploy/AppRelease.pm → KM::Script::Deploy::AppRelease → km deploy-app-release
• lib/KM/Script/Install/Nginx.pm → KM::Script::Install::Nginx → km install-nginx
• lib/KM/Script/Other/Doctor.pm → KM::Script::Other::Doctor → km other-doctor
• lib/KM/Script/Tool/Doctor.pm → KM::Script::Tool::Doctor → km tool-doctor

Each module:

• MUST implement run and return a numeric exit code (0 means success)
• SHOULD provide our $DESCRIPTION, usage, and examples
• MUST use use strict; and use warnings;

Exit codes

• 0: success
• 2: usage/argument error
• 3: module not found
• 4: module load/compile error
• 5: module runtime error

Tests (non-interactive)

ruby scripts/test.rb