解析命令行參數(shù)
處理短選項(xiàng)和長選項(xiàng)
支持位置參數(shù)
自動(dòng)做類型轉(zhuǎn)換
生成幫助文檔
生成版本信息
支持子命令
支持命令補(bǔ)全
支持打包成可執(zhí)行 Jar
支持 GraalVM Native Image

Picocli 用注解描述命令、選項(xiàng)和參數(shù)，把 String[] args 解析成 Java 對象。

public static void main(String[] args) {
    for (int i = 0; i < args.length; i++) {
        if ("--file".equals(args[i])) {
            String file = args[++i];
            System.out.println(file);
        }
    }
}

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

dependencies {
    implementation("info.picocli:picocli:4.7.7")
}

<dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli-codegen</artifactId>
    <version>4.7.7</version>
    <scope>provided</scope>
</dependency>

Runnable：只執(zhí)行邏輯，不關(guān)心返回值
Callable<Integer>：可以返回退出碼，更適合正式 CLI

0：成功
非 0：失敗

java -jar hello.jar 張三

Hello, 張三

package com.example.picoclidemo;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Parameters;
import java.util.concurrent.Callable;
@Command(
        name = "hello",
        description = "打印問候語",
        mixinStandardHelpOptions = true,
        version = "hello 1.0.0"
)
public class HelloCommand implements Callable<Integer> {
    @Parameters(index = "0", description = "名稱")
    private String name;
    @Override
    public Integer call() {
        System.out.println("Hello, " + name);
        return 0;
    }
    public static void main(String[] args) {
        int exitCode = new CommandLine(new HelloCommand()).execute(args);
        System.exit(exitCode);
    }
}

java com.example.picoclidemo.HelloCommand 張三

Hello, 張三

java com.example.picoclidemo.HelloCommand --help

Usage: hello [-hV] <name>
打印問候語
      <name>      名稱
  -h, --help      Show this help message and exit.
  -V, --version   Print version information and exit.

-h, --help
-V, --version

tool --file app.log --limit 100 --verbose

@Option(names = {"-f", "--file"}, description = "文件路徑")
private File file;
@Option(names = {"-l", "--limit"}, defaultValue = "100", description = "最多處理多少行")
private int limit;
@Option(names = {"-v", "--verbose"}, description = "輸出詳細(xì)日志")
private boolean verbose;

copy source.txt target.txt

@Parameters(index = "0", description = "源文件")
private File source;
@Parameters(index = "1", description = "目標(biāo)文件")
private File target;

有 - 或 -- 前綴：@Option
沒有前綴，靠順序：@Parameters

統(tǒng)計(jì)行數(shù)
統(tǒng)計(jì)字符數(shù)
忽略空行
限制最多讀取多少行
輸出詳細(xì)信息

textstat README.md --chars --ignore-blank --limit 1000 -v

package com.example.picoclidemo;
import picocli.CommandLine;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.io.IOException;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.List;
import java.util.concurrent.Callable;
@Command(
        name = "textstat",
        description = "統(tǒng)計(jì)文本文件的行數(shù)和字符數(shù)",
        mixinStandardHelpOptions = true,
        version = "textstat 1.0.0"
)
public class TextStatCommand implements Callable<Integer> {
    @Parameters(index = "0", description = "要統(tǒng)計(jì)的文本文件")
    private Path file;
    @Option(names = {"-c", "--chars"}, description = "統(tǒng)計(jì)字符數(shù)")
    private boolean countChars;
    @Option(names = {"--ignore-blank"}, description = "忽略空行")
    private boolean ignoreBlank;
    @Option(names = {"-l", "--limit"}, defaultValue = "0", description = "最多讀取多少行，0 表示不限制")
    private int limit;
    @Option(names = {"-v", "--verbose"}, description = "輸出詳細(xì)信息")
    private boolean verbose;
    @Override
    public Integer call() {
        if (!Files.exists(file)) {
            System.err.println("文件不存在: " + file);
            return 2;
        }
        if (!Files.isRegularFile(file)) {
            System.err.println("不是普通文件: " + file);
            return 2;
        }
        try {
            List<String> lines = Files.readAllLines(file, StandardCharsets.UTF_8);
            if (limit > 0 && lines.size() > limit) {
                lines = lines.subList(0, limit);
            }
            long lineCount = lines.stream()
                    .filter(line -> !ignoreBlank || !line.isBlank())
                    .count();
            System.out.println("lines=" + lineCount);
            if (countChars) {
                int chars = lines.stream()
                        .filter(line -> !ignoreBlank || !line.isBlank())
                        .mapToInt(String::length)
                        .sum();
                System.out.println("chars=" + chars);
            }
            if (verbose) {
                System.out.println("file=" + file.toAbsolutePath());
                System.out.println("limit=" + limit);
                System.out.println("ignoreBlank=" + ignoreBlank);
            }
            return 0;
        } catch (IOException e) {
            System.err.println("讀取文件失敗: " + e.getMessage());
            return 1;
        }
    }
    public static void main(String[] args) {
        int exitCode = new CommandLine(new TextStatCommand()).execute(args);
        System.exit(exitCode);
    }
}

java com.example.picoclidemo.TextStatCommand README.md

lines=128

java com.example.picoclidemo.TextStatCommand README.md --chars

lines=128
chars=5042

java com.example.picoclidemo.TextStatCommand README.md --ignore-blank -v

lines=96
file=/Users/test/project/README.md
limit=0
ignoreBlank=true

java com.example.picoclidemo.TextStatCommand

@Option(names = {"-u", "--username"}, required = true, description = "用戶名")
private String username;

Missing required option: '--username=<username>'

@Option(names = {"-p", "--port"}, defaultValue = "8080", description = "端口，默認(rèn) ${DEFAULT-VALUE}")
private int port;

${DEFAULT-VALUE}

@Option(names = {"-v", "--verbose"}, description = "詳細(xì)輸出")
private boolean verbose;

tool -v
tool --verbose

@Option(names = {"-t", "--tag"}, description = "標(biāo)簽，可重復(fù)")
private List<String> tags;

tool -t java -t cli -t demo

[java, cli, demo]

@Option(names = "--tags", split = ",", description = "逗號(hào)分隔的標(biāo)簽")
private List<String> tags;

tool --tags java,cli,demo

tool --color
tool --color=always
tool --color=never

@Option(
        names = "--color",
        arity = "0..1",
        fallbackValue = "always",
        defaultValue = "auto",
        description = "顏色模式: auto, always, never"
)
private String color;

不傳 --color：auto
只傳 --color：always
傳 --color=never：never

enum OutputFormat {
    TEXT, JSON, CSV
}
@Option(names = {"-f", "--format"}, defaultValue = "TEXT", description = "輸出格式: ${COMPLETION-CANDIDATES}")
private OutputFormat format;

tool --format JSON

@Parameters(index = "0", description = "輸入文件")
private Path input;

@Parameters(index = "0", description = "源文件")
private Path source;
@Parameters(index = "1", description = "目標(biāo)文件")
private Path target;

@Parameters(index = "0..*", description = "文件列表")
private List<Path> files;

tool a.txt b.txt c.txt

2026-07-18

package com.example.picoclidemo;
import picocli.CommandLine.ITypeConverter;
import java.time.LocalDate;
import java.time.format.DateTimeFormatter;
public class LocalDateConverter implements ITypeConverter<LocalDate> {
    @Override
    public LocalDate convert(String value) {
        return LocalDate.parse(value, DateTimeFormatter.ISO_LOCAL_DATE);
    }
}

@Option(names = "--date", converter = LocalDateConverter.class, description = "日期，格式 yyyy-MM-dd")
private LocalDate date;

tool --date 2026-07-18

git add
git commit
kubectl get pods
docker image ls

filecli stat README.md
filecli copy a.txt b.txt --force
filecli delete temp.log --dry-run

package com.example.picoclidemo.filecli;
import picocli.CommandLine;
import picocli.CommandLine.Command;
@Command(
        name = "filecli",
        description = "文件處理命令行工具",
        mixinStandardHelpOptions = true,
        version = "filecli 1.0.0",
        subcommands = {
                StatCommand.class,
                CopyCommand.class,
                DeleteCommand.class
        }
)
public class FileCliCommand implements Runnable {
    @Override
    public void run() {
        CommandLine.usage(this, System.out);
    }
    public static void main(String[] args) {
        int exitCode = new CommandLine(new FileCliCommand()).execute(args);
        System.exit(exitCode);
    }
}

package com.example.picoclidemo.filecli;
import picocli.CommandLine.Command;
import picocli.CommandLine.Parameters;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.Callable;
@Command(name = "stat", description = "查看文件基本信息")
public class StatCommand implements Callable<Integer> {
    @Parameters(index = "0", description = "文件路徑")
    private Path file;
    @Override
    public Integer call() throws Exception {
        if (!Files.exists(file)) {
            System.err.println("文件不存在: " + file);
            return 2;
        }
        System.out.println("path=" + file.toAbsolutePath());
        System.out.println("size=" + Files.size(file));
        System.out.println("directory=" + Files.isDirectory(file));
        System.out.println("regularFile=" + Files.isRegularFile(file));
        return 0;
    }
}

package com.example.picoclidemo.filecli;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.nio.file.Files;
import java.nio.file.Path;
import java.nio.file.StandardCopyOption;
import java.util.concurrent.Callable;
@Command(name = "copy", description = "復(fù)制文件")
public class CopyCommand implements Callable<Integer> {
    @Parameters(index = "0", description = "源文件")
    private Path source;
    @Parameters(index = "1", description = "目標(biāo)文件")
    private Path target;
    @Option(names = {"-f", "--force"}, description = "覆蓋已存在文件")
    private boolean force;
    @Override
    public Integer call() throws Exception {
        if (!Files.exists(source)) {
            System.err.println("源文件不存在: " + source);
            return 2;
        }
        if (Files.exists(target) && !force) {
            System.err.println("目標(biāo)文件已存在，使用 --force 覆蓋: " + target);
            return 3;
        }
        if (force) {
            Files.copy(source, target, StandardCopyOption.REPLACE_EXISTING);
        } else {
            Files.copy(source, target);
        }
        System.out.println("復(fù)制完成: " + source + " -> " + target);
        return 0;
    }
}

package com.example.picoclidemo.filecli;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import picocli.CommandLine.Parameters;
import java.nio.file.Files;
import java.nio.file.Path;
import java.util.concurrent.Callable;
@Command(name = "delete", description = "刪除文件")
public class DeleteCommand implements Callable<Integer> {
    @Parameters(index = "0", description = "文件路徑")
    private Path file;
    @Option(names = "--dry-run", description = "只打印將要執(zhí)行的操作，不真正刪除")
    private boolean dryRun;
    @Override
    public Integer call() throws Exception {
        if (!Files.exists(file)) {
            System.err.println("文件不存在: " + file);
            return 2;
        }
        if (dryRun) {
            System.out.println("[dry-run] 將刪除: " + file.toAbsolutePath());
            return 0;
        }
        Files.delete(file);
        System.out.println("刪除完成: " + file.toAbsolutePath());
        return 0;
    }
}

java com.example.picoclidemo.filecli.FileCliCommand stat README.md
java com.example.picoclidemo.filecli.FileCliCommand copy a.txt b.txt --force
java com.example.picoclidemo.filecli.FileCliCommand delete temp.log --dry-run

java com.example.picoclidemo.filecli.FileCliCommand copy --help

Usage: filecli copy [-f] <source> <target>
復(fù)制文件
      <source>   源文件
      <target>   目標(biāo)文件
  -f, --force    覆蓋已存在文件

--verbose
--profile
--config

package com.example.picoclidemo.filecli;
import picocli.CommandLine.Option;
import java.nio.file.Path;
public class CommonOptions {
    @Option(names = {"-v", "--verbose"}, description = "輸出詳細(xì)日志")
    boolean verbose;
    @Option(names = "--config", description = "配置文件路徑")
    Path config;
}

@Mixin
private CommonOptions commonOptions;

@Command(name = "stat", description = "查看文件基本信息")
public class StatCommand implements Callable<Integer> {
    @Mixin
    private CommonOptions commonOptions;
    @Parameters(index = "0", description = "文件路徑")
    private Path file;
    @Override
    public Integer call() throws Exception {
        if (commonOptions.verbose) {
            System.out.println("config=" + commonOptions.config);
        }
        System.out.println("path=" + file.toAbsolutePath());
        return 0;
    }
}

filecli stat README.md --verbose --config ./app.properties

@Option(names = "--username", required = true, description = "用戶名")
private String username;
@Option(
        names = "--password",
        interactive = true,
        arity = "0..1",
        description = "密碼，不在命令行中明文顯示"
)
private char[] password;

tool --username admin --password

tool --password 123456

@Option(names = "--port", required = true)
private int port;

tool --port abc

@Option(names = "--port", defaultValue = "8080", description = "端口")
private int port;
@Override
public Integer call() {
    if (port < 1 || port > 65535) {
        System.err.println("端口范圍必須是 1 到 65535");
        return 2;
    }
    return 0;
}

public static void main(String[] args) {
    int exitCode = new CommandLine(new AppCommand()).execute(args);
    System.exit(exitCode);
}

CommandLine.ExitCode.OK
CommandLine.ExitCode.USAGE
CommandLine.ExitCode.SOFTWARE

return CommandLine.ExitCode.OK;

CommandLine commandLine = new CommandLine(new FileCliCommand());
commandLine.setExecutionExceptionHandler((ex, cmd, parseResult) -> {
    cmd.getErr().println("執(zhí)行失敗: " + ex.getMessage());
    return 1;
});
int exitCode = commandLine.execute(args);
System.exit(exitCode);

@Command(
        name = "filecli",
        description = "文件處理命令行工具",
        synopsisHeading = "%n用法:%n  ",
        descriptionHeading = "%n說明:%n",
        optionListHeading = "%n選項(xiàng):%n",
        parameterListHeading = "%n參數(shù):%n",
        commandListHeading = "%n子命令:%n",
        mixinStandardHelpOptions = true,
        version = "filecli 1.0.0"
)

@Option(
        names = "--format",
        defaultValue = "TEXT",
        description = "輸出格式: ${COMPLETION-CANDIDATES}，默認(rèn) ${DEFAULT-VALUE}"
)
private OutputFormat format;

@Command(
        name = "filecli",
        mixinStandardHelpOptions = true,
        subcommands = {
                StatCommand.class,
                CopyCommand.class,
                DeleteCommand.class,
                picocli.AutoComplete.GenerateCompletion.class
        }
)
public class FileCliCommand implements Runnable {
    @Override
    public void run() {
        CommandLine.usage(this, System.out);
    }
}

java -cp "target/filecli.jar" com.example.picoclidemo.filecli.FileCliCommand generate-completion

java -jar filecli.jar stat README.md

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-shade-plugin</artifactId>
            <version>3.6.0</version>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>shade</goal>
                    </goals>
                    <configuration>
                        <transformers>
                            <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                                <mainClass>com.example.picoclidemo.filecli.FileCliCommand</mainClass>
                            </transformer>
                        </transformers>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

mvn clean package

java -jar target/filecli-1.0.0.jar stat README.md

#!/usr/bin/env sh
java -jar /opt/filecli/filecli-1.0.0.jar "$@"

chmod +x filecli

./filecli stat README.md

<profiles>
    <profile>
        <id>native</id>
        <build>
            <plugins>
                <plugin>
                    <groupId>org.graalvm.buildtools</groupId>
                    <artifactId>native-maven-plugin</artifactId>
                    <version>1.1.2</version>
                    <extensions>true</extensions>
                    <configuration>
                        <mainClass>com.example.picoclidemo.filecli.FileCliCommand</mainClass>
                        <imageName>filecli</imageName>
                    </configuration>
                    <executions>
                        <execution>
                            <id>build-native</id>
                            <goals>
                                <goal>compile-no-fork</goal>
                            </goals>
                            <phase>package</phase>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </build>
    </profile>
</profiles>

mvn -Pnative package

./target/filecli stat README.md

<dependency>
    <groupId>info.picocli</groupId>
    <artifactId>picocli-spring-boot-starter</artifactId>
    <version>4.7.7</version>
</dependency>

package com.example.bootcli;
import org.springframework.stereotype.Component;
import picocli.CommandLine.Command;
import picocli.CommandLine.Option;
import java.util.concurrent.Callable;
@Component
@Command(name = "user", description = "用戶管理命令", mixinStandardHelpOptions = true)
public class UserCommand implements Callable<Integer> {
    private final UserService userService;
    @Option(names = "--list", description = "列出用戶")
    private boolean list;
    public UserCommand(UserService userService) {
        this.userService = userService;
    }
    @Override
    public Integer call() {
        if (list) {
            userService.findAll().forEach(System.out::println);
            return 0;
        }
        System.out.println("沒有指定操作");
        return 2;
    }
}

package com.example.bootcli;
import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import picocli.CommandLine;
import picocli.CommandLine.IFactory;
@SpringBootApplication
public class BootCliApplication implements CommandLineRunner {
    private final UserCommand userCommand;
    private final IFactory factory;
    public BootCliApplication(UserCommand userCommand, IFactory factory) {
        this.userCommand = userCommand;
        this.factory = factory;
    }
    public static void main(String[] args) {
        SpringApplication.run(BootCliApplication.class, args);
    }
    @Override
    public void run(String... args) {
        int exitCode = new CommandLine(userCommand, factory).execute(args);
        System.exit(exitCode);
    }
}

java -jar boot-cli.jar --list

命令類交給 Spring 管理
CommandLine 使用 Spring 提供的 IFactory 創(chuàng)建對象
子命令、轉(zhuǎn)換器等也可以走 Spring 注入

@Command(name = "hello")
class HelloCommand implements Callable<Integer> {
    @Parameters(index = "0")
    String name;
    PrintWriter out = new PrintWriter(System.out, true);
    @Override
    public Integer call() {
        out.println("Hello, " + name);
        return 0;
    }
}

package com.example.picoclidemo;
import org.junit.jupiter.api.Test;
import picocli.CommandLine;
import java.io.PrintWriter;
import java.io.StringWriter;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertTrue;
class HelloCommandTest {
    @Test
    void shouldPrintHello() {
        HelloCommand command = new HelloCommand();
        StringWriter output = new StringWriter();
        command.out = new PrintWriter(output);
        int exitCode = new CommandLine(command).execute("張三");
        assertEquals(0, exitCode);
        assertTrue(output.toString().contains("Hello, 張三"));
    }
}

@Test
void shouldReturnUsageExitCodeWhenMissingName() {
    int exitCode = new CommandLine(new HelloCommand()).execute();
    assertEquals(CommandLine.ExitCode.USAGE, exitCode);
}

new CommandLine(new AppCommand()).execute(args);

int exitCode = new CommandLine(new AppCommand()).execute(args);
System.exit(exitCode);

CommandLine.run(new AppCommand(), args);
CommandLine.call(new AppCommand(), args);

new CommandLine(new AppCommand()).execute(args);

@Option(names = "--verbose")
private Boolean verbose;

@Option(names = "--verbose")
private boolean verbose;

@Parameters
private Path source;
@Parameters
private Path target;

@Parameters(index = "0")
private Path source;
@Parameters(index = "1")
private Path target;

-a -b -c -x

@Option(names = {"-f", "--file"})
@Option(names = {"-o", "--output"})
@Option(names = {"-v", "--verbose"})

tool --password 123456

tool --password

@Option(names = "--password", interactive = true, arity = "0..1")
private char[] password;

@Command 定義命令
@Option 定義具名選項(xiàng)
@Parameters 定義位置參數(shù)
CommandLine.execute 負(fù)責(zé)解析和執(zhí)行
Callable<Integer> 返回退出碼
subcommands 組織復(fù)雜工具
Mixin 復(fù)用公共參數(shù)