#cmder

• Executable root commands and nested subcommands with raising callbacks.
• String, Boolean and checked Int32 options, plus positional arguments.
• Explicit global options shared with descendants; other arguments stay local.
• Immutable command definitions and parsed invocations with value provenance.
• Help, version, JSON definitions and Bash/Zsh/Fish completion scripts.

#Differences from admiral 0.1.2

• Option helpers accept direct values for short and default, and definitions and contexts are read-only.
• Root commands can have callbacks and positional arguments. Callbacks can propagate errors to the application.
• Options are local by default; set global=true to make an option available to descendant commands. Required local options apply only to the selected command.
• parse returns structured outcomes without executing callbacks or performing process I/O. A parsed invocation can be inspected, overridden and dispatched; argument provenance is available through source_of.
• Command definitions are validated at construction, and integer options are checked for syntax and Int32 range during parsing.
• JSON definitions include positional order and cardinality; generated help and shell completions reflect command and option scopes.

#Installation

moon add hustcer/cmder

import {
  "hustcer/cmder",
}
pkgtype(kind: "executable")

#Quick Start

///|
fn main raise {
  let app = @cmder.cli(
    name="hello",
    version="1.0.0",
    options=[
      @cmder.string("name", short='n', required=true),
      @cmder.int("count", short='c', default=1),
      @cmder.bool("loud", short='l'),
    ],
    examples=["hello -n Alice", "hello -n Bob -l -c 2"],
    run=ctx => {
      let name = ctx.get_string_required("name")
      let count = ctx.get_int_required("count")
      for _ in 0..<count {
        let message = "Hello, \{name}!"
        println(if ctx.get_bool("loud") { message.to_upper() } else { message })
      }
    },
  )
  app.run_or_exit()
}

$ hello -n Alice
Hello, Alice!
$ hello -n Bob -l -c 2
HELLO, BOB!
HELLO, BOB!

#Options and Positional Arguments

let options = [
  @cmder.string("config", short='f', required=true),
  @cmder.string("host", default="localhost"),
  @cmder.int("port", short='p', default=3000),
  @cmder.bool("verbose", short='v', global=true),
]

let app = @cmder.cli(
  name="copy",
  positionals=[
    @cmder.positional("source", required=true),
    @cmder.positional("destinations"),
  ],
  run=ctx => {
    println(ctx.get_string_required("source"))
    println(ctx.get_strings("destinations").join(", "))
  },
)

#Subcommands and Scope

let app = @cmder.cli(
  name="myapp",
  options=[@cmder.bool("verbose", short='v', global=true)],
  commands=[
    @cmder.command(
      name="db",
      options=[@cmder.string("region", default="west", global=true)],
      subcommands=[
        @cmder.command(name="migrate", options=[@cmder.bool("dry-run")], run=ctx => {
          if ctx.get_bool("verbose") {
            println("Starting migration")
          }
          println(ctx.get_string_required("region"))
          println(if ctx.get_bool("dry-run") { "Preview" } else { "Apply" })
        }),
      ],
    ),
  ],
)

#Reading Arguments and Errors

#Parsing, Host Checks and Dispatch

let app = @cmder.cli(name="app", options=[@cmder.int("count", default=1)], run=ctx => {
  println(ctx.get_int_required("count"))
})
match app.parse(argv=["--count", "2"]) {
  Parsed(call) => {
    // Perform host checks before execution.
    let edited = call.with_overrides({
      "count": @cmder.ArgumentValue::Integer(3),
    })
    edited.dispatch()
  }
  Help(text) | Version(text) => println(text)
  Failed(error) => {
    eprintln(error.message())
    @env.exit(1)
  }
}

#Exporting Definitions and Completion

let schema_text = app.render_schema()
let schema_json = app.render_schema_json()
let help = app.render_help(command_path=["db", "migrate"])
let bash_script = app.render_bash_completion()
let zsh_script = app.render_zsh_completion()
let fish_script = app.render_fish_completion()

source ./myapp.bash

autoload -Uz compinit
compinit
source ./_myapp

source ./myapp.fish

#Migration from 0.3

#Local Development

moon check --deny-warn --target native
moon test --target native
moon test --target js
moon test --target wasm-gc
moon run src/examples/cli --target native -- greet -n Alice
moon run src/examples/cli --target native -- db migrate up --dry-run
moon run src/examples/cli --target native -- --schema
nu scripts/check-cli.nu
nu scripts/check-completions.nu
nu scripts/check-readme.nu

#Acknowledgments and License