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();

@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

@GroupCommandDefinition(
    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();

@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 = "${user.home}", description = "User home directory")
private String userHome;

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

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

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

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

@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 = "${DB_USER:${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

public class AppConfigProvider implements DefaultValueProvider {

    @Override
    public String defaultValue(ProcessedOption option) {
        // Build a hierarchical key from command + option name
        String key = option.parent().name() + "." + option.name();
        return AppConfig.instance().get(key);  // null if not configured
    }
}

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

    @Option(description = "Debug port", defaultValue = "4004")
    private String debug;

    @Option(description = "JFR settings")
    private String jfr;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        // debug = config value if set, else "4004", unless user provided a value
        return CommandResult.SUCCESS;
    }
}

@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;
    }
}

# Works -- overrideRequired bypasses required checks
$ deploy -h
Usage: deploy [options]
  ...

# Still validates normally when -h is NOT used
$ deploy
Error: Option: --environment is required for this command

@CommandDefinition(name = "test", description = "Run tests")
public class TestCommand implements Command<CommandInvocation> {

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

    @Option(name = "output", acceptNameWithoutDashes = true,
            description = "Output file")
    private String output;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        invocation.println("verbose=" + verbose + ", output=" + output);
        return CommandResult.SUCCESS;
    }
}

# Standard form
$ test --verbose --output results.txt

# Without dashes
$ test verbose output results.txt

# Mixed
$ test verbose --output results.txt

@CommandDefinition(name = "config", description = "Configuration manager")
public class ConfigCommand implements Command<CommandInvocation> {

    @Option(name = "key", acceptNameWithoutDashes = true,
            required = true, description = "Configuration key")
    private String key;

    @Option(name = "value", acceptNameWithoutDashes = true,
            description = "Value to set")
    private String value;

    @Override
    public CommandResult execute(CommandInvocation invocation) {
        if (value != null) {
            invocation.println("Set " + key + " = " + value);
        } else {
            invocation.println("Get " + key);
        }
        return CommandResult.SUCCESS;
    }
}

$ config key database.host value localhost
Set database.host = localhost