Part 1 got way more attention than I expected — 1500+ upvotes and 336 comments. I read every single one. Some confirmed my thinking, some challenged it, some taught me things I hadn't considered.
I noticed the same questions kept coming up. Here's my attempt to organize them.
1. First, a Clarification: CLI ≠ A Real Shell
The biggest misunderstanding from Part 1. Many people read "CLI" and assumed I meant "give the LLM a Linux terminal." That's not what I'm saying.
CLI is an interface protocol: text command in → text result out. You can implement it in two ways:
- As a binary or script in the shell's PATH — it becomes a CLI tool that runs in a real shell.
- As a command parser inside your code — when the LLM outputs
run(command="weather --city Tokyo"), you parse the string and execute it directly in your application code. No shell involved.
You just need the LLM to feel like it's using a CLI. That's it.
In my system, most commands never touch the OS. They're Go functions dispatched by a command router. Only commands that genuinely need a real OS — running scripts, installing packages — go to an isolated micro-VM. The agent doesn't know and doesn't care which layer handles its command.
2. Agent-Friendly CLI Design
How to design CLI tools that work well for agents.
2.1 Two Core Philosophies
Philosophy 1: Unix-Style Help Design
tool --help → list of top-level commandstool --help → specific parameters and usage for that subcommand
The agent discovers capabilities on demand. No need to stuff all documentation into context upfront.
Philosophy 2: Tips Thinking
Every response — especially errors — should include guidance that reduces unnecessary exploration.
Bad:
> cat photo.png [error] binary file
Good:
> cat photo.png [error] cat: binary file detected (image/png, 182KB). Use: see photo.png (view image) Or: cat -b photo.png (base64 encode)
Why this matters: invalid exploration wastes tokens. And in multi-turn conversations, this waste accumulates — every failed attempt stays in context, consuming attention and inference resources for every subsequent turn. A single helpful hint can save a significant amount of tokens across the rest of the conversation.
2.2 Safe CLI Design
When CLI commands involve dangerous or irreversible operations, the tool itself should provide safety mechanisms. There are two categories, serving different purposes:
Dry-Run / Change Preview — Preventing Mistakes
For operations that are within the agent's authority, but whose consequences are hard to reverse. The goal is to let the agent (or human) see what will happen before committing — catching parameter errors or unintended consequences. The agent can decide on its own whether to proceed. No human needs to be involved.
> dns update --zone example.com --record A --value 1.2.3.4 ⚠ DRY RUN: A record for example.com: 5.6.7.8 → 1.2.3.4 Propagation: ~300s. Not instantly reversible. To execute: add --confirm
The preview should clearly show what the current state is and what it will change to. The agent confirms with --confirm.
Human Authorization — Operations Beyond the Agent's Autonomy
For operations that require human judgment or approval — no matter how confident the agent is, it cannot complete these on its own. The following two approaches are equivalent, just different implementations:
Approach 1: Blocking Push Approval
> pay --amount 500 --to vendor --reason "office supplies for Q2" ⏳ Approval required. Notification sent to your device. Waiting for response... ✓ Approved. Payment of $500 completed. [exit:0 | 7.2s]
Like Apple's device login verification — the CLI sends a push notification directly to the human's device with full context (amount, recipient, reason). The CLI blocks until the human approves or rejects, then returns the result to the agent. The agent can see "Waiting for response" and the 7.2s duration — it knows it's waiting for human approval.
Approach 2: Verification Code / 2FA
> transfer --from savings --to checking --amount 10000 ⚠ This operation requires 2FA verification. Reason: transferring $10,000 between accounts. A code has been sent to your authenticator. Re-run with: --otp
The CLI explains why verification is needed — so the agent can relay this to the user. The agent pauses execution and asks the user for the OTP, explaining the reason (similar to how Claude Code behaves when it needs human input). Once the code is provided:
> transfer --from savings --to checking --amount 10000 --otp 847293 ✓ Transfer completed. [exit:0 | 1.1s]
Both approaches are equivalent — they introduce human authorization at critical operations. Which one you choose depends on your scenario and infrastructure.
2.3 Large Output → File
When results are large, tools should write the bulk to a file and return a short summary with a reference:
> search-docs "authentication flow" Found 47 results. Top 3: 1. docs/auth/oauth2.md (score: 0.95) 2. docs/auth/jwt.md (score: 0.88) 3. docs/api/middleware.md (score: 0.72) Full results: /tmp/search-results.json [exit:0 | 890ms]
The agent only pulls in what it actually needs.
2.4 Schema Design
Two parts:
Schema Display — auto-generated from --help, function signature as constraint:
> weather --help Get current weather for a city. Usage: weather [OPTIONS] Options: --city TEXT (required) --unit TEXT celsius or fahrenheit [default: celsius]
Schema Validation — the command validates input internally, returning actionable hints on error:
> weather --city [error] weather: --city requires a value. Usage: weather --city [--unit celsius|fahrenheit]
2.5 stdin Separation
Double-escaping is the biggest engineering tax of the CLI approach. The LLM outputs a JSON function call, and the command field contains a shell command. If the command has quotes or newlines → JSON escaping + shell escaping = double escape hell.
The fix: pass content through a separate stdin parameter, not through the command string:
# Instead of: run(command="write file.txt 'some \"complex\" content'") # Do: run(command="write file.txt", stdin="some \"complex\" content")
Content only needs one layer of escaping (JSON). This eliminated ~90% of our escaping issues.
3. How Agents Can Use CLI More Efficiently
What the framework layer does to wrap CLI output, helping agents work more effectively.
3.1 Output Truncation (Overflow Mode)
Covered in Part 1, recap here.
When output exceeds 200 lines or 50KB:
- Truncate to the first 200 lines (rune-safe, no broken UTF-8)
- Write the full output to a temp file
Return:
[first 200 lines of output]
--- output truncated (5000 lines, 198.5KB) --- Full output: /tmp/cmd-output/cmd-3.txt Explore: cat /tmp/cmd-output/cmd-3.txt | grep cat /tmp/cmd-output/cmd-3.txt | tail 100
This turns "large data exploration" into a skill the LLM already has — navigating files with grep, head, tail. No custom pagination API needed.
3.2 Never Drop stderr
When a command fails, stderr is the information the agent needs most.
I had a bug where my code silently dropped stderr whenever stdout was non-empty. The agent tried pip install pymupdf, got exit code 127. stderr contained bash: pip: command not found, but the agent couldn't see it. What followed:
pip install → 127 (doesn't exist) python3 -m pip → 1 (module not found) uv pip install → 127 (doesn't exist) apt-get install → 1 (permission denied) ...
10 calls, ~5 seconds of inference each. If stderr had been visible the first time, one call would have sufficed.
Always attach stderr on failure.
3.3 Output Cleaning & Adaptation
- ANSI escape codes (progress bars, colors) → strip at the framework level
- Interactive programs → require
--batch / --json / --no-interactive modes. If a tool doesn't support non-interactive mode, wrap it - sed is a trap → match strings must be exact, LLMs frequently get this wrong → provide dedicated
write / edit commands
3.4 Exit Code + Duration Metadata
Covered in Part 1, recap here.
This is a framework-level wrapper around CLI output, not something CLI tools do themselves:
file1.txt file2.txt dir1/ [exit:0 | 12ms]
After seeing [exit:N | Xms] dozens of times in a conversation, the agent internalizes the pattern:
exit:0 → success, move onexit:1 → check the error12ms → cheap, call freely45s → expensive, use sparingly
Consistent output format makes the agent smarter over time.
4. Understanding Agent Security
4.1 Errors Are Inevitable
Organizations make mistakes. Humans make mistakes. Agents will make mistakes. No schema validation eliminates this — delete_file(path="/") is perfectly valid JSON. Schema catches syntax errors, not semantic errors. Both paradigms face the same fundamental question: "should this action execute at all?"
4.2 Proactive Measures
We have proactive tools to reduce error probability and enable reflection when errors happen:
- Safe CLI design (Section 2.2) — dry-run previews, push approval, 2FA verification
- Audit logs — every
run() call is a plain string, trivially auditable and reproducible - Process documentation — recording what happened for post-error analysis and improvement
- Gates inside tools — each command knows its own risk level and self-gates accordingly. This is more fine-grained than wrapping an external approval layer around the entire agent
4.3 Define Boundaries, Then Accept
The core idea is not "make errors cheap." It's keep errors within expected bounds.
Define the agent's autonomy boundary:
- The agent can make payments up to $10 without approval — errors within this allowance are something you've pre-accepted
- Anything over $10 requires push approval or OTP verification (Section 2.2)
- The agent can do whatever it wants inside the sandbox — the worst case is the sandbox crashes, and you rebuild it
- The agent's network access has an allowlist — the scope of what it can reach is predefined
You're not hoping the agent won't make mistakes. You're designing a boundary, confirming that the worst case within that boundary is acceptable, and then letting the agent act autonomously within it.
5. Designing CLI Around Your Business
5.1 CLI Toolset = Agent Capability Boundary
Section 1 established that CLI doesn't have to be a real shell environment. So the set of CLI commands you expose defines the agent's action space — what it can and can't do is entirely determined by what commands you provide.
This connects directly to the security model in Section 4: by controlling the CLI surface, you control the agent's maximum possible impact.
5.2 Desire Path Design
A methodology I've found surprisingly effective for designing CLI tools.
I often start with a simple, minimal CLI design, then observe how the agent actually uses it. Errors are expected — that's the point. I watch: What non-existent commands does it try to call? How does it combine existing commands? Where does it get stuck?
Then I redesign the CLI based on the paths the agent naturally wants to take. Like desire paths in landscape design — pave where people actually walk, not where you think they should walk.
This often produces better results than upfront design alone.
5.3 Putting It All Together — E-Commerce Example
Let's see the techniques from earlier sections in a complete agent session. Say your agent is a shopping assistant.
Agent doesn't know the tools → --help discovery (2.1 Philosophy 1)
> shop [error] shop: unknown command. Available: search, order, pay, cart, track Try: search --help [exit:127 | 2ms]
Agent explores a subcommand
> search --help Search products in the catalog. Usage: search [OPTIONS] Options: --size INT Filter by size --max-price INT Maximum price in USD --sort TEXT Sort by: price-asc, price-desc, relevance [default: relevance] [exit:0 | 1ms]
Agent makes an error → Tips guidance (2.1 Philosophy 2)
> search --size 42 [error] search: is required. Usage: search [--size INT] [--max-price INT] Example: search "red shoes" --size 42 [exit:1 | 1ms]
Agent searches → large output to file (2.3) + metadata (3.4)
> search "red shoes" --size 42 --max-price 100 Found 23 results. Top 3: 1. Nike Air Max 90 - $89 (SKU: NK-AM90-42) 2. Adidas Ultraboost - $95 (SKU: AD-UB-42) 3. New Balance 574 - $72 (SKU: NB-574-42) Full results: /tmp/search-results.json [exit:0 | 340ms]
Agent places order → dry-run preview (2.2)
> order create --sku NK-AM90-42 --qty 1 --address "123 Main St" ⚠ DRY RUN: Item: Nike Air Max 90, Size 42 Price: $89.00 + $5.99 shipping = $94.99 Ship to: 123 Main St To confirm: add --confirm [exit:0 | 45ms]
Agent confirms the order
> order create --sku NK-AM90-42 --qty 1 --address "123 Main St" --confirm ✓ Order ORD-789 created. [exit:0 | 220ms]
Agent pays → push approval, waiting for human (2.2)
> pay --order ORD-789 --method credit-card ⏳ Approval required. Notification sent to your device. Amount: $94.99 → Visa ending 4242 Waiting for response... ✓ Approved. Payment completed. [exit:0 | 7.2s]
Schema validation error (2.4)
> pay --order ORD-000 --method bitcoin [error] pay: invalid payment method "bitcoin". Supported: credit-card, debit-card, paypal Usage: pay --order --method [exit:1 | 3ms]
Shell primitives for orchestration — one call, multiple operations
> order create --sku NB-574-42 --confirm && pay --order $(order list --latest --id-only) --method paypal ✓ Order ORD-790 created. ⏳ Approval required. Notification sent to your device. Amount: $77.99 → PayPal (user@email.com) Waiting for response... ✓ Approved. Payment completed. [exit:0 | 8.1s]
When the agent's entire domain is shopping, commands are top-level — no shop prefix needed. Like git has commit, push, pull. Each command is a thin wrapper over your backend API. The agent never touches the backend directly.
6. Q&A
Q: Can't dynamic typed tools solve the discovery problem too?
Yes, but with two costs.
First, dynamically changing tool definitions in the LLM API breaks the KV cache prefix. Every time you add or remove a tool, the system prompt region must be recomputed. With a single run() tool, the definition never changes — the cache prefix stays stable across the entire conversation.
Second, you lose CLI's composability benefits.
You can integrate dynamic discovery into the CLI approach: design a cli-search command (backed by RAG, for example), or when the agent calls a non-existent command, have the framework automatically route it to cli-search and return the results. Same effect, no tool definition changes.
Q: Why not Python / CodeAct?
CLI is the superset. Shell can call code naturally (python -c "..."), but code calling CLI requires subprocess wrappers. pip list is itself a CLI command.
--help is a zero-cost discovery protocol. There's no equivalent in Python — you either stuff documentation into context (expensive) or invent your own discovery mechanism.
7. Related Resources
Projects and articles mentioned in the discussion:
8. Things I Haven't Figured Out Yet
Open questions:
- Tool discovery —
--help solves using known tools, but how does the agent discover tools it doesn't know exist? cli-search (see Q&A) is one direction, but a complete solution isn't there yet - Multimodal I/O — how to handle image/audio/binary data in a text-stream paradigm
Directions I'm actively exploring:
- Simple demos — minimal implementations people can run immediately to experience the approach
- Small models + CLI — CLI use might work surprisingly well with smaller models (Qwen 3.5). Every agent session naturally produces (task, command, output) training data. With some targeted fine-tuning, the results might be quite good. No data yet — no claims
Thanks to everyone who participated in the discussion. Through the process of talking with all of you, many of my own ideas became clearer, and I discovered some unexpected directions I hadn't considered before.
Happy to discuss — especially if you've tried similar approaches or found cases where CLI breaks down.
非常感谢大家昨天的回复，有两个地方解释一下：
- 关于 LLM 生成的内容
- 我本身是一个脑子比嘴快的人，所以就算在中文环境下，我也会使用 opus/gemini pro/gpt-5.4 这些 sota 模型来帮我梳理思路，把临时的想法（甚至是一些破碎的、毫无语法逻辑的词语）整理成内容
- 有时候我会觉得 LLM 生成的内容因为 markdown 语法可读性会更高，比如表格、黑体、blockquote，这些如果让我自己手打我真的会懒得去写，所以虽然有些朋友会觉得这些非常有 AI 味，但为了信息的传递和表达，我还是保留了
- 虽然我大量地使用 LLM，但是内容在发出前，我都会自己看一遍，去检查内容是否和我思考的一致
- 我会学好英语的！（虽然这句话我说了很多年😂）
- 推特&GitHub 上 yan5xu 也是我，morrohsu 是我早期使用的英文网名，reddit 无法修改，所以就沿用下来了
