How Much of Writing CLI Tool Documentation Can AI Take Over?
A Common Scenario
You've built a CLI tool with plenty of features—twenty-plus commands and all kinds of parameters. Users' first question is always: "How do I use this tool?"
So now you have to write a user manual. For indie developers and small teams, this is arguably the least cost-effective task in the world:
- You spent two weeks writing the code, and now you need another two weeks for the docs. And writing docs is nowhere near as enjoyable as writing code.
- The manual starts going stale the moment it's finished. The next version changes a parameter, nobody updates the docs, users follow the outdated manual, hit errors, and start ranting in the issue tracker.
- The people on the team who know the tool best are precisely the ones with the least time to write docs. The result is documentation at the level of "anyone who can understand it didn't need to read it in the first place."
My own experience: a manual covering 20 commands takes about 10–15 hours of focused time for the first draft, not counting ongoing maintenance—and that's with me knowing the tool inside out.
This article covers: how much of this work AI can take over, and how to turn it into a repeatable process.
First, Be Clear: What AI Can and Cannot Do
What AI can do:
- Extract the command inventory from code. Feed it your CLI entry file and argument-parsing code, and it can produce a complete table of commands, parameters, and default values. This used to be the most tedious "grunt work," accounting for over 40% of total writing time.
- Generate standard-structure documentation for each command. Usage, parameter descriptions, examples, common errors—AI generates first drafts in bulk using a unified template, and you just proofread.
- Translate error messages into plain language. Users have no idea what
ERR_PIPE_BREAKmeans; AI can generate corresponding troubleshooting guides based on your error-handling code. - Ongoing maintenance. After a version update, feed the diff to AI and have it flag the sections in the manual that need to be updated. This turns documentation maintenance from "whenever I remember" into "something I do along the way."
What AI cannot do:
- It has never used your tool, so it doesn't know which parameter combinations are easy to trip over in practice. That kind of "battle-tested experience" has to come from you.
- It will confidently fabricate parameters that don't exist. Every AI-generated command example must actually be run—this is the bottom line, no exceptions.
The Concrete Process: How to Split Two Evenings
First evening (~2–3 hours): Build the skeleton
- Gather materials: CLI entry code,
--helpoutput, parameter definition files. If you use argparse / click / cobra, just give the definition files to the AI—the structure will be clearest. - Use the prompt template (see below) to have AI generate first drafts of documentation for all commands.
- Run every example command one by one; delete the ones that don't work and fix any inconsistent outputs.
Second evening (~2 hours): Add the flesh
- Manually add to the FAQ the questions you've repeatedly answered in user groups and the issue tracker. AI can't generate this, but it's the most valuable part.
- Have AI read through the manual from a user's perspective and list places with "explanation gaps"—it plays the role of a reader encountering the tool for the first time, and it works surprisingly well.
- Finalize and publish.
Prompt Template
Copy-ready—just replace the bracketed content with your own:
你是一位技术文档工程师。请为我的 CLI 工具生成使用手册初稿。
## 工具信息
- 工具名称:[名称]
- 工具用途:[一句话说明]
- 目标用户:[如:独立开发者 / 运维人员]
## 命令定义
[粘贴 argparse/click/cobra 的参数定义代码,或 --help 的完整输出]
## 要求
1. 手册结构:
- 快速开始(5 分钟内能跑通第一个命令)
- 命令参考(每个命令包含:用途、语法、参数表格、1-2 个可运行示例、常见报错及排查)
- FAQ(基于参数的常见误用)
2. 每个示例命令必须只使用上文定义过的参数,禁止推测不存在的参数。
3. 参数说明中标注默认值和取值范围。
4. 语言风格:直接、简短,不用营销语气。
5. 不确定的地方用 [待确认] 标记,不要编造。
先输出手册目录结构给我确认,再逐节输出内容。That last line—"output the table of contents first"—is critical. If the structure is wrong, redo it. That saves far more time than revising a complete draft.
Before and After Comparison
| Task | Pure Manual Writing | AI-Assisted |
|---|---|---|
| Compiling the command inventory | 2–3 hours | 20 minutes (AI-generated + manual verification) |
| First draft per command | Avg. 20 min/command × 20 ≈ 7 hours | ~1 hour (bulk generation + proofreading) |
| Verifying examples | 1 hour | 1 hour (this step can't be skipped) |
| Writing the FAQ | 2 hours | 2 hours (mostly manual) |
| Sync maintenance on version updates | 1–2 hours each time, often skipped | 20 minutes each time, diff handed to AI for locating changes |
| Total for first draft | ~13–15 hours | ~4–5 hours |
Beyond the time cost, there's a hidden cost: manually written manuals tend to have inconsistent structure (you get tired by the tenth command), while AI-generated structure is naturally consistent—new commands can simply follow the template.
A Few Common Pitfalls
- Don't let AI "read" your entire repository. Instead of letting it guess, cut out the parameter definition code yourself first. The more precise the input, the more precise the output.
- Examples must be actually run. Roughly 10–20% of AI-generated example commands contain detail errors (parameter typos, path assumptions). Full verification is the only reliable approach.
- Don't outsource the FAQ to AI. Questions real users have asked are far more valuable than "frequently asked questions" the AI imagines.
- Keep the "[to be confirmed]" mechanism. Forcing AI to admit uncertainty significantly reduces fabrication.
Final Thoughts
CLI tool documentation has long lived in the state of "important but not urgent, so there's never time for it." The point of an AI-assisted process isn't to make the docs fancier—it's to push the cost down to the level of "something you can just do along the way": cutting first-draft time by two-thirds, and reducing maintenance costs to the point where docs can be updated alongside each release.
If you use AI heavily in your workflow, model API costs are also worth calculating carefully. Connecting to a multi-model platform and choosing the right model per task is a common way to control costs—check out https://api.thistoken.ai/register. After signing up, you can call a variety of models on demand; see the official pricing page for details.
---
Ready to try it yourself? Sign up at https://api.thistoken.ai/register to get your API key and start building.
Token.AI を試してみませんか?
プロジェクトレベルの API Key を作成し、コンソールでチャネルを有効にして、ルーティング、予算、監査ログを設定しましょう。
注册 ThisToken.AI 并获取 API Key