example.yaml

# Fictional example of a program with subcommands.

prog: "net"
help: "Network utility program"
options:
  - option_strings: ["-h", "--help"]
    help: "show this help message and exit"
---
prog: "net configure"
aliases: ["setup"]
help: "Configure a network interface"
options:
  - option_strings: ["--mode", "-m"]
    metavar: "mode"
    help: "Specify the mode for the interface"
    complete: ["choices", {"static": "Use static IP mode", "dhcp": "Use DHCP mode"}]

  - option_strings: ["--ip"]
    metavar: "IP"
    help: "Set IP address (for --mode=static)"
    complete: ["none"]
    # Only show this option if --mode=static, or -m static
    when: "option_is --mode -m -- static"

positionals:
  - number: 1
    metavar: "interface"
    help: "Specify interface"
    # Complete files that are found in /sys/class/net
    complete: ["file", {"directory": "/sys/class/net"}]
---
prog: "net monitor"
aliases: ["watch"]
help: "Monitor network"
options:
  - option_strings: ["--protocol", "-p"]
    help: "Specify which protocol to monitor"
    # Use the first word of each line in /etc/protocols for argument completion
    complete: ["exec", "grep -o -E '^\\w+' /etc/protocols"]

  - option_strings: ["--verbose", "-v"]
    multiple_option: true # can be specified multiple times
    help: "Enable verbose mode"
    group: "output_mode" # mutually exclusive to --quiet

  - option_strings: ["--quiet", "-q"]
    help: "Enable quiet mode"
    group: "output_mode" # mutually exclusive to --verbose