• 1 Picocli 用途
• 2 CLI 基礎知識
  • 2.1 Options、positional parameters
  • 2.2 Options、positional parameters 既次序
  • 2.3 Double-dash
  • 2.4 Subcommand
• 3 Maven dependencies
• 4 基本例子
• 5 探討 Picocli annotations
  • 5.1 @Command
    • 5.1.1 Top-level command
    • 5.1.2 Subcommand
    • 5.1.3 Sub-subcommand
  • 5.2 @Option（option）
    • 5.2.1 必要 option
    • 5.2.2 非必要 option
  • 5.3 @Parameters（positional parameter）
    • 5.3.1 非必要 positional parameter
• 6 Data types
  • 6.1 String
  • 6.2 boolean
  • 6.3 List<String>
  • 6.4 enum
• 7 參考資料

kubectl get pods -n my-namespace

<dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli</artifactId>
    <version>4.7.3</version>
</dependency>

1public class MainCli {
2
3    public static void main(String[] args) {
4
5        final CommandLine cli = new CommandLine(new MyCommand());
6        final int exitCode = cli.execute(args);
7
8        System.exit(exitCode);
9    }
10}

1@Command(
2    name = "my-cli-app",
3    description = "This app is a CLI tool for testing Picocli.",
4    sortOptions = false,
5    showDefaultValues = true,
6    mixinStandardHelpOptions = true,
7    showEndOfOptionsDelimiterInUsageHelp = true,
8    versionProvider = MyVersionProvider.class,
9)
10public class MyCommand implements Runnable {
11
12    @Option(/* name, description, required, defaultValue, etc */)
13    String sampleOption;
14
15    @Parameters(/* index, description, arity, etc */)
16    String sampleParameter;
17
18    @Override
19    public void run() {
20        // log.info(...);
21    }
22}

• MyCommand 係一個終點 command，所以需要 implements Runnable。
• 如果執行既時候畀左 --help option，佢就會自動生成類似 man page 既結果。
• 如果執行既時候畀左 --version option 而又冇畀 --help option，佢就會用我地自定義既 MyVersionProvider class 黎生成結果。
• 又齊曬 required 既 options 以及 positional parameters，咁佢就會 call 個 run() method。

1@Command(
2    name = "kubectl",
3    description = "This is a Picocli demo to replicate the 'kubectl' CLI.",
4    scope = ScopeType.INHERIT,
5    sortOptions = false,
6    showDefaultValues = true,
7    mixinStandardHelpOptions = true,
8    showEndOfOptionsDelimiterInUsageHelp = true,
9    versionProvider = MyVersionProvider.class,
10    subcommands = {
11        KubectlGetCommand.class,
12        KubectlDeleteCommand.class,
13        KubectlLogsCommand.class,
14    }
15)
16public class KubectlCommand {
17    // 唔計 --help、--version 呢啲特殊既 predefined options，
18    // 呢個本身唔係一個終點 command，所以唔洗 implements Runnable。
19}

• 如果唔係一個終點 command（執行既時候一定要提供 subcommand），就唔洗 implements Runnable，因為就算定義左 run() method，佢都唔會 call。
• 相反，如果係一個終點 command，就要 implements Runnable，因為佢會 call 我地定義既 run() method。

1@Command(
2    name = "get",
3    description = "This is the 'kubectl get' subcommand.",
4    subcommands = {
5        KubectlGetPodsCommand.class,
6        KubectlGetDeploymentsCommand.class,
7    }
8)
9public class KubectlGetCommand {}

1@Command(
2    name = "delete",
3    description = "This is the 'kubectl delete' command.",
4    subcommands = {
5        KubectlDeletePodsCommand.class,
6        KubectlDeleteDeploymentsCommand.class,
7    }
8)
9public class KubectlDeleteCommand {}

1@Slf4j
2@Command(
3    name = "logs",
4    description = "This is the 'kubectl logs' command."
5)
6public class KubectlLogsCommand implements Runnable {
7
8    @Option(names = { "-f", "--follow" }, required = false, defaultValue = "false")
9    boolean follow;
10
11    @Option(names = { "--tail" }, required = false, defaultValue = "-1")
12    int tail;
13
14    @Parameters(index = "0")
15    String podName;
16
17    @Override
18    public void run() {
19        log.info("kubectl logs");
20        log.info("-f: {}", follow);
21        log.info("--tail: {}", tail);
22        log.info("Param 0: {}", podName);
23    }
24}

java -jar kubectl.jar logs mypod
java -jar kubectl.jar logs -f --tail=20 mypod

1@Command(
2    name = "pods",
3    aliases = { "po", "pod" },
4    description = "This is the 'kubectl get pods' command."
5)
6public class KubectlGetPodsCommand implements Runnable {
7
8    @Override
9    public void run() {
10        System.out.println("kubectl get pods");
11    }
12}

java -jar kubectl.jar get po
java -jar kubectl.jar get pod
java -jar kubectl.jar get pods

1@Slf4j
2@Command(
3    name = "pods",
4    aliases = { "po", "pod" },
5    description = "This is the 'kubectl delete pods' command."
6)
7public class KubectlDeletePodsCommand implements Runnable {
8
9    @Parameters(
10        index = "0",
11        description = "A list of pod names.",
12        arity = "1..*"
13    )
14    List<String> podNames;
15
16    @Override
17    public void run() {
18        log.info("kubectl delete pods");
19        log.info("Param 0: ({} elements) {}", podNames.size(), podNames);
20    }
21}

java -jar kubectl.jar delete po pod1
java -jar kubectl.jar delete pod pod1
java -jar kubectl.jar delete pods pod1
java -jar kubectl.jar delete pods pod1 pod2

@Option(
    names = { "-i", "--input" },
    required = true
)
String input;

@Option(
    names = { "-o", "--output" },
    required = false
)
String output;

@Parameters(
    index = "0",
    description = "1st parameter"
)
String foo;

@Parameters(
    index = "1",
    description = "2nd parameter"
)
String bar;

1@Parameters(
2    index = "2",
3    description = "3rd parameter (multiple values)",
4    arity = "1..*"
5)
6List<String> varargs;

@Parameter(index = "0", arity = "0..1")
String foo;

@Option(
    names = { "--foo" },
    defaultValue = "foo" // 任意值
)
String foo;

@Option(
    names = { "--foo" },
    defaultValue = "true" // "true"、"false"
)
boolean foo;

• 想用空格以外既符號去分隔多個值，例如 ,、;。
• 喺 defaultValue 度提供多個值（如果冇設置 split 既話會當左做一個帶空格既值）。

• 如果有幾個 options 都係接受多個值，例如 --foo 1 2 3 --bar 4 5 6，佢會識得分個值係咪其中一個 option 黎，如果係（例子裡面既 --bar），佢會識得分返開佢地，而唔係當左佢係前面 option（例子裡面既 --foo）既其中一個值。
  • 即使唔係 - 或者 -- 開頭佢都會識分。
• 如果有幾個 positional parameters 都接受多個值既話，測試過係會出問題，即使前面既已經設置左 arity 數量上限。

1@Option(
2    names = { "--foo" },
3    defaultValue = "item1 item2 item3",
4    split = " "
5)
6List<String> foo;

--foo item1
--foo item1 item2

1@Option(
2    names = { "--foo" },
3    defaultValue = "item1,item2,item3", // 要冇 space
4    split = ","
5)
6List<String> foo;

--foo item1
--foo item1,item2

1public static enum MyEnum {
2    FOO, BAR
3}
4
5@Option(
6    names = { "--foo" },
7    defaultValue = "BAR" // 個 enum 既其中一個 constant
8)
9MyEnum foo;

• Picocli 官方文檔 - Quick Guide
• Picocli 官方文檔 - 4. Options and Parameters
• Picocli 官方文檔 - 6. Multiple Values
• Picocli 官方文檔 - 6.5 Default Arity