跳到主要内容

arc completion

arc completion 把 bash / zsh / fish 的补全脚本打到 stdout——它自己从不写文件，落地成文件是你自己控制的一步。

arc completion 为你的 shell 生成一份 tab 补全脚本,打到 stdout。它从不往磁盘上写任何东西——把输出变成一个文件,或者追加进你 shell 的启动文件,是你自己动手的一步。

对照版本：arc 2.0.0-beta.48（commit 5a5316bde，main，2026-09-10）。复制下面任何内容前先跑 arc --version；生成的脚本可能随构建变化。

用法

bash
arc completion [shell]
  • shell：bash、zsh、或 fish。省略时 arc 从 $SHELL 探测；如果 $SHELL 没设置,或者设成了这三者之外的东西,就回落到 bash：
bash
$ env -i PATH="$PATH" SHELL=/bin/zsh arc completion | head -1
#compdef arc
$ env -i PATH="$PATH" SHELL=/usr/bin/tcsh arc completion | head -1
###-begin-arc-completions-###

生成脚本

三份脚本长度不一样——bash 自己做匹配和转义,zsh 把大部分工作交给 _describe,fish 只是一次 complete 调用：

bash
$ arc completion bash | wc -l
86
$ arc completion zsh | wc -l
67
$ arc completion fish | wc -l
14

三个合法值之外的 shell 名字,会像任何其它非法 choice 取值一样被拒绝——一个 yargs 校验错误,exit 5：

bash
$ arc completion nosuchshell
ERROR: Invalid values:
  Argument: shell, Given: "nosuchshell", Choices: "bash", "zsh", "fish"

（此处截断——剩下的部分和 arc completion --help 打印的文本相同）

怎么装

每份脚本自己的开头注释都写了该怎么装。arc completion <shell> 只打印,不会替你写到下面任何一个路径。

bash

bash
arc completion bash >> ~/.bashrc

macOS 上改用 ~/.bash_profile,脚本里的注释写的就是这个。开一个新 shell,或者 source 这个文件,就能生效。

zsh

bash
arc completion zsh >> ~/.zshrc

如果你的 ~/.zshrc 从没跑过 compinit,脚本第一次加载时会自己引导它,你不需要另外加这一步。它还会在每个 prompt 上重新注册自己,这样你环境里后面某处再跑一次 compinit 重建补全表时,不会悄悄把 arc 这条丢掉。

fish

bash
mkdir -p ~/.config/fish/completions
arc completion fish > ~/.config/fish/completions/arc.fish

mkdir -p 这一步很关键——> 不会自动建父目录,而 fish 只认已经在 ~/.config/fish/completions/ 里面的补全文件。

能补全什么

在下面任何一种位置按 Tab,装好的脚本都会去问正在跑的那个 arc 二进制该给什么——所以答案永远匹配你实际装的那个二进制,不是生成脚本那一刻定住的快照：

  • 命令名 —— arc d<TAB> 给出 did、deploy、drain、dsl
  • 子命令名 —— arc did <TAB> 给出 init、check、issue、verify、info、list、issuer
  • --instance / -i 取值 —— 和 arc service list 会显示的同一批名字,所以 arc service status -i <TAB> 只会给出你真的有的实例
  • --recipe / --template 取值 —— arc blocklet create --recipe <TAB> 给出和 arc blocklet create --help 列出的一样的选项：basic、blank、blog、agent、minimal-app、agent-workspace、support-community

除此之外的位置——比如 arc afs ls <TAB> 里的 AFS 路径——不属于上面任何一个槽位,脚本会落回你 shell 自带的普通文件名补全。

取值怎么落到命令行上

实例名和 recipe 名不是生成脚本那一刻定住的。每按一次键都会去查询你现在实际装的那个 arc 二进制,所以上周生成的脚本,照样能给出你五分钟前才建的实例。

不管取值里是什么字符,插入这一步也是安全的。bash 在插入每个候选值之前都用 printf %q 转义,所以一个字面上叫 my prod box 的实例,补全出来是安全的三段词 my\ prod\ box,不会拆成三个独立的词;一个含 shell 元字符的名字,永远不会被未转义地交给 shell。zsh 的 _describe 内置了同样的性质。

退出码

你跑了什么退出码
arc completion bash / zsh / fish0
arc completion（不带参数，探测到的 shell）0
arc completion <其它任何值>5