https://github.com/master4novice/master-cli
Master CLI for developers and AI agents — headless, JSON-first commands that replace the boilerplate agents regenerate on every machine: epoch/date conversion, JWT decode, port-killing, file finding, and directory trees. Self-describing via mfn capabilities and llms.txt; every command runs headless with stable exit codes.
https://github.com/master4novice/master-cli
agent-tools ai-agents automation cli command-line developer-tools devtools directory-tree epoch-converter fuzzy-finder headless-cli json-output jwt-decode kill-port llm-tools master-cli mfn nodejs timezone typescript
Last synced: 10 days ago
JSON representation
Master CLI for developers and AI agents — headless, JSON-first commands that replace the boilerplate agents regenerate on every machine: epoch/date conversion, JWT decode, port-killing, file finding, and directory trees. Self-describing via mfn capabilities and llms.txt; every command runs headless with stable exit codes.
- Host: GitHub
- URL: https://github.com/master4novice/master-cli
- Owner: Master4Novice
- License: mit
- Created: 2026-06-03T10:13:56.000Z (16 days ago)
- Default Branch: master
- Last Pushed: 2026-06-06T08:42:29.000Z (13 days ago)
- Last Synced: 2026-06-08T23:24:43.728Z (11 days ago)
- Topics: agent-tools, ai-agents, automation, cli, command-line, developer-tools, devtools, directory-tree, epoch-converter, fuzzy-finder, headless-cli, json-output, jwt-decode, kill-port, llm-tools, master-cli, mfn, nodejs, timezone, typescript
- Language: TypeScript
- Homepage:
- Size: 236 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# @master4n/master-cli (`mfn`)
[](https://github.com/Master4Novice/master-cli/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/@master4n/master-cli)
**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
```sh
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 --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`](./llms.txt) documents the full agent contract.
## Quick start
```sh
mfn -h # top-level help (lists every command)
mfn -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 --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 --help` for the full flag list and more examples.
### Examples
```sh
# 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`](https://www.npmjs.com/package/@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`](https://www.npmjs.com/package/@master4n/temporal-transformer) — epoch/timestamp ↔ date conversion with auto unit-detection and IANA timezones (Luxon-backed)
- [`@master4n/temporal-transformer-codemod`](https://www.npmjs.com/package/@master4n/temporal-transformer-codemod) — codemod to migrate temporal-transformer v1→v2
- [`@master4n/http-status`](https://www.npmjs.com/package/@master4n/http-status) — machine-readable HTTP status-code registry for apps & AI agents
- [`@master4n/decorators`](https://www.npmjs.com/package/@master4n/decorators) — zero-dependency TypeScript decorators (DI, validation, resilience, redaction)
## License
MIT © [Master4Novice](https://github.com/Master4Novice)