Technical previewShare feedback
Fireargs
FireargsModern CLI builder

Open source · MIT License

Typed CLIs for
humans, agents
and scripts.

Define each command with an input and an output schema. Get --help for humans, an MCP-shaped --llms manifest for agents and --json for scripts, all from one definition.

$ shipit deploy --help
Usage: shipit deploy [options] <env>

Deploy the current build to an environment.

Arguments:
  env                   Target environment. (choices: "staging", "production")

Options:
  --json [value]        write output as JSON; pass a JSON string to also drive
                        input
  --llms                print this command's schema (name, input, output) as
                        JSON for LLM tool-use
  -r, --region <value>  Cloud region. (default: "eu-west-1", env: SHIPIT_REGION)
  --replicas <value>    Instances to run. (default: 2)
  -p, --preview         Plan without applying. (default: false)
  -h, --help            display help for command

Defined with a schema

deploy.ts
env: f.argument().enum(envs),
region: f.option({ short: "r" })

Still just pydantic and click

Fireargs fills in the boring parts and gets out of the way. Your models and your click setup stay yours.

  • Plain pydantic models

    Inputs and outputs are ordinary BaseModel classes. Share fields as Annotated aliases and groups as mixins; there is no DSL to learn.

  • A real click command

    Every command is a click Command and every program a Group. Contexts, plugins and the rest of click's API stay within reach.

  • Programs all the way down

    Group commands with Program(router=...) and nest programs inside programs. See Programs.

shipit
cli.py
commands/
├─ deploy.py
└─ db/
   ├─ __init__.py
   └─ migrate.py

$ shipit db migrate --json
$ shipit --llms

The layout is only an example: routers take imported commands, not folders.

From schema to shipping CLI

Sane defaults, every escape hatch, no extra plumbing.

Schema-first

Inputs and outputs are pydantic models, zod schemas or serde structs. Descriptions, defaults, choices, and lists propagate to the CLI automatically.

Validated end-to-end

Every input is validated before your handler runs and every output before it ships. One source of truth for types and runtime.

Fully composable

Share arguments, options and groups of them across commands. Group leaves into programs and nest programs in programs — same shape at every level.

Built-in --json

Every command takes JSON in and emits JSON out via --json. Drive it from a script or an agent — same binary.

Built-in --llms

Each binary publishes an MCP-shaped tools/list manifest. LLM agents read it and call straight back through --json.

Built on proven parsers

Every command is parsed by its language's go-to CLI library, so it behaves like any other CLI there — fireargs just fills in the boring parts.

One schema, every interface

The same pydantic model drives --help, --json, and the LLM manifest.

greet.py
from typing import Annotated
from pydantic import BaseModel
from fireargs import Argument, Option, Program, command

# Composable arguments and options
Name = Annotated[str, Argument(description="Who to greet")]
Times = Annotated[int, Option(default=1, ge=1)]


# Typed input, validated on every run
class GreetInput(BaseModel):
    name: Name
    times: Times


# Typed output, validated on every run
class GreetOutput(BaseModel):
    greeting: str


# A click command, typed from the handler's annotations
@command(description="Greet politely")
def greet(input: GreetInput) -> GreetOutput:
    words = [f"hello {input.name}"] * input.times
    return GreetOutput(greeting=" ".join(words))


# Output for humans; --json prints the data instead
@greet.render
def render_greeting(output: GreetOutput) -> str:
    return output.greeting


# Composable commands: a router of leaves and nested programs
cli = Program(name="myapp", router={"greet": greet})

# Use as a normal click group, e.g. configure or apply plugins
if __name__ == "__main__":
    cli()
terminal
# For humans
$ myapp greet world --times 2
hello world hello world

# For agents
$ myapp --llms
{
  "tools": [
    { "name": "help", ... },
    {
      "name": "greet",
      "description": "Greet politely",
      "inputSchema": { ... },
      "outputSchema": { ... }
    }
  ]
}

# For scripts
$ myapp greet --json '{"name":"world"}'
{
  "greeting": "hello world"
}

Descriptions surface in --help and the JSON Schema.

Defaults, choices, and optionality flow to click automatically.

Every leaf gets --json '<value>' and --llms for free.

Stop hand-rolling argument parsers. Write a schema.

Install, write a command, ship a CLI that humans, agents, and scripts can all call.