{"id":50653956,"url":"https://github.com/master4novice/master-cli","last_synced_at":"2026-06-10T00:00:46.531Z","repository":{"id":362273381,"uuid":"1258151866","full_name":"Master4Novice/master-cli","owner":"Master4Novice","description":"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.","archived":false,"fork":false,"pushed_at":"2026-06-06T08:42:29.000Z","size":242,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-08T23:24:43.728Z","etag":null,"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"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Master4Novice.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T10:13:56.000Z","updated_at":"2026-06-06T08:42:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Master4Novice/master-cli","commit_stats":null,"previous_names":["master4novice/master-cli"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Master4Novice/master-cli","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Master4Novice%2Fmaster-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Master4Novice%2Fmaster-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Master4Novice%2Fmaster-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Master4Novice%2Fmaster-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Master4Novice","download_url":"https://codeload.github.com/Master4Novice/master-cli/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Master4Novice%2Fmaster-cli/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34130642,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["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"],"created_at":"2026-06-07T22:36:25.811Z","updated_at":"2026-06-10T00:00:46.203Z","avatar_url":"https://github.com/Master4Novice.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @master4n/master-cli (`mfn`)\n\n[![CI](https://github.com/Master4Novice/master-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/Master4Novice/master-cli/actions/workflows/ci.yml)\n[![npm version](https://img.shields.io/npm/v/%40master4n%2Fmaster-cli)](https://www.npmjs.com/package/@master4n/master-cli)\n![npm downloads](https://img.shields.io/npm/dm/%40master4n%2Fmaster-cli)\n![License](https://img.shields.io/npm/l/%40master4n%2Fmaster-cli)\n![Owner](https://img.shields.io/badge/Owner-Master4Novice-orange?style=flat)\n\n**Master CLI for developers and AI agents.** A set of headless, JSON-first\ncommands that replace the boilerplate agents otherwise regenerate on every\nmachine — timestamp/date conversion, JWT decoding, freeing ports, finding files,\nand directory trees. Every command runs the same for a human at a terminal and\nfor an agent reading stdout.\n\n## Installation\n\n```sh\nnpm install -g @master4n/master-cli\n```\n\nThis installs the `mfn` command.\n\n## The contract (why it's agent-friendly)\n\n- **Headless-first** — every command runs from flags/stdin. Interactive prompts\n  appear only on a TTY when required input is missing; with `--json` or when\n  piped, commands never block.\n- **Machine-readable** — pass `--json` (or just pipe; non-TTY auto-emits) and you\n  get exactly one JSON object on stdout: `{ \"ok\": true, ... }` on success,\n  `{ \"ok\": false, \"error\", \"message\" }` on failure.\n- **Stable exit codes** — `0` success · `1` runtime error · `2` usage error.\n- **Clean channels** — the banner, spinners, and logs go to **stderr**; stdout\n  carries only data, so `mfn \u003ccmd\u003e --json | jq` always works.\n- **Strict parsing** — unknown commands/flags and missing args fail loudly\n  (`{ok:false}`, exit 2), never a silent \"success\".\n- **Self-describing** — `mfn capabilities --json` lists every command, and\n  [`llms.txt`](./llms.txt) documents the full agent contract.\n\n## Quick start\n\n```sh\nmfn -h                 # top-level help (lists every command)\nmfn \u003ccommand\u003e -h       # per-command help: flags + examples\nmfn -v                 # version\nmfn capabilities --json   # machine-readable manifest of all commands\n```\n\n## Commands\n\n| Command | What it does | Example |\n| ------- | ------------ | ------- |\n| `capabilities` | Self-describing manifest of every command | `mfn capabilities --json` |\n| `id` | Generate IDs — UUID v4, time-ordered UUID v7, or URL-safe nano | `mfn id --json` · `mfn id -t uuid7 -n 3 --json` |\n| `hash` | Hash a string, file, or stdin (md5/sha1/sha256/sha512) | `mfn hash hello --json` · `mfn hash -f ./x --json` |\n| `encode` | Encode/decode text — base64, base64url, hex, url | `mfn encode hi --json` · `mfn encode aGk= -d --json` |\n| `random` | Secure random bytes, or an unbiased password | `mfn random --json` · `mfn random -p -l 32 --json` |\n| `port` | Find a free port, or check if one is available | `mfn port --json` · `mfn port -c 3000 --json` |\n| `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` |\n| `date` | Convert/format a date across timezones (defaults to now) | `mfn date 2024-07-04T15:30:30Z --tz America/New_York --json` |\n| `decode` | Decode a JWT (header + payload + expiry; signature **not** verified) | `mfn decode -t \u003cjwt\u003e --json` |\n| `kill` | Kill the process(es) listening on given ports | `mfn kill -p 3000 8080 -y --json` |\n| `sc` | Fuzzy-find files/folders under the current directory | `mfn sc service --json` |\n| `cts` | Print (or export) a tree of the current directory | `mfn cts --json` · `mfn cts -t png` |\n| `update` | Update the CLI (or a named package) to the latest version | `mfn update --json` |\n\nRun `mfn \u003ccommand\u003e --help` for the full flag list and more examples.\n\n### Examples\n\n```sh\n# Timestamps: any unit in, readable date out (parse cleanly in a script)\nmfn epoch 1622547800000 --json | jq -r '.utc'        # 2021-06-01 11:43:20.000\n\n# Free the ports your dev server got stuck on\nmfn kill -p 3000 5173 -y --json\n\n# Inspect a JWT without a website\nmfn decode -t \"$TOKEN\" --json | jq '.payload.exp'\n\n# Hand an agent the repo layout\nmfn cts --json | jq -r '.tree'\n```\n\n## Notes\n\n- Date/time features are powered by\n  [`@master4n/temporal-transformer`](https://www.npmjs.com/package/@master4n/temporal-transformer)\n  v2 (Luxon-backed, integer epochs, `yyyy-MM-dd HH:mm:ss` tokens).\n- Process/port/package operations use `execFile` (no shell), so inputs cannot\n  inject commands.\n\n## Part of the @master4n toolkit\n\nA small ecosystem of focused, agent-friendly packages:\n\n- [`@master4n/temporal-transformer`](https://www.npmjs.com/package/@master4n/temporal-transformer) — epoch/timestamp ↔ date conversion with auto unit-detection and IANA timezones (Luxon-backed)\n- [`@master4n/temporal-transformer-codemod`](https://www.npmjs.com/package/@master4n/temporal-transformer-codemod) — codemod to migrate temporal-transformer v1→v2\n- [`@master4n/http-status`](https://www.npmjs.com/package/@master4n/http-status) — machine-readable HTTP status-code registry for apps \u0026 AI agents\n- [`@master4n/decorators`](https://www.npmjs.com/package/@master4n/decorators) — zero-dependency TypeScript decorators (DI, validation, resilience, redaction)\n\n## License\n\nMIT © [Master4Novice](https://github.com/Master4Novice)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaster4novice%2Fmaster-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaster4novice%2Fmaster-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaster4novice%2Fmaster-cli/lists"}