进阶 oclif.io 2026-10-18 02:37:03 · 27 阅读

第26章 命令 Flag 详解

# 第26章 命令标志(Flags) Flag 是传给命令的非位置参数。Flag 分两类:需要接收参数的选项 flag,以及不需要参数的布尔 flag。选项 flag 必须带有参数。 例如,如果这样运行命令: $ mycli --force --file=./myfile
那么声明方式如下: import {Command, Flags} from '@oclif/core'

export class MyCLI extends Command {
static flags = {
// 可以传 --force 或 -f
force: Flags.boolean({char: 'f'}),
file: Flags.string(),
}

async run() {
const {flags} = await this.parse(MyCLI)
if (flags.force) console.log('--force is set')
if (flags.file) console.log(`--file is: ${flags.file}`)
}
}
oclif 支持多种灵活的 flag 输入方式。 flag 可配置的选项如下: static flags = {
name: Flags.string({
// 以下选项既适用于布尔 flag,也适用于选项 flag(如 string、integer、url、custom 等)
char: 'n', // flag 的简写形式
summary: 'brief summary', // flag 的帮助摘要
helpLabel: '--my-flags', // 帮助信息中显示的 flag 标签,默认为 "[-] --",且仅在定义了 char 时才显示 -
helpGroup: 'THE BEST FLAGS', // 在帮助信息中把 flag 归入 THE BEST FLAGS 分组
description: 'in-depth overview', // flag 的帮助详细描述
hidden: false, // 在帮助信息中隐藏
multiple: false, // 允许多次传入该 flag
env: 'MY_NAME', // 默认取环境变量的值
options: ['a', 'b'], // 只允许取离散集合中的值
parse: async input => 'output', // 返回转换后的值,而非用户原始输入
default: 'world', // flag 未传入时的默认值(可以是返回字符串或 undefined 的异步函数)
defaultHelp: 'a dynamic value' // 帮助信息中展示的动态默认值(如当前工作目录),可以是返回字符串或 undefined 的异步函数
required: false, // 将 flag 设为必填 aliases: ['username', 'u'], // 标志的别名 - 可以是短字符或长标志
charAliases: ['u', 'n'], // 标志的单字符别名
deprecated: false, // 将标志标记为已弃用。
deprecateAliases: false, // 每当提供标志别名时发出弃用警告
noCacheDefault: false, // 若为 true,defaultHelp 返回的值将不会缓存在 oclif.manifest.json 中。
dependsOn: ['extra-flag'], // 此标志依赖另一个标志
exclusive: ['extra-flag'], // 此标志不能与该其他标志同时指定
exactlyOne: ['extra-flag', 'another-flag'], // 必须且只能提供这些标志中的一个
compatible: ['extra-flag'], // 此标志只能与提供的标志组合使用
relationships: [ // 定义标志间的复杂关系
// 使此标志依赖于所有这些标志
{type: 'all', flags: ['flag-one', 'flag-two']}
// 使此标志依赖于这些标志中的至少一个
{type: 'some', flags: ['flag-three', 'flag-four']}
// 使此标志与所有这些标志互斥
{type: 'none', flags: ['flag-five', 'flag-six']}
// 使此标志仅与这些标志兼容
{type: 'only', flags: ['flag-one', 'flag-two']}

// 使此标志依赖于所有这些标志
{type: 'all', flags: [
'flag-one',
'flag-two',
// 仅在 flag-eight 等于 FooBar 时包含 flag-seven
{name: 'flag-seven', when: async (flags) => flags['flag-eight'] === 'FooBar'}
]}
],
// 以下属性不能设置在布尔型标志上
helpValue: '', // 帮助中显示的标志值。默认为“”,
multipleNonGreedy: false, // 每个标志解析一个值,允许 `-m val1 -m val2` 但不允许 `-m val1 val2`。仅在 multiple 设为 true 时生效
delimiter: ',' // 用于分隔多值标志值的分隔符。仅在 multiple 设为 true 时生效。默认行为是按空格分隔。
allowStdin: false, // 当提供值为 `-` 时,允许从标准输入(stdin)读取值。也可以设置为 `only`,以便在即使未提供值的情况下也始终从标准输入读取。
}),

// 无值标志 (-f, --force)
force: Flags.boolean({
// 布尔标志除了之前示例中描述的属性外,还支持:
allowNo: true // 支持通过 `--no-` 前缀的可反转布尔标志(例如 `--no-force`)。此功能默认处于禁用状态。
}),
}
自定义标志(Custom Flags) 对于大型 CLI 工具,声明一个可供多个命令共享的自定义标志会非常有用。以下是一个自定义标志的示例: // src/flags.ts
import {Flags} from '@oclif/core'

class Team {
public name: string;
// 等等...
}

function getTeam(): Promise {
// 想象一下,这里是通过读取配置文件等方式来查找团队
return new Team()
}

export const team = Flags.custom({
char: 't',
description: '使用的团队',
default: async () => getTeam(),
})

// src/commands/mycommand.ts
import {team} from '../flags'
import {Command} from '@oclif/core'

export class MyCLI extends Command {
static flags = {
team: team({
required: true,
}),
}

async run() {
const {flags} = await this.parse(MyCLI)
if (flags.team) console.log(`--team is ${flags.team.name}`)
}
}
在 Salesforce CLI 中,我们大量使用自定义标志。例如: 一个 salesforceId 标志,确保提供的字符串是有效的 Salesforce Id。 一个 duration 标志,将提供的整数转换为 Duration 实例,用于处理基于时间的数值。 如果你想查看更多示例,可以在这里找到这些代码。你还可以阅读 API 文档。 替代标志输入(Alternative Flag Inputs) 以下是用户使用输入标志的其他几种方式。假设该命令包含类似 -f, --file=file 和 -v, --verbose(字符串标志和布尔标志)的标志: $ mycli --verbose
$ mycli -v
$ mycli --file=foo
$ mycli --file foo
$ mycli -f foo
$ mycli -f=foo
$ mycli -ffoo
$ mycli -vffoo
最后一种写法乍看之下有点奇怪,但在 Unix 中相对标准,这使得诸如 tar -xvzfmytarball.tar.gz 之类的命令成为可能。 要深入了解 CLI 标志,请阅读我们的博客文章《CLI 标志解析》。

评论 (0)