@master4n/master-cli

@master4n/master-cli (mfn)

Master CLI for developers and AI agents. A set of headless, JSON-first commands that replace the boilerplate agents otherwise regenerate on every machine — timestamp/date conversion, JWT decoding, freeing ports, finding files, and directory trees. Every command runs the same for a human at a terminal and for an agent reading stdout.

Installation

npm install -g @master4n/master-cli

This installs the mfn command.

The contract (why it's agent-friendly)

• Headless-first — every command runs from flags/stdin. Interactive prompts appear only on a TTY when required input is missing; with --json or when piped, commands never block.
• Machine-readable — pass --json (or just pipe; non-TTY auto-emits) and you get exactly one JSON object on stdout: { "ok": true, ... } on success, { "ok": false, "error", "message" } on failure.
• Stable exit codes — 0 success · 1 runtime error · 2 usage error.
• Clean channels — the banner, spinners, and logs go to stderr; stdout carries only data, so mfn <cmd> --json | jq always works.
• Strict parsing — unknown commands/flags and missing args fail loudly ({ok:false}, exit 2), never a silent "success".
• Self-describing — mfn capabilities --json lists every command, and llms.txt documents the full agent contract.

Quick start

mfn -h                 # top-level help (lists every command)
mfn <command> -h       # per-command help: flags + examples
mfn -v                 # version
mfn capabilities --json   # machine-readable manifest of all commands

Commands

Command	What it does	Example
capabilities	Self-describing manifest of every command	mfn capabilities --json
id	Generate IDs — UUID v4, time-ordered UUID v7, or URL-safe nano	mfn id --json · mfn id -t uuid7 -n 3 --json
hash	Hash a string, file, or stdin (md5/sha1/sha256/sha512)	mfn hash hello --json · mfn hash -f ./x --json
encode	Encode/decode text — base64, base64url, hex, url	mfn encode hi --json · mfn encode aGk= -d --json
random	Secure random bytes, or an unbiased password	mfn random --json · mfn random -p -l 32 --json
port	Find a free port, or check if one is available	mfn port --json · mfn port -c 3000 --json
epoch	Convert between epoch timestamps and dates (auto-detects s/ms/µs/ns)	mfn epoch 1622547800 --json · mfn epoch --from 2021-06-01T11:43:20Z --json
date	Convert/format a date across timezones (defaults to now)	mfn date 2024-07-04T15:30:30Z --tz America/New_York --json
decode	Decode a JWT (header + payload + expiry; signature not verified)	mfn decode -t <jwt> --json
kill	Kill the process(es) listening on given ports	mfn kill -p 3000 8080 -y --json
sc	Fuzzy-find files/folders under the current directory	mfn sc service --json
cts	Print (or export) a tree of the current directory	mfn cts --json · mfn cts -t png
update	Update the CLI (or a named package) to the latest version	mfn update --json

Run mfn <command> --help for the full flag list and more examples.

Examples

# Timestamps: any unit in, readable date out (parse cleanly in a script)
mfn epoch 1622547800000 --json | jq -r '.utc'        # 2021-06-01 11:43:20.000

# Free the ports your dev server got stuck on
mfn kill -p 3000 5173 -y --json

# Inspect a JWT without a website
mfn decode -t "$TOKEN" --json | jq '.payload.exp'

# Hand an agent the repo layout
mfn cts --json | jq -r '.tree'

Notes

• Date/time features are powered by @master4n/temporal-transformer v2 (Luxon-backed, integer epochs, yyyy-MM-dd HH:mm:ss tokens).
• Process/port/package operations use execFile (no shell), so inputs cannot inject commands.

Part of the @master4n toolkit

A small ecosystem of focused, agent-friendly packages:

• @master4n/temporal-transformer — epoch/timestamp ↔ date conversion with auto unit-detection and IANA timezones (Luxon-backed)
• @master4n/temporal-transformer-codemod — codemod to migrate temporal-transformer v1→v2
• @master4n/http-status — machine-readable HTTP status-code registry for apps & AI agents
• @master4n/decorators — zero-dependency TypeScript decorators (DI, validation, resilience, redaction)

License

MIT © Master4Novice