Back to Details

cli-for-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLI for agents

面向Agent的CLI

Human-oriented CLIs often block agents: interactive prompts, huge upfront docs, and help text without copy-pasteable examples. Prefer patterns that work headlessly and compose in pipelines.
面向人类的CLI通常会阻碍Agent运行：比如交互式提示、冗长的前置文档，以及没有可复制粘贴示例的帮助文本。优先采用支持无头运行且可在管道中组合的模式。

Non-interactive first

优先非交互式

  • Every input should be expressible as a flag or flag value. Do not require arrow keys, menus, or timed prompts.
  • If flags are missing, then fall back to interactive mode—not the other way around.
Bad: 
mycli deploy
→ 
? Which environment? (use arrow keys)

Good: 
mycli deploy --env staging
  • 所有输入都应能通过标志或标志值来指定。不应要求使用方向键、菜单或定时提示。
  • 如果缺少标志，再回退到交互式模式——而不是反过来。
反面示例： 
mycli deploy
→ 
? Which environment? (use arrow keys)

正面示例： 
mycli deploy --env staging

Discoverability without dumping context

无需冗余上下文即可实现可发现性

  • Agents discover subcommands incrementally: 
    mycli
    , then 
    mycli deploy --help
    . Do not print the entire manual on every run.
  • Let each subcommand own its documentation so unused commands stay out of context.
  • Agent会逐步发现子命令：先执行
    mycli
    ，再执行
    mycli deploy --help
    。不要在每次运行时都打印完整手册。
  • 让每个子命令管理自己的文档，这样未使用的命令就不会干扰上下文。

--help
that works

实用的
--help

  • Every subcommand has 
    --help
    .
  • Every 
    --help
    includes Examples with real invocations. Examples do more than prose for pattern-matching.
text
Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --force   Skip confirmation

Examples:
  mycli deploy --env staging
  mycli deploy --env production --tag v1.2.3
  mycli deploy --env staging --force
  • 每个子命令都配有
    --help
    。
  • 每个
    --help
    都包含示例，展示真实的调用方式。对于模式匹配来说，示例比文字说明更有效。
text
Options:
  --env     Target environment (staging, production)
  --tag     Image tag (default: latest)
  --force   Skip confirmation

Examples:
  mycli deploy --env staging
  mycli deploy --env production --tag v1.2.3
  mycli deploy --env staging --force

stdin, flags, and pipelines

标准输入、标志与管道

  • Accept stdin where it makes sense (e.g. 
    cat config.json | mycli config import --stdin
    ).
  • Avoid odd positional ordering and avoid falling back to interactive prompts for missing values.
  • Support chaining: 
    mycli deploy --env staging --tag $(mycli build --output tag-only)
    .
  • 在合理场景下接受标准输入（例如 
    cat config.json | mycli config import --stdin
    ）。
  • 避免奇怪的参数位置排序，避免因缺少值而回退到交互式提示。
  • 支持链式调用：
    mycli deploy --env staging --tag $(mycli build --output tag-only)
    。

Fail fast with actionable errors

快速返回可操作的错误

  • On missing required flags: exit immediately with a clear message and a correct example invocation, not a hang.
text
Error: No image tag specified.
  mycli deploy --env staging --tag <image-tag>
  Available tags: mycli build list --output tags
  • 当缺少必填标志时：立即退出并返回清晰的消息，以及正确的示例调用，不要挂起。
text
Error: No image tag specified.
  mycli deploy --env staging --tag <image-tag>
  Available tags: mycli build list --output tags

Idempotency

幂等性

  • Agents retry often. The same successful command run twice should be safe (no-op or explicit "already done"), not duplicate side effects.
  • Agent经常会重试命令。成功执行的同一命令运行两次应是安全的（无操作或明确提示“已完成”），不会产生重复的副作用。

Destructive actions

破坏性操作

  • Add 
    --dry-run
    (or equivalent) so agents can preview plans before committing.
  • Offer 
    --yes
    / 
    --force
    to skip confirmations while keeping the safe default for humans.
  • 添加
    --dry-run
    （或等效参数），让Agent在提交前可以预览执行计划。
  • 提供
    --yes
    / 
    --force
    参数以跳过确认，同时为人类用户保留安全的默认设置。

Predictable structure

可预测的结构

  • Use a consistent pattern everywhere, e.g. 
    resource
    + 
    verb
    : if 
    mycli service list
    exists, 
    mycli deploy list
    and 
    mycli config list
    should follow the same shape.
  • 在所有地方使用一致的模式，例如「资源 + 动词」：如果存在
    mycli service list
    ，那么
    mycli deploy list
    和
    mycli config list
    也应遵循相同的结构。

Success output

成功输出

  • On success, return machine-useful data: IDs, URLs, durations. Plain text is fine; avoid relying on decorative output alone.
text
deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s
  • 成功时返回机器可解析的数据：ID、URL、时长。纯文本即可；避免仅依赖装饰性输出。
text
deployed v1.2.3 to staging
url: https://staging.myapp.com
deploy_id: dep_abc123
duration: 34s

When reviewing an existing CLI

评审现有CLI时

  • Check: non-interactive path, layered help, examples on 
    --help
    , stdin/pipeline story, error messages with invocations, idempotency, dry-run, confirmation bypass flags, consistent command structure, structured success output.
  • 检查以下内容：非交互式执行路径、分层帮助、
    --help
    中的示例、标准输入/管道支持、带调用示例的错误消息、幂等性、dry-run、确认跳过标志、一致的命令结构、结构化的成功输出。