clfly(active)
File-based routing for CLIs — one commands/ tree becomes CLI, completions, and MCP.
npm create @clfly mycliFile-based routing for CLIs — one commands/ tree becomes CLI, completions, and MCP.
npm create @clfly mycliclfly builds a command-line tool from a directory of files. Each file under
commands/ exports one function and the schema of its input. From that tree
clfly derives the argv parser and --help, shell completions for bash, zsh and
fish, and an MCP server, so the same commands are callable by people and by
agents. The same approach wraps an existing CLI: schemas over shell-outs, with no
rewrite.
The contract is Standard Schema, the interface Zod 4, ArkType and Valibot share. clfly asks each command’s schema for its input as draft-07 JSON Schema and refuses a schema library that can’t produce one:
export function toJsonSchema(schema: AnySchema): JsonSchema {
const std = schema["~standard"];
if (std.jsonSchema?.input) {
return std.jsonSchema.input({ target: "draft-07" }) as JsonSchema;
}
throw new ClflyError(
`Schema (vendor: ${std.vendor}) does not implement Standard JSON Schema ` +
`(~standard.jsonSchema). Use Zod 4, ArkType, or Valibot with JSON Schema support.`,
);
}
Every interface reads that one document, so a field’s description written once
appears in --help and in the MCP tool definition.
On the command line, the tokenizer converts only booleans (for --no-* flags)
and leaves numbers as strings. Types belong to the validator: z.coerce.number()
converts and applies defaults. That keeps two type systems from disagreeing at
the boundary between them.
A file’s place in the tree is its command. [name] segments are dynamic and
become positional arguments, which also answer to --name; an exported
positionals tuple claims more; every other property is a flag.
MCP tool names are flat, so clfly drops a dynamic segment in the middle of a path
from the name and adds it back as a required property; a dynamic segment at the
end is the command itself and keeps its name (down/[env].ts → down_env). Two
files that map to the same tool name stop the build with an error naming both.
commands/users/[id]/show.ts:
import { z } from "zod";
import type { Context } from "@clfly/core";
export const meta = { description: "Show a single user" };
export const args = z.object({
id: z.string().describe("User id"),
});
export default async function (opts: z.infer<typeof args>, ctx: Context) {
const user = { id: opts.id, status: "active" };
if (ctx.json) return user;
ctx.stdout.write(`${user.id}\t${user.status}\n`);
}
In development clfly walks the directory on each run, so a new file is a new
command with no build step. For a release, build bakes that walk into a
manifest with flags, positionals and schemas precomputed and each handler
behind a lazy import(). A shipped CLI does no scanning at startup, and the
completions read the same manifest. mcp serve runs over stdio or HTTP and
spools large results to .clfly/sessions/.