Crystal and Rust - JSON Schema in, CLI out

Your CLI is an API.
Why not treat it as one?

Jargon turns JSON Schema into a precise, user-friendly CLI. You get validation, defaults, subcommands, and completions with a single definition, delivered as clean JSON, in Crystal or Rust.

Get started See it run

MIT license

stdin JSON

$ref support

XDG friendly

ENV overrides

Schema defaults

Nested objects

Subcommands

Auto help

Shell completions

Typed parsing

Config loading

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "User name"
    },
    "age": {
      "type": "integer",
      "description": "User age",
      "default": 0
    },
    "verbose": {
      "type": "boolean",
      "short": "v"
    }
  },
  "required": ["name"]
}

type: object
properties:
  name:
    type: string
    description: User name
  age:
    type: integer
    description: User age
    default: 0
  verbose:
    type: boolean
    short: v
required:
  - name

schema.json

The schema becomes the interface

Define the data shape once and reuse it everywhere.

Define your schema

Describe data types, defaults, env overrides, and descriptions.

Parse with confidence

Jargon validates inputs and produces consistent JSON output.

Ship with polish

Automatic help, completions, and subcommands come built in.

Seeing is believing

A tiny demo script that shows parsing, nesting, and validation.

jargon-demo

live

Built for real-world CLIs

Jargon keeps the CLI surface area predictable, while still letting you express complex data shapes with nested objects and refs.

Schema-first validation

Required fields, enum constraints, and strict type checks are all derived from your JSON Schema.

XDG config aware

Loads config from standard XDG paths with project overrides.

Defaults & precedence

Schema defaults, config files, and env vars layer predictably.

Environment bindings

Map options to env vars and coerce types automatically.

Subcommands without ceremony

Compose nested sub-parsers, with a default command fallback.

Positional + variadic

Mix ordered arguments with a variadic tail for lists.

Flexible input styles

Accept --flags or bare key=value without extra parsing.

Nested object paths

Use dotted keys like user.name for deep objects.

Stdin JSON mode

Parse full JSON payloads via stdin with a single dash.

Help & hints

Auto-generated help plus typo suggestions for options.

Schema reuse

Share definitions via $ref and keep specs DRY.

Shell completions

Generate bash, zsh, and fish scripts from the same schema.

Completions that stay in sync

Generate scripts for bash, zsh, and fish straight from your schema.

One command per shell

Jargon can emit shell completion scripts without any extra tooling. Hook them into your install process or generate on demand.

bash zsh fish

cli = Jargon.cli("mycmd", json: schema)
puts cli.bash_completion
puts cli.zsh_completion
puts cli.fish_completion

let cli = Cli::from_json(&schema, "mycmd")?;
println!("{}", cli.completion_script(Shell::Bash));
println!("{}", cli.completion_script(Shell::Zsh));
println!("{}", cli.completion_script(Shell::Fish));

Designed for clarity

Help output reads like docs because descriptions come from the schema.

Succinct help, by design

Perfectly concise help messages that stay readable and focused. Deep dives belong in man pages, not in the CLI overview.

Usage: mycmd [options]

Options:
  -v, --verbose [default: false]
      Enable verbose logging
      --count=<integer> [default: 10]
      Number of retries
      --mode=<string>
      Operation mode

Get started in minutes

Add the shard or the crate, load a schema, and parse.

From dependency to CLI

Add Jargon to your shard.yml and run shards update, or add it to your Cargo.toml. Then define your schema, wire it up in your code (easy peasy), and enjoy a friendly CLI.

# shard.yml

dependencies:
  jargon:
    github: openbohemians/jargon.cr

# Cargo.toml

[dependencies.jargonaut]
git = "https://github.com/openbohemians/jargon.rs"

Get involved

Contribute, explore the docs, or ship Jargon in your next CLI.

Build with the community

Jargon is MIT-licensed and built to be hacked on. Open issues, send PRs, or browse the API docs to dive deeper.

Crystal repo Rust repo Crystal API docs Shard stats

Developer friendly

Schema-driven help, JSON output, and shell completions make it easy to ship polished command lines quickly.