Claptrap

Hello, ${claptrap_name}!

hello.sh

#!/usr/bin/env bash

set -euo pipefail

eval "$(claptrap --spec - -- "$@" <<'SPEC'
  name = "hello"
  [args]
  name = { short = 'n', long = "name", default-value = "world" }
SPEC
)"

echo "hello, ${claptrap_name}!"

$ ./hello.sh -n fuji
hello, fuji!

Features

Powered by Clap

Claptrap brings the full power of Clap command line parsing to shell scripts.

Declarative Specification

Command line interface specifications can be declared in toml, yaml or json and used as standalone files or embedded directly in scripts.

Run Anywhere

Supports bash, zsh, fish and PowerShell and can run on Linux, BSD, macOS, and Windows.

Beyond Parsing

Automatically generate shell completions, man pages, markdown documentation and template scripts.

Examples

Basic

A simple toml specification embedded in a bash script:

simple.sh

#!/usr/bin/env bash

set -euo pipefail

eval "$(claptrap --spec - -- "$@" <<'SPEC'
  name = "simple"
  version = "0.1.0"
  arg-required-else-help = true
  [args]
  format = { short = "f", long = "format", required = true, value-parser = ["toml", "yaml", "json"] }
  exts = { long = "extensions", num-args = "1..", default-values = ["txt", "sh", "rs"] }
SPEC
)"

echo "format: $claptrap_format"
for i in "${!claptrap_exts[@]}"; do
  echo "extensions[$i]: ${claptrap_exts[$i]}"
done

Show usage:

$ ./hello.sh
Usage: hello [OPTIONS] --format <format>

Options:
  -f, --format <format>       [possible values: toml, yaml, json]
      --extensions <exts>...  [default: txt sh rs]
  -h, --help                  Print help
  -V, --version               Print version

Parse arguments:

$ ./hello.sh -f json
protocol: json
extensions[0]: txt
extensions[1]: sh
extensions[2]: rs

Error handling:

$ ./hello.sh -f yml --extensions md ts js
error: invalid value 'yml' for '--format <format>'
  [possible values: toml, yaml, json]

  tip: a similar value exists: 'yaml'

For more information, try '--help'.

Subcommands

A standalone toml specification with subcommands:

name = "docker"
about = "A self-sufficient runtime for containers"
version = "Docker version 27.5.1, build 9f9e405"
arg-required-else-help = true

[[subcommands]]
name = "run"
about = "Create and run a new container from an image"
[subcommands.args]
interactive = { short = 'i', long = "interactive", help = "Keep STDIN open even if not attached", action = "set-true" }
tty = { short = 't', long = "tty", help = "Allocate a pseudo-TTY", action = "set-true" }
volume = { short = 'v', long = "volume", value-name = "list", help = "Bind mount a volume", action = "append", num-args = 1 }
image = { value-name = "IMAGE", help = "The image to run", required = true, index = 1 }

Use it in a script with the claptrap Docker image:

docker.sh

#!/usr/bin/env bash

set -euo pipefail

eval "$(docker run -it -v ${PWD}:/data fujiapple/claptrap:latest --spec docker.toml -- "$@")"

Show usage:

$ ./docker.sh run --help
Create and run a new container from an image

Usage: docker run [OPTIONS] <IMAGE>

Arguments:
  <IMAGE>  The image to run

Options:
  -i, --interactive    Keep STDIN open even if not attached
  -t, --tty            Allocate a pseudo-TTY
  -v, --volume <list>  Bind mount a volume
  -h, --help           Print help

Formats

The hello example specification written in json and embedded in a script:

#!/usr/bin/env bash

set -euo pipefail

eval "$(claptrap --spec - -- "$@" <<'SPEC'
  {
    "name": "hello",
    "args": {
      "name": {
        "default-value": "world",
        "long": "name",
        "short": "n"
      }
    }
  }
SPEC
)"

echo "hello, ${claptrap_name}!"

A standalone specification written in yaml:

name: pacman
about: package manager utility
version: 5.2.1
subcommand-required: true
arg-required-else-help: true
subcommands:
- name: query
  short-flag: Q
  long-flag: query
  about: Query the package database.
  args:
    search:
      short: s
      long: search
      help: search locally installed packages for matching strings
      conflicts-with: info
      action: set
      num-args: 1..
    info:
      long: info
      short: i
      conflicts-with: search
      help: view package information
      action: set
      num-args: 1..
- name: sync
  short-flag: S
  long-flag: sync
  about: Synchronize packages.
  args:
    search:
      short: s
      long: search
      conflicts-with: info
      action: set
      num-args: 1..
      help: search remote repositories for matching strings
    info:
      long: info
      conflicts-with: search
      short: i
      action: set-true
      help: view package information
    package:
      help: packages
      required-unless-present: search
      action: set
      num-args: 1..

Use it in a script:

pacman.sh

#!/usr/bin/env bash

set -euo pipefail

eval "$(claptrap --spec pacman.spec -- "$@")"

echo "claptrap__subcommand: ${claptrap__subcommand}"
case "${claptrap__subcommand}" in
  "query")
    if [ -n "${claptrap_query_search+x}" ]; then
      for i in "${!claptrap_query_search[@]}"; do
        echo "claptrap_query_search[$i]: ${claptrap_query_search[$i]}"
      done
    fi
    if [ -n "${claptrap_query_info+x}" ]; then
      for i in "${!claptrap_query_info[@]}"; do
        echo "claptrap_query_info[$i]: ${claptrap_query_info[$i]}"
      done
    fi
    ;;
  "sync")
    if [ -n "${claptrap_sync_search+x}" ]; then
      for i in "${!claptrap_sync_search[@]}"; do
        echo "claptrap_sync_search[$i]: ${claptrap_sync_search[$i]}"
      done
    fi
    if [ -n "${claptrap_sync_info+x}" ]; then
      echo "claptrap_sync_info: ${claptrap_sync_info}"
    fi
    if [ -n "${claptrap_sync_package+x}" ]; then
      for i in "${!claptrap_sync_package[@]}"; do
        echo "claptrap_sync_package[$i]: ${claptrap_sync_package[$i]}"
      done
    fi
    ;;
esac

Parse some arguments:

./pacman.sh --sync -i claptrap trippy
claptrap__subcommand: sync
claptrap_sync_info: true
claptrap_sync_package[0]: claptrap
claptrap_sync_package[1]: trippy

Templates

Generate a template bash shell script from a hello.toml spec:

name = "hello"
[args]
name = { short = 'n', long = "name", default-value = "world" }

$ claptrap script --spec hello.toml bash -o hello.sh

Outputs:

hello.sh

#!/usr/bin/env bash

set -euo pipefail

if ! command -v claptrap &> /dev/null; then
    echo "claptrap command not found. Please install it first, see https://claptrap.sh for instructions."
    exit 1
fi

eval "$(claptrap --spec examples/pacman/spec.toml -- "$@")"

if [ -n "${claptrap_name+x}" ]; then
  echo "claptrap_name: ${claptrap_name}"
fi

Run the script:

$ ./hello.sh
claptrap_name: world

Generate

Generate man pages:

$ claptrap man --spec myapp.toml -o myapp.roff

Generate shell completions:

$ claptrap completion --spec myapp.json --shell bash -o myapp.bash
$ claptrap completion --spec myapp.json --shell zsh -o myapp.zsh
$ claptrap completion --spec myapp.json --shell fish -o myapp.fish
$ claptrap completion --spec myapp.json --shell powershell -o myapp.ps1

Generate markdown documentation:

$ claptrap doc --spec myapp.toml -o myapp.md

Generate JSON schema for the specification format:

$ claptrap schema -o schema.json

Rust

The claptrap crate can be used in Rust applications to parse command line arguments using a specification file.

fn main() {
    let spec = r#"
          name = "hello"
          [args]
          name = { short = 'n', long = "name", default-value = "world" }
        "#;
    let cmd: claptrap::Command = toml::from_str(spec).unwrap();
    let clap_cmd = clap::Command::from(cmd);
    let matches = clap_cmd.get_matches();
    let name = matches.get_one::<String>("name").unwrap();
    println!("Hello, {}!", name);
}