← Projects

clfly(active)

File-based routing for CLIs — one commands/ tree becomes CLI, completions, and MCP.

npm create @clfly mycli

clfly 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.

Status
published (@clfly/cli, @clfly/core, @clfly/create on npm)
Distribution
one commands/ tree → CLI, shell completions, MCP serve

One schema, three readers

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.

command fileJSON SchemaargvcompletionsMCP
Figure 1 One command file, three surfaces. clfly asks the file's schema for one draft-07 JSON Schema; the argv parser and help, the shell completions and the MCP tool definition are all read from that one document.

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.

The path is the address

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.

users[id]showdemo users 42 show(a)
users[id]showusers_show, input: id (string, required)(b)
Figure 2 The file commands/users/[id]/show.ts on two surfaces. (a) On the command line the [id] segment stays in place as a positional argument. (b) An MCP tool has a flat name, so the middle segment is dropped from it and comes back as a required string property.

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`);
}

Two routers, one tree

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/.