Fitz CLI builder: como typer, pero en el lenguaje

Construí herramientas CLI nativas en Fitz con @command, sin librería que instalar. Help auto-generado, flags con type coercion, positional args por convención, binario nativo a la salida. El mismo lenguaje que mueve servicios HTTP construye tus scripts.

¿Por qué un CLI builder en el lenguaje?

La mayoría del trabajo de CLI en Python vive en typer, click o argparse. Todas son librerías decentes; typer en particular es delicioso. La respuesta de Rust es clap. La de Go es cobra o urfave/cli. La de Node es commander.js o yargs. Cada lenguaje tiene una librería CLI. Cada una de ellas es una librería.

Una librería está bien hasta que te acordás que:

• Las convenciones de la librería se imponen al resto de tu código (decoradores, factory objects, DSLs de builder).
• El formato del help text es decisión de la librería, no del lenguaje.
• Distribuir el resultado necesita un packager (pyinstaller, pyox, Docker, etc.) arriba.
• El comportamiento cross-platform depende de la cobertura de la librería, no del lenguaje.
• Agregar un --flag es cambiar la signature de una función más una llamada a decorador más quizás un objeto de config.

¿Qué pasaría si el mismo compilador que produce tu server HTTP también produce tus CLI tools, con el mismo type checker, el mismo async/await, el mismo Result<T> para errores, el mismo binario nativo como output?

Ese es el CLI builder de Fitz.

El hello-world completo

// main.fitz
@command("greet", desc="Saludar a una persona")
fn greet(name: Str, loud: Bool = false, count: Int = 1) -> Int {
    let n = count
    while n > 0 {
        if loud {
            print("HOLA, {name}!")
        } else {
            print("hola, {name}")
        }
        n = n - 1
    }
    return 0
}

Corrélo local durante el desarrollo:

$ fitz run main.fitz greet Ada
hola, Ada

$ fitz run main.fitz greet Ada --loud --count 3
HOLA, Ada!
HOLA, Ada!
HOLA, Ada!

Compilá a un binario self-contained:

$ fitz build
$ ls -lh ./greeter
-rwxr-xr-x  1  user  user   5.2M  Jun  5 14:00 ./greeter

$ ./greeter greet Ada --loud
HOLA, Ada!

Binario nativo de 5 MB, estáticamente linkeado excepto libc. Sin pyinstaller. Sin pyz. Sin intérprete Python en la máquina destino.

La convención: sin decoradores @arg/@flag

typer y click te piden que marques cada parámetro con un decorador que diga "esto es positional argument" o "esto es flag". Fitz usa una convención que cubre el mismo terreno sin la verbosidad:

• Param sin default → positional argument requerido (mybin greet <name>).
• Param con default → flag (--name <value>, o --loud para flags Bool).
• Bool = false → flag bool (--loud lo activa, sin valor).
• Int = N, Float = X, Str = "..." → flag con valor (--count 3).

La signature fn greet(name: Str, loud: Bool = false, count: Int = 1) -> Int le dice al compilador exactamente:

Param	Convención	CLI
name: Str	sin default → positional	greet <name>
loud: Bool = false	bool con default → flag	--loud (presencia = true)
count: Int = 1	int con default → flag con valor	--count 3

El trade-off: no podés tener positional optional args. Si querés uno, declaralo Str? (nullable) y hacé match en el body — el shape queda bien, el body maneja el caso missing explícito.

Conviví con este trade-off una semana antes de empezar a escribir CLIs en Fitz en lugar de typer, y no volví. La signature es la definición del CLI.

El help es auto-generado

$ ./mybin --help
USAGE:
    mybin <command> [ARGS] [OPTIONS]

COMMANDS:
    greet    Saludar a una persona

$ ./mybin greet --help
USAGE:
    mybin greet <name> [OPTIONS]

ARGUMENTS:
    <name>     (requerido)

OPTIONS:
    --loud, -l           default: false
    --count, -c <count>  default: 1
    -h, --help           mostrar este help

Short flags (-l, -c) se auto-derivan de la primera letra de la long flag. Si dos flags colisionarían en la misma letra, el compilador te avisa en build time (no en runtime, no cuando el user lo descubre):

✗ @command("greet") short flag conflict: `--loud` y `--limit`
  comparten primera letra `-l`. Renombrá una, u opt-out una con
  `@flag(short=null)`.

El formateo del output sigue convenciones de clap porque clap ya optimizó esto; no tiene sentido reinventarlo.

Multi-command dispatch

@command("greet", desc="Saludar a una persona")
fn greet(name: Str) -> Int { print("hola, {name}"); return 0 }

@command("add", desc="Sumar dos números")
fn add(a: Int, b: Int) -> Int { print("{a + b}"); return 0 }

@command("status", desc="Chequear estado del servicio")
async fn status(url: Str = "http://localhost:8080") -> Int {
    // ... llamada HTTP a la URL ...
    return 0
}

$ ./mybin --help
COMMANDS:
    greet     Saludar a una persona
    add       Sumar dos números
    status    Chequear estado del servicio

$ ./mybin add 21 21
42

$ ./mybin status --url http://prod.example.com
✓ healthy

El dispatch se genera en build time. No hay tabla de lookup de comandos en runtime que mantener.

Async nativo, porque por qué no

El comando status de arriba es async. El compilador lo detecta y envuelve el dispatch en #[tokio::main] automáticamente:

@command("fetch", desc="Traer una URL e imprimir el body")
async fn fetch(url: Str) -> Int {
    // Asumí que `http.get` fuera built-in (todavía no lo es; esto es ilustrativo).
    let body = http.get(url).await?
    print(body)
    return 0
}

El mismo async/await que usás en handlers HTTP funciona en CLI commands. Sin boilerplate de asyncio.run(). Sin "este comando es async, ese otro no, por favor no mezcles". Solo async fn cuando lo querés.

Exit codes

Las CLI tools viven y mueren por exit codes. La convención es POSIX:

• 0 — éxito.
• 1+ — retornado por el handler explícitamente.
• 2 — error de parsing del CLI (flag desconocida, type incorrecto, positional faltante).

@command("validate", desc="Chequear un archivo")
fn validate(path: Str) -> Int {
    let contents = read_file(path)
    if (contents.starts_with("FAIL")) {
        print("validación falló")
        return 1   // distinto de error interno
    }
    return 0
}

$ ./mybin validate ok.txt
$ echo $?
0

$ ./mybin validate fail.txt
validación falló
$ echo $?
1

$ ./mybin validate
✗ greet: missing positional argument `<path>`
$ echo $?
2

El parser CLI maneja los errores de parsing. Tu código maneja los errores de negocio. Limpio.

El poder completo del lenguaje

Acá es donde el approach de Fitz paga en una forma que typer no puede: tenés el lenguaje entero a tu disposición en CLI tools, no solo funciones y prints.

CLI tools con el ORM

¿Necesitás un CLI de admin de DB? Es el mismo ORM que el servicio HTTP:

@command("list-users", desc="Imprimir todos los users")
async fn list_users(db: DbConn) -> Int {
    let users = User.all(db).await
    for u in users {
        print("#{u.id}\t{u.email}\t{u.role}")
    }
    return 0
}

@command("delete-user", desc="Borrar un user por email")
async fn delete_user(db: DbConn, email: Str, force: Bool = false) -> Int {
    if not force {
        print("Usá --force para borrar de verdad")
        return 1
    }
    User.where(fn(u) => u.email == email).delete(db).await
    print("borrado")
    return 0
}

La inyección de DbConn funciona igual que en handlers HTTP. Closure-to-SQL en .where(...) funciona. Eager loading funciona. Las migraciones de fitz db diff/migrate funcionan. El CLI tool tiene el mismo acceso a tu capa de datos que el API server, con la misma seguridad de tipos.

CLI con llamadas HTTP

¿Querés un CLI que hable con tu propio API? Mismo lenguaje, sin SDK separado:

@command("ping-prod", desc="Pegarle al /healthz de prod")
async fn ping_prod() -> Int {
    let url = env_or("PROD_URL", "https://api.example.com")
    // ... usá la stdlib o `from python import requests` etc ...
    return 0
}

CLI como wrapper de herramientas Python

¿Necesitás envolver una herramienta Python pero con mejor UX? El interop Python está en Fitz:

from python import subprocess

@command("backup-db", desc="Correr pg_dump y subir a S3")
async fn backup_db(db_url: Str, bucket: Str) -> Int {
    let dump_cmd = "pg_dump {db_url} > backup.sql"
    subprocess.run(dump_cmd, shell=true).await?
    // ... upload a S3 ...
    return 0
}

El CLI está en Fitz. La llamada a pg_dump es shell. El upload a S3 podría ser Python con boto3 (from python import boto3). Un binario, tres ecosistemas compuestos.

CLI con config + secrets

El mismo Secret<T> y config(...) de la Parte 3 funcionan en CLI tools:

@command("deploy", desc="Empujar un release")
async fn deploy(env: Str = "staging") -> Int {
    let api_key: Secret<Str> = secret("DEPLOY_API_KEY")
    let endpoint: Str = config("DEPLOY_ENDPOINT", "https://deploy.internal")
    // ... usá api_key.expose() en el request ...
    return 0
}

api_key nunca leakea a logs incluso si el path de error del comando deploy imprime el config map. Las mismas reglas de redacción de los servicios HTTP aplican acá.

Boilerplate cli-tool

El repo tiene un boilerplate para proyectos CLI en boilerplates/cli-tool/. Trae tres comandos como starter:

• report — genera un sumario de datos.
• count — cuenta items.
• regions — lista categorías.

fitz new my-cli --template cli-tool
cd my-cli
fitz dev

Hot reload también funciona en CLI mode — fitz dev watchea el source, mata y respawnea cuando guardás.

Lo que no está en la caja

• Prompts interactivos (pensá inquirer / click.prompt). Fitz todavía no tiene readers de stdin estilo read_line en el core. Por ahora, aceptá una flag y alimentala vía env o stdin piped.
• TUI (terminal UI con control de cursor). Fuera de scope.
• Generación de shell completion (bash/zsh/fish). No se genera automático todavía. El approach del archivo _complete escrito a mano sigue funcionando.
• --no-foo para flags Bool = true. Bools default a false; si querés una flag que default a true y vos opt-out, la convención es invertir el booleano en tu lógica de negocio por ahora. Trackeada como deuda menor.

Si algo de esto te bloquea, abrí un issue. O son chicos para agregar o ya están en progreso.

Por qué importa

Cada developer que construye servicios web también termina escribiendo CLI tools. Migraciones para correr, imports ad-hoc, smoke tests, scripts de deploy, acciones admin, exports de data. La elección hoy en la mayoría de los lenguajes es:

• Mismo lenguaje que el servicio, con una librería CLI separada (Python: typer).
• Bash / shell script que llama a tu servicio vía HTTP (perdés toda la seguridad de tipos).
• Un lenguaje separado para ops (binarios Go al lado de un servicio Python — está bien, pero dos lenguajes para mantener).

Fitz propone una cuarta: mismo compilador, mismo type checker, mismo ORM, mismo async, mismo formato de binario. Tus CLI tools viven en el mismo repo, comparten el mismo type User, le pegan al mismo Postgres con la misma lógica de conexión.

Podés escribir mybin migrate y mybin reset-test-db en el mismo archivo .fitz que tus handlers @get("/users") si querés. O dividir en comandos separados por binario. La elección es tuya, no de la librería.

Probalo:

# Linux / macOS / WSL
curl -sSf https://thegreekman76.github.io/fitz/install.sh | sh

# Windows (PowerShell)
irm https://thegreekman76.github.io/fitz/install.ps1 | iex

# Reabrí la terminal, después:
fitz new micli --template cli-tool
cd micli
fitz run main.fitz greet --help
fitz build
./micli greet Ada --loud --count 3

Para VSCode (recomendado para editar — hover con tipos, autocomplete, signature help): bajá el fitz-lang-<plataforma>.vsix desde la página de releases y code --install-extension fitz-lang-<plataforma>.vsix --force. El Language Server viene incluido.

Vas a tener un binario nativo self-contained en tu pwd en menos de cinco minutos.

Repo: github.com/Thegreekman76/fitz
Boilerplate cli-tool: github.com/Thegreekman76/fitz/tree/main/boilerplates/cli-tool
Docs y curso: thegreekman76.github.io/fitz
Capítulo de la guía sobre CLI: thegreekman76.github.io/fitz/guide/#33-cli
Roadmap: docs/roadmap.md
CHANGELOG: CHANGELOG.md
Issues: github.com/Thegreekman76/fitz/issues

Hasta la próxima.