#admiral

• Typed option helpers (string, bool, int, int64, uint, uint64, double, positional)
• Optional configuration loading through independent config keys
• Async run callbacks for commands and nested subcommands
• Structured JSON schema output for AI agent integration
• Shell completion generation (bash, zsh, fish)
• Auto-generated --help / --version, including help for incomplete command paths

#Install

import {
  "totto2727/admiral@0.4.0",
  "moonbitlang/async@0.19.2",
}

preferred_target = "native"

import {
  "totto2727/admiral" @admiral,
  "moonbitlang/async",
}

#Quick Start

async fn main {
  let name = @admiral.string(
    "name",
    short='n',
    description="Name to greet",
    env="ADMIRAL_NAME",
    config="name",
    required=true,
  )
  let verbose = @admiral.bool("verbose", short='v', description="Verbose output")
  let count = @admiral.int("count", short='c', description="Repeat count", default=Some(1))
  let app = @admiral.cli(
    name="myapp",
    version="1.0.0",
    description="My CLI tool",
    commands=[
      @admiral.command(
        name="greet",
        description="Greet someone",
        options=[name, verbose, count],
        examples=["myapp greet --name Alice", "myapp greet -n Bob -v -c 3"],
        run=Some(async fn(ctx) {
          let name_value = try { ctx.get_string_required(name) } catch { _ => return }
          let is_verbose = ctx.get_bool(verbose)
          let count_value = match ctx.get_int(count) { Some(n) => n; None => 1 }
          for i = 0; i < count_value; i = i + 1 {
            if is_verbose {
              println("Hello, " + name_value + "! (" + (i + 1).to_string() + ")")
            } else {
              println("Hello, " + name_value + "!")
            }
          }
        }),
      ),
    ],
  )
  app.run()
}

$ myapp greet --name Alice
Hello, Alice!

$ myapp greet -n Bob -v -c 3
Hello, Bob! (1)
Hello, Bob! (2)
Hello, Bob! (3)

$ myapp --help
Usage: myapp [command]

My CLI tool

Commands:
  greet  Greet someone

Options:
  -h, --help     Show help information.
  -V, --version  Show version information.

#Guide

#Defining Options

// String option: --name value or -n value
@admiral.string("name", short='n', description="User name", env="MYAPP_NAME", config="name", required=true)

// Bool flag: --verbose or -v
@admiral.bool("verbose", short='v', description="Verbose output", env="MYAPP_VERBOSE", config="verbose")

// Int option: --port 8080 or -p 8080
@admiral.int("port", short='p', description="Port number", env="MYAPP_PORT", config="port", default=Some(3000))

// Scalar position: file
@admiral.position_string("file", description="Input file", config="input", required=true)

// Variadic position: file...
@admiral.position_strings("files", description="Input files")

#Environment Variables

@admiral.string("name", env="MYAPP_NAME")
@admiral.bool("verbose", env="MYAPP_VERBOSE")
@admiral.int("port", env="MYAPP_PORT")

app.run(
  argv=Some(["serve"]),
  env={
    "MYAPP_PORT": "8080",
    "MYAPP_VERBOSE": "true",
  },
)

// An empty map prevents ambient process variables from affecting the parse.
app.run(argv=Some(["serve"]), env=Map([]))

#Configuration

fn load_config() -> Map[String, Json] raise @admiral.ConfigLoadFailure {
  {
    "port": (7000).to_json(),
    "verbose": (true).to_json(),
    "tags": ["release", "signed"].to_json(),
  }
}

let app = @admiral.cli(
  name="myapp",
  load_config=Some(load_config),
  commands=[...],
)

#Reading Values from Context

let verbose = @admiral.bool("verbose")
let name = @admiral.string("name", required=true)
let port = @admiral.int("port", required=true)
let input = @admiral.position_int("input", required=true)

// Register definitions with command(options=[verbose, name, port], positionals=[input]).
run=Some(async fn(ctx) {
  // Bool — returns false if not specified
  let is_verbose = ctx.get_bool(verbose)

  // String — returns None if not specified
  let name_value = ctx.get_string(name)       // String?

  // String (required) — raises if missing
  let name_value = try { ctx.get_string_required(name) } catch { _ => return }

  // Int — parses string value to Int, returns None if missing or invalid
  let port_value = ctx.get_int(port)           // Int?

  // Int (required) — raises if missing or not a valid integer
  let port_value = try { ctx.get_int_required(port) } catch { _ => return }

  // The same getter accepts PositionDef[Int]
  let input_value = try { ctx.get_int_required(input) } catch { _ => return }
})

#Nested Subcommands

let dry_run = @admiral.bool("dry-run", description="Preview without applying")
let up_steps = @admiral.int("steps", short='s', description="Number of steps")
let down_steps = @admiral.int("steps", short='s', description="Steps to rollback", default=Some(1))
let seed_file = @admiral.string("file", short='f', description="Seed file", default=Some("seeds/default.sql"))

let app = @admiral.cli(
  name="myapp",
  commands=[
    @admiral.command(
      name="db",
      description="Database commands",
      subcommands=[
        @admiral.command(
          name="migrate",
          description="Run migrations",
          subcommands=[
            @admiral.command(
              name="up",
              description="Apply pending migrations",
              options=[dry_run, up_steps],
              examples=[
                "myapp db migrate up",
                "myapp db migrate up --dry-run",
                "myapp db migrate up --steps 5",
              ],
              run=Some(async fn(ctx) {
                if ctx.get_bool(dry_run) {
                  println("[DRY RUN] Would apply migrations")
                } else {
                  match ctx.get_int(up_steps) {
                    Some(n) => println("Applying " + n.to_string() + " migrations...")
                    None => println("Applying all pending migrations...")
                  }
                }
              }),
            ),
            @admiral.command(
              name="down",
              description="Rollback migrations",
              options=[down_steps],
              run=Some(async fn(ctx) {
                let steps = match ctx.get_int(down_steps) { Some(n) => n; None => 1 }
                println("Rolling back " + steps.to_string() + " migration(s)...")
              }),
            ),
          ],
        ),
        @admiral.command(
          name="seed",
          description="Seed the database",
          options=[seed_file],
          run=Some(async fn(ctx) {
            let file = match ctx.get_string(seed_file) { Some(f) => f; None => "seeds/default.sql" }
            println("Seeding from: " + file)
          }),
        ),
      ],
    ),
  ],
)

$ myapp db migrate up --dry-run
[DRY RUN] Would apply migrations

$ myapp db migrate down --steps 3
Rolling back 3 migration(s)...

$ myapp db seed --file custom.sql
Seeding from: custom.sql

#Positional Arguments

let files = @admiral.position_strings("files", description="Files to concatenate")

@admiral.command(
  name="cat",
  description="Concatenate files",
  positionals=[files],
  run=Some(async fn(ctx) {
    let file_values = ctx.get_strings(files)
    for file in file_values {
      println("Reading: " + file)
    }
  }),
)

$ myapp cat a.txt b.txt c.txt
Reading: a.txt
Reading: b.txt
Reading: c.txt

#Testing with Explicit argv

// In async tests, pass argv explicitly:
async test {
  app.run(argv=Some(["greet", "--name", "alice"]))
}

// In production, omit argv to use process args:
app.run()

#Structured Schema Output

println(app.render_schema())         // -> JSON string
let json = app.render_schema_json()  // -> Json value

{
  "name": "myapp",
  "version": "1.0.0",
  "description": "My CLI tool",
  "commands": {
    "greet": {
      "description": "Greet someone",
      "options": {
        "name": {
          "type": "string",
          "description": "Name to greet",
          "required": true,
          "short": "n",
          "env": "ADMIRAL_NAME"
        },
        "verbose": { "type": "bool", "description": "Verbose output", "required": false, "short": "v" },
        "count": { "type": "int", "description": "Repeat count", "required": false, "short": "c", "default": "1" }
      },
      "examples": ["myapp greet --name Alice", "myapp greet -n Bob -v -c 3"]
    },
    "db": {
      "description": "Database commands",
      "commands": {
        "migrate": {
          "description": "Run migrations",
          "commands": {
            "up": {
              "description": "Apply pending migrations",
              "options": {
                "dry-run": { "type": "bool", "description": "Preview without applying", "required": false },
                "steps": { "type": "int", "description": "Number of steps", "required": false, "short": "s" }
              },
              "examples": ["myapp db migrate up", "myapp db migrate up --dry-run"]
            }
          }
        }
      }
    }
  }
}

#Shell Completion

// Bash
println(app.render_bash_completion())

// Zsh
println(app.render_zsh_completion())

// Fish
println(app.render_fish_completion())

let shell = @admiral.string(
  "shell",
  short='s',
  description="Shell type (bash, zsh, fish)",
  required=true,
)

@admiral.command(
  name="completion",
  description="Generate shell completion script",
  options=[shell],
  run=Some(async fn(ctx) {
    match ctx.get_string(shell) {
      Some("bash") => println(app.render_bash_completion())
      Some("zsh") => println(app.render_zsh_completion())
      Some("fish") => println(app.render_fish_completion())
      _ => println("Unsupported shell. Use: bash, zsh, fish")
    }
  }),
)

# Bash: add to ~/.bashrc
eval "$(myapp completion --shell bash)"

# Zsh: add to ~/.zshrc
eval "$(myapp completion --shell zsh)"

# Fish: save to completions dir
myapp completion --shell fish > ~/.config/fish/completions/myapp.fish

#API Reference

#Option Helpers

#Position Helpers

#Command Definition

#Context Methods

#Schema & Completion

#Running

app.run()                                    // use process args
app.run(argv=Some(["greet", "--name", "x"])) // explicit args (for testing)
app.run(env={ "ADMIRAL_NAME": "Env" })       // explicit environment map
app.run(
  argv=Some(["greet"]),
  env={ "ADMIRAL_NAME": "Env" },
)

#Targets

#License