进阶 oclif.io 2026-10-18 02:37:03 · 21 阅读
第2章 详解 oclif 中的 CLI 参数与 Flag 用法
# CLI Flags 详解
2019年2月20日 · 阅读约5分钟
Casey Watts 和 Jeff Dickey
oclif 让在 node 中创建命令行界面(CLI)变得非常简单。大多数命令都有参数——也叫 "flags"、"args",有时也叫 "options"。这篇文章会解释这些参数是什么、什么时候用,同时介绍一个新功能,可以帮助用户在使用参数时更容易发现拼写错误。
需要说明的是,下文描述的是 GNU 风格的 flags。并非所有 CLI 都遵循这一约定,但它是最常用的。
## 词法构成
任何命令行命令都有几个标准的"词法构成"。作为 CLI 工具的使用者,了解它们可以帮助你减少拼写错误,也能让你更快看懂别人分享给你的复杂命令。如果你在设计 CLI 工具,理解这些概念就更加重要了——这样你才能为用户设计出最符合人体工学的接口。
向 CLI 命令传递数据的方式有很多,其中三种是位于命令"右侧"的参数,分别是:argument、short flag 和 long flag。
## 以 ls 为例
`ls` 是最常见、最简单的 unix 命令之一,作用是"列出"目录内容。
### command
```
ls
```
`ls` 本身就是一个独立的命令,不带任何参数时会列出当前文件夹的内容,隐含使用 `.` 目录。
### argument
```
ls .
ls ~/code/some-repo-name
```
如果给命令传入 argument,比如目录名 `.`(当前文件夹)或 `~/code/some-repo-name`,它就会列出对应目录的内容。
argument 就是命令右侧所有非 flag 的内容,可以出现在 flag 之前或之后。
### Long flag
要列出通常被隐藏的文件(比如 `~/.bashrc`),可以给 `ls` 加一个 flag。`ls --all` 是 long flag 形式——long flag 总是用双横线,并且由多个字符组成。
```
ls --all
ls . --all
```
### Short flag
这个 flag 还有 short flag 形式:`ls -a`。这里的 `a` 是 `all` 的缩写。short flag 总是用单横线,并且由单个字母组成。
```
ls -a
ls . -a
```
short flag 还可以连写,不必每个都加横线,顺序也不影响结果(除非传的是 flag argument)。
```
ls -la
```
Flag arguments
许多 flags 接受一个选项,即“flag 参数”(与“命令参数”相对)。通常,命令的参数顺序可以任意,但接受选项的 flag 必须紧随其后。
举个例子,下面的 -x flag 不接受选项,而 -f flag 接受。archive.tar 就是传给 -f 的选项。
tar -x -f archive.tar
tar -xf archive.tar
Flag 与其选项之间可以用空格 或等号 = 分隔。有趣的是,短 flag(但长 flag 不行)甚至可以省略空格,尽管多数人认为加空格或等号更易读。 以下三种形式均有效且等价: tar -f archive.tar
tar -f=archive.tar
tar -farchive.tar
长 flag 必须用空格或等号将 flag 与其选项分隔开。 git log --pretty=oneline
git log --pretty oneline
其他传数据方式 我们已经讲了参数(arguments)、短 flag 和长 flag。向命令传数据的还有两种方式:环境变量("env vars")或标准输入("stdin")。本文不深入介绍这些。 设计一个 Command 场景:我们要设计一个 oclif command,回显输入如 "Casey",并返回 "hi, Casey!"。用户有多种传参方式,下面展示每种输入类型的示例。 argument greet-me Casey
带参数的短 flag greet-me -n Casey
greet-me -n=Casey
greet-me -nCasey
带参数的长 flag greet-me --name=Casey
greet-me --name Casey
环境变量 NAME=Casey greet-me
标准输入 echo "Casey" | greet-me
Command 人体工学 短 flag 与长 flag 许多 CLI 命令同时支持长 flag 和短 flag 形式。在 Heroku CLI 中,每个 flag 至少有一个长 flag 形式,约一半的 flag 还配有短 flag 形式。 长 flag 形式更易读,但键入字符更多。当你希望他人快速理解某条命令语句时(例如在 README 中),长 flag 最有用。 短 flag 形式键入更快,更适合常用命令。短 flag 在多个短 flag 堆叠使用时尤其方便。
tar -xf archive.tar
Flag 与其选项之间可以用空格 或等号 = 分隔。有趣的是,短 flag(但长 flag 不行)甚至可以省略空格,尽管多数人认为加空格或等号更易读。 以下三种形式均有效且等价: tar -f archive.tar
tar -f=archive.tar
tar -farchive.tar
长 flag 必须用空格或等号将 flag 与其选项分隔开。 git log --pretty=oneline
git log --pretty oneline
其他传数据方式 我们已经讲了参数(arguments)、短 flag 和长 flag。向命令传数据的还有两种方式:环境变量("env vars")或标准输入("stdin")。本文不深入介绍这些。 设计一个 Command 场景:我们要设计一个 oclif command,回显输入如 "Casey",并返回 "hi, Casey!"。用户有多种传参方式,下面展示每种输入类型的示例。 argument greet-me Casey
带参数的短 flag greet-me -n Casey
greet-me -n=Casey
greet-me -nCasey
带参数的长 flag greet-me --name=Casey
greet-me --name Casey
环境变量 NAME=Casey greet-me
标准输入 echo "Casey" | greet-me
Command 人体工学 短 flag 与长 flag 许多 CLI 命令同时支持长 flag 和短 flag 形式。在 Heroku CLI 中,每个 flag 至少有一个长 flag 形式,约一半的 flag 还配有短 flag 形式。 长 flag 形式更易读,但键入字符更多。当你希望他人快速理解某条命令语句时(例如在 README 中),长 flag 最有用。 短 flag 形式键入更快,更适合常用命令。短 flag 在多个短 flag 堆叠使用时尤其方便。