Options

@CommandDefinition(name = "greet")
public class GreetCommand implements Command<CommandInvocation> {

    @Option(shortName = 'n', description = "Name to greet")
    private String name;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        invocation.println("Hello, " + name + "!");
        return CommandResult.SUCCESS;
    }
}

@Option(shortName = 'v', hasValue = false, description = "Verbose output")
private boolean verbose;

@Option(hasValue = false, description = "Enable color output")
private Boolean color;  // null = use terminal default, true = force color

@CommandDefinition(name = "run", description = "Run application")
public class RunCommand implements Command<CommandInvocation> {

    @Option(shortName = 'd', optionalValue = true, defaultValue = "4004",
            description = "Enable debugging, optionally with a specific port")
    private String debug;

    @Option(optionalValue = true, defaultValue = "default",
            description = "Enable JFR recording")
    private String jfr;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        if (debug != null) {
            invocation.println("Debugging on port " + debug);
        }
        return CommandResult.SUCCESS;
    }
}

# Flag-only: uses defaultValue "4004"
$ run --debug
Debugging on port 4004

# With value via space
$ run --debug 5005
Debugging on port 5005

# With value via equals
$ run --debug=6006
Debugging on port 6006

# Short name
$ run -d
Debugging on port 4004

# Short name with value (no space)
$ run -d8080
Debugging on port 8080

# Combined with other options -- debug uses default, jfr gets value
$ run --debug --jfr=filename=recording.jfr
Debugging on port 4004

ProcessedOptionBuilder.builder()
        .name("debug")
        .shortName('d')
        .type(String.class)
        .optionalValue(true)
        .addDefaultValue("4004")
        .description("Enable debugging")
        .build();

@CommandDefinition(name = "run", description = "Run application")
public class RunCommand implements Command<CommandInvocation> {

    @Option(name = "debug", fallbackValue = "4004",
            description = "Enable debugging. Default port: ${FALLBACK-VALUE}")
    private String debug;

    @Argument(description = "Script file")
    private String script;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        if (debug == null) {
            invocation.println("No debugging");
        } else {
            invocation.println("Debugging on port " + debug);
        }
        return CommandResult.SUCCESS;
    }
}

ProcessedOptionBuilder.builder()
        .name("debug")
        .type(String.class)
        .fallbackValue("4004")
        .description("Debug port")
        .build();

@Option(hasValue = false, negatable = true, description = "Enable verbose output")
private boolean verbose;

@Option(hasValue = false, negatable = true, negationPrefix = "without-",
        description = "Enable color output")
private boolean color;

@Option(hasValue = false, negatable = true, negationPrefix = "disable-",
        description = "Enable caching")
private boolean cache;

@CommandDefinition(name = "build", description = "Build the project")
public class BuildCommand implements Command<CommandInvocation> {

    @Option(hasValue = false, negatable = true, defaultValue = "true",
            description = "Run tests during build")
    private boolean tests;

    @Option(hasValue = false, negatable = true, defaultValue = "true",
            description = "Enable compiler optimizations")
    private boolean optimize;

    @Option(hasValue = false, negatable = true, negationPrefix = "skip-",
            description = "Generate documentation")
    private boolean docs;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        invocation.println("Building with:");
        invocation.println("  Tests: " + tests);
        invocation.println("  Optimize: " + optimize);
        invocation.println("  Docs: " + docs);
        return CommandResult.SUCCESS;
    }
}

# Run with defaults (tests=true, optimize=true, docs=false)
$ build
Building with:
  Tests: true
  Optimize: true
  Docs: false

# Disable tests and optimization, enable docs
$ build --no-tests --no-optimize --docs
Building with:
  Tests: false
  Optimize: false
  Docs: true

# Use custom prefix
$ build --skip-docs
Building with:
  Tests: true
  Optimize: true
  Docs: false

@CommandDefinition(
    name = "project",
    description = "Project management",
    groupCommands = {BuildCommand.class, TestCommand.class}
)
public class ProjectCommand implements Command<CommandInvocation> {

    @Option(name = "verbose", hasValue = false, inherited = true)
    private boolean verbose;

    @Option(name = "config", inherited = true)
    private String configFile;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        return CommandResult.SUCCESS;
    }
}

@CommandDefinition(name = "build", description = "Build the project")
public class BuildCommand implements Command<CommandInvocation> {

    // Plain fields with matching names -- auto-populated from parent's inherited options
    private boolean verbose;
    private String configFile;

    @Option(description = "Build target")
    private String target;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        if (verbose) {
            invocation.println("[VERBOSE] Config: " + configFile);
        }
        invocation.println("Building " + target);
        return CommandResult.SUCCESS;
    }
}

# Option before the subcommand -- parsed by the parent
$ project --verbose --config app.yml build --target release

# Option after the subcommand -- recognized from the parent
$ project build --verbose --config app.yml --target release

# Both forms produce the same result

// Parent
@Option(name = "verbose", hasValue = false, inherited = true)
private boolean verbose;

// Child -- plain field, same name
private boolean verbose;  // receives the inherited value

@CommandDefinition(name = "runner", description = "Java runner")
public class RunnerCommand implements Command<CommandInvocation> {

    @Option(name = "enableassertions", aliases = {"ea"},
            hasValue = false, description = "Enable assertions")
    private boolean enableAssertions;

    @Option(name = "classpath", aliases = {"cp"},
            description = "Class path")
    private String classpath;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        return CommandResult.SUCCESS;
    }
}

$ runner --enableassertions --classpath /path
$ runner --ea --cp /path

@OptionList(name = "items", aliases = {"item"},
            description = "Items to process")
private List<String> items;

@CommandDefinition(name = "myapp", description = "My application", generateHelp = true)
public class MyAppCommand implements Command<CommandInvocation> {

    @Option(hasValue = false, description = "Output as JSON", helpGroup = "Output Format")
    private boolean json;

    @Option(hasValue = false, description = "Output as XML", helpGroup = "Output Format")
    private boolean xml;

    @Option(description = "Username", helpGroup = "Authentication")
    private String user;

    @Option(description = "Password", helpGroup = "Authentication")
    private String password;

    @Option(hasValue = false, description = "Verbose output")
    private boolean verbose;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        return CommandResult.SUCCESS;
    }
}

@OptionList(description = "Include patterns", helpGroup = "Filters")
private List<String> include;

@OptionList(description = "Exclude patterns", helpGroup = "Filters")
private List<String> exclude;

public class OutputMixin {
    @Option(hasValue = false, description = "Output as JSON", helpGroup = "Output Format")
    boolean json;

    @Option(hasValue = false, description = "Output as XML", helpGroup = "Output Format")
    boolean xml;
}

@CommandDefinition(name = "report", description = "Generate report", generateHelp = true)
public class ReportCommand implements Command<CommandInvocation> {

    @Mixin
    OutputMixin output;

    @Option(description = "Report title")
    private String title;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        return CommandResult.SUCCESS;
    }
}

ProcessedOptionBuilder.builder()
        .name("json")
        .type(boolean.class)
        .description("Output as JSON")
        .helpGroup("Output Format")
        .build();

@Option(description = "Always first", order = 10)
private boolean ci;

@Option(description = "Shown after --ci", order = 20)
private String profile;

@CommandDefinition(name = "export", description = "Export data", generateHelp = true)
public class ExportCommand implements Command<CommandInvocation> {

    @Option(hasValue = false, description = "Output as JSON", exclusiveWith = {"xml", "csv"})
    private boolean json;

    @Option(hasValue = false, description = "Output as XML", exclusiveWith = {"json", "csv"})
    private boolean xml;

    @Option(hasValue = false, description = "Output as CSV", exclusiveWith = {"json", "xml"})
    private boolean csv;

    @Option(hasValue = false, description = "Verbose output")
    private boolean verbose;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        return CommandResult.SUCCESS;
    }
}

# Valid -- only one format selected
$ export --json
$ export --xml --verbose

# Invalid -- mutually exclusive options used together
$ export --json --xml
Error: Options --json and --xml are mutually exclusive.

@OptionList(description = "Items to process", exclusiveWith = {"file"})
private List<String> items;

@Option(description = "Read items from file", exclusiveWith = {"items"})
private String file;

ProcessedOptionBuilder.builder()
        .name("json")
        .type(boolean.class)
        .hasValue(false)
        .exclusiveWith("xml", "csv")
        .build();

@CommandDefinition(name = "serve", description = "Start server", generateHelp = true)
public class ServeCommand implements Command<CommandInvocation> {

    @Option(shortName = 'p', description = "Server port")
    private int port;

    @Option(description = "Bind address")
    private String host;

    @Option(description = "Enable request tracing", visibility = OptionVisibility.FULL)
    private boolean trace;

    @Option(description = "Thread pool size", visibility = OptionVisibility.FULL)
    private int threads;

    @Option(description = "Internal diagnostic token", visibility = OptionVisibility.HIDDEN)
    private String diagnosticToken;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        return CommandResult.SUCCESS;
    }
}

$ serve --help
Usage: serve [<options>]
Start server

Options:
  -p, --port      Server port
  --host          Bind address
  -h, --help      Display help (use --help=all for all options)

$ serve --help=all
Usage: serve [<options>]
Start server

Options:
  -p, --port      Server port
  --host          Bind address
  --trace         Enable request tracing
  --threads       Thread pool size
  -h, --help      Display help (use --help=all for all options)

@Option(description = "Enable tracing", helpGroup = "Diagnostics",
        visibility = OptionVisibility.FULL)
private boolean trace;

@Option(description = "Profile mode", helpGroup = "Diagnostics",
        visibility = OptionVisibility.FULL)
private boolean profile;

@OptionList(description = "Debug modules", visibility = OptionVisibility.FULL)
private List<String> debugModules;

@OptionGroup(shortName = 'X', description = "Internal flags",
             visibility = OptionVisibility.HIDDEN)
private Map<String, String> internalFlags;

ProcessedOptionBuilder.builder()
        .name("trace")
        .type(boolean.class)
        .description("Enable request tracing")
        .visibility(OptionVisibility.FULL)
        .build();

@Option(required = true, description = "Required file path")
private String filePath;

@Option(defaultValue = "INFO", description = "Log level")
private String logLevel;

@Option(defaultValue = "${HOME}", description = "Home directory")
private String homeDir;

@Option(defaultValue = "${USER}", description = "Username")
private String username;

@Option(defaultValue = "${DATABASE_URL}", description = "Database connection URL")
private String databaseUrl;

@Option(defaultValue = "${PORT:-8080}", description = "Server port")
private int port;

@Option(defaultValue = "${LOG_LEVEL:-INFO}", description = "Log level")
private String logLevel;

@Option(defaultValue = "${DATABASE_HOST:-localhost}", description = "Database host")
private String dbHost;

@Option(defaultValue = "${sys:user.home}", description = "User home directory")
private String userHome;

@Option(defaultValue = "${user.name}", description = "Current user (sys prop, then env var)")
private String userName;

@Option(defaultValue = "${sys:java.io.tmpdir}", description = "Temp directory")
private String tempDir;

@Option(defaultValue = "${sys:os.name}", description = "Operating system")
private String osName;

@Option(defaultValue = "${sys:my.app.config:-/etc/myapp/config}", description = "Config path")
private String configPath;

// Try env var EDITOR, then sys prop editor.path, then literal "vim"
@Option(defaultValue = "${env:EDITOR:-${sys:editor.path:-vim}}")
private String editor;

// Try env var DB_USER, then system user name
@Option(defaultValue = "${env:DB_USER:-${sys:user.name}}")
private String dbUser;

// Bare --debug resolves port from env, then config, then literal 4004
@Option(name = "debug", fallbackValue = "${env:DEBUG_PORT:-${sys:debug.port:-4004}}")
private String debug;

@Option(defaultValue = "$${NOT_EXPANDED}", description = "Literal ${NOT_EXPANDED}")
private String literal;

@CommandDefinition(name = "connect", description = "Connect to database")
public class ConnectCommand implements Command<CommandInvocation> {

    @Option(
        shortName = 'h',
        defaultValue = "${DB_HOST:-localhost}",
        description = "Database host"
    )
    private String host;

    @Option(
        shortName = 'p',
        defaultValue = "${DB_PORT:-5432}",
        description = "Database port"
    )
    private int port;

    @Option(
        shortName = 'u',
        defaultValue = "${env:DB_USER:-${sys:user.name}}",
        description = "Database user (defaults to system user)"
    )
    private String user;

    @Option(
        shortName = 'd',
        defaultValue = "${DB_NAME:-myapp}",
        description = "Database name"
    )
    private String database;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        invocation.println(String.format(
            "Connecting to %s@%s:%d/%s", user, host, port, database));
        return CommandResult.SUCCESS;
    }
}

# Uses all defaults (environment variables or fallback values)
$ connect
Connecting to john@localhost:5432/myapp

# Override with environment variables
$ export DB_HOST=prod-db.example.com
$ export DB_PORT=5433
$ connect
Connecting to john@prod-db.example.com:5433/myapp

# Override with command-line options (highest priority)
$ connect -h dev-db.local -p 5434
Connecting to john@dev-db.local:5434/myapp

@CommandDefinition(name = "edit", description = "Edit files",
        defaultValueProvider = AppConfigProvider.class)
public class EditCommand implements Command<CommandInvocation> {

    // Priority: JBANG_EDITOR env var > config "edit.open" > (none)
    @Option(name = "open", defaultValue = "${env:JBANG_EDITOR:-}")
    String editor;
}

# Env var set: uses env var (priority 2)
$ JBANG_EDITOR=code edit file.java    # editor = "code"

# Env var not set, config has edit.open=vim: uses provider (priority 3)
$ edit file.java                       # editor = "vim"

# Env var not set, no config: uses fallback (priority 4)
$ edit file.java                       # editor = ""

public class AppConfigProvider implements DefaultValueProvider {

    @Override
    public String defaultValue(ProcessedOption option) {
        // Called when option is NOT specified at all
        String key = option.parent().name() + "." + option.name();
        return AppConfig.instance().get(key);  // null → falls through to annotation defaultValue
    }
}

@CommandDefinition(name = "run", description = "Run application",
        defaultValueProvider = AppConfigProvider.class)
public class RunCommand implements Command<CommandInvocation> {

    @Option(description = "Debug port", defaultValue = "4004")
    private String debug;
    // Omitted → provider returns config value, or falls through to "4004"
}

public class JBangConfigProvider implements DefaultValueProvider {

    @Override
    public String defaultValue(ProcessedOption option) {
        // Called when option is omitted entirely
        return null;
    }

    @Override
    public String fallbackValue(ProcessedOption option) {
        // Called when option is present but bare (--debug without =value)
        switch (option.name()) {
            case "debug":
                return Configuration.get("run.debug");  // null → falls through to "4004"
            case "jfr":
                return Configuration.get("run.jfr");    // null → falls through to ""
            default:
                return null;  // use annotation fallbackValue
        }
    }
}

@CommandDefinition(name = "run", description = "Run a script",
        defaultValueProvider = JBangConfigProvider.class)
public class RunCommand implements Command<CommandInvocation> {

    @Option(name = "debug", fallbackValue = "4004",
            description = "Enable debugging on port ${DEFAULT-VALUE}")
    String debug;

    @Option(name = "jfr", fallbackValue = "",
            description = "Enable Java Flight Recorder")
    String jfr;
}

# Explicit value — always wins (priority 1)
$ myapp run --debug=5005
# debug = "5005"

# Bare flag, config has run.debug=9999 — provider fallback (priority 2)
$ myapp run --debug
# debug = "9999" (from provider.fallbackValue())

# Bare flag, no config — annotation fallback (priority 3)
$ myapp run --debug
# debug = "4004" (from @Option(fallbackValue = "4004"))

# Option omitted — field default (priority 6)
$ myapp run
# debug = null

public class DebugOptionParser implements OptionParser {
    private static final Pattern PORT = Pattern.compile("\\d+");

    @Override
    public void parse(ParsedLineIterator iter, ProcessedOption option)
            throws OptionParserException {
        // Consume the option name token
        iter.pollParsedWord();

        // Peek at next token -- only consume if it matches a port number
        if (iter.hasNextWord()) {
            String next = iter.peekWord();
            if (!next.startsWith("-") && PORT.matcher(next).matches()) {
                option.addValue(next);
                iter.pollParsedWord();
                return;
            }
        }
        // No addValue() call -- framework applies the fallback chain
    }
}

@CommandDefinition(name = "run", description = "Run script")
public class RunCommand implements Command<CommandInvocation> {

    @Option(name = "debug", parser = DebugOptionParser.class,
            fallbackValue = "4004")
    String debug;

    @Argument
    String script;
}

$ run --debug=5005 test.java   # debug = "5005" (parser consumed)
$ run --debug 5005 test.java   # debug = "5005" (parser consumed)
$ run --debug test.java        # debug = "4004" (parser skipped, fallback applied)
$ run --debug                  # debug = "4004" (parser skipped, fallback applied)

@Option(defaultValue = {"${DEFAULT_TAG:latest}", "stable"}, description = "Image tags")
private List<String> tags;

@Argument(defaultValue = "${PWD:${user.dir}}", description = "Working directory")
private String workingDirectory;

// Good: Password from environment, no fallback (will be null if not set)
@Option(defaultValue = "${DB_PASSWORD}", description = "Database password")
private String password;

// In execute(), check if password was provided
if (password == null) {
    password = shell.readLine(new Prompt("Password: ", '*'));
}

@Option(name = "format",
        allowedValues = { "text", "json", "yaml" },
        description = "Output format")
private String format;

@OptionList(name = "tags",
            allowedValues = { "v1", "v2", "latest" },
            description = "Deployment tags")
private List<String> tags;

@Option(converter = PathConverter.class, description = "Directory path")
private Path directory;

public static class PathConverter implements Converter<Path> {
    @Override
    public Path convert(String input) {
        return Paths.get(input);
    }
}

@Option(description = "Output file")
private Resource output;    // automatic file completion + Resource API

@Option(description = "Config file")
private File config;         // automatic file completion + java.io.File

@Option(description = "Data directory")
private Path dataDir;        // automatic file completion + java.nio.file.Path

@Option(name = "verbose", shortName = 'v', description = "Verbose mode")
private boolean verbose;

@CommandDefinition(name = "connect", description = "Connect to server")
public class ConnectCommand implements Command<CommandInvocation> {

    @Option(required = true, description = "Server hostname")
    private String host;

    @Option(askIfNotSet = true, description = "Username")
    private String username;

    @Option(askIfNotSet = true, description = "Password")
    private String password;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        invocation.println("Connecting as " + username + "@" + host);
        return CommandResult.SUCCESS;
    }
}

// Will NOT prompt -- the default "8080" is used instead
@Option(askIfNotSet = true, defaultValue = "8080", description = "Port")
private int port;

// WILL prompt -- no default value
@Option(askIfNotSet = true, description = "API key")
private String apiKey;

@CommandDefinition(name = "deploy", description = "Deploy application",
                   validator = DeployValidator.class)
public class DeployCommand implements Command<CommandInvocation> {

    @Option(required = true, description = "Target environment")
    private String environment;

    @Option(required = true, description = "Application version")
    private String version;

    @Option(shortName = 'h', hasValue = false, overrideRequired = true,
            description = "Show help")
    private boolean help;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        if (help) {
            invocation.println(invocation.getHelpInfo("deploy"));
            return CommandResult.SUCCESS;
        }
        invocation.println("Deploying " + version + " to " + environment);
        return CommandResult.SUCCESS;
    }
}