Chapter 17 · Tool System and CLI Reference

Chapter goals: Clarify what each of pi's 7 built-in tools can do, master using CLI args to precisely control工具可用性, and收 the full CLI参数表 into your quick-reference handbook.

17.1 Built-in Tool Checklist

pi's built-in tools共 7 (official CLI reference: read, bash, edit, write, grep, find, ls):

Tool	Responsibility	Typical Use
read	Read files	View source code, config
write	Write files	Create new files
edit	Precise file editing	Modify code, config
bash	Execute shell commands	Run tests, git ops, builds
grep	Content search	Find patterns in the codebase
find	Filename lookup	Locate file positions
ls	List directories	Browse project structure

Note two design philosophies: no built-in web scraping / fancy terminal UI tools —补 via extensions or skills if needed; bash is the universal backdoor — even if其他 tools are disabled, as long as bash is available the model can理论上 still间接完成读写; so "read-only review" scenarios mustexclude bash as well.

🪟 Windows exclusive: PowerShell tool (0.84.3+): The optional powershell tool executes commands on Windows via pwsh.exe (fallback to Windows PowerShell if unavailable), with startup params -NoProfile -NonInteractive -ExecutionPolicy Bypass. Enable or replace bash via defaultTools:

{ "defaultTools": ["read", "powershell", "edit", "write"] }

17.2 Controlling Tool Availability with Tool Options

CLI provides four tiers of switches (parenthesized areabbreviations):

# Whitelist mode: only these 4 read-only tools — the官方推荐的 "Read-only mode"
pi --tools read,grep,find,ls -p "Review the code"
pi -t read,grep,find,ls "..."            # equivalent shorthand

# Blacklist mode: disable just one tool (incl built-in, extension, and custom)
pi --exclude-tools ask_question
pi -xt bash "Refactor this code"               # disable bash,逼 the model use read/write/edit

# Close all built-in tools but保留 extension-registered custom tools
pi --no-builtin-tools

# All tools closed — pure conversation mode; the model can only回答 with language
pi --no-tools "Explain the CAP theorem"

Selection strategy:

• Code review / architecture Q&A → -t read,grep,find,ls;杜绝 any write;
• Just want to block onedangerous action → -xt bash or -xt write;
• Let extensions fully接管 the toolset → --no-builtin-tools;
• Pure text tasks → --no-tools is最省心 and safest.

Tool Whitelist ≠ Safety Boundary

The official security doc明确: these options are 行为控制 not sandboxing. Real隔离 must come from containers or micro VMs (see Chapter 19). Do not treat -t read,... as adefense against malicious repos.

17.3 CLI Parameter Quick Reference

Full syntax: pi [options] [@files...] [messages...]. Grouped by function (consistent with the official README's CLI Reference):

Run Modes

Param	Description
(default)	Interactive TUI
-p / --print	Output response then exit
--mode json	JSON Lines event stream output
--mode rpc	RPC process integration mode
--export <in> [out]	Export a session as HTML

Model-Related

Param	Description
--provider <name>	Specify provider (anthropic/openai/google, etc.)
--model <pattern>	Model pattern or ID; supports provider/id:thinking
--api-key <key>	Temporarily specify an API key (overrides env vars)
--thinking <level>	Thinking level: off/minimal/low/medium/high/xhigh/max
--models <patterns>	Model list for Ctrl+P cycling
--list-models [search]	List available models

Session-Related

Param	Description
-c / --continue	Continue the most recent session
-r / --resume	Browse and select a historical session
--session <path|id>	Use a specified session file or UUID prefix
--fork <path|id>	Fork a new session from an existing one
--session-dir <dir>	Custom session storage directory
--no-session	Temp mode; no persistence
-n <name>	Name the session at startup

Resource Loading

Param	Description
-e <source>	Load an extension (path/npm/git);可重复
--skill <path>	Load a skill;可重复
--prompt-template <path>	Load a prompt template;可重复
--theme <path>	Load a theme;可重复
--no-extensions / --no-skills etc.	Disableauto-discovery for that resource type
--no-context-files (-nc)	Do not load AGENTS.md / CLAUDE.md

System Prompt

# Replace the default system prompt entirely (context files and skills still append)
pi --system-prompt "You are an assistant that only answers Go questions"

# Only append
pi --append-system-prompt "All answers in Chinese"

17.4 Combined Practical Examples

拼起来就是各种标准工作姿势:

# 1. Batch doc translation with a cheap小模型 (unattended)
for f in docs/en/*.md; do
  pi --model openai/gpt-4o-mini --no-session -p "Translate @$f to Chinese; output only the translation" \
    > "docs/zh/$(basename "$f")"
done

# 2. High-thinking-level攻坚复杂 bug
pi --model sonnet:high "This concurrency deadlock only出现s on Fridays; help me排查"

# 3. Read-only mode +禁用 context files; audit an陌生 repo
cd /tmp/untrusted-repo
pi -t read,grep,find,ls --no-context-files -p "Summarize this project's entry and deps"

# 4. Precisely replicate a colleague's debugging scene: fork from a session ID
pi --session 9f2c1a3b --fork

17.5 Chapter Summary

• 7 built-in tools: read/write/edit/bash/grep/find/ls; bash is both the capability上限 and the risk上限;
• Four control tiers: --tools whitelist > --exclude-tools blacklist > --no-builtin-tools > --no-tools;
• Tool switches are行为约束 not sandbox;
• Models可 provider/id:thinking shorthand one-step;
• --system-prompt replaces; --append-system-prompt appends.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. What is the官方推荐的 "read-only review" command写法?

2. What is the difference between --no-tools and --no-builtin-tools?

3. To开 a new exploration branch from a point in the current session history, use?

4. In pi --model sonnet:high, what does ":high" mean?

🛠️ Hands-on Practice

1. Use --tools, --exclude-tools, and --no-tools三种方式 to let pi "only explain, not modify" your project;对比 the three approaches' response差异.
2. Use --list-models to找出 your cheapest available model; write a batch script to rename markdown headings.
3. Use --fork to复制 an old session;尝试 different refactoring approaches on the新 branch; then use /tree to回看 the fork点.