命令

CtxCtl 共有六个命令。每次调用都自包含：解析、打印、退出。

命令	用途
outline <file>	符号大纲 + token 节省统计
symbol <file> --name <s>	单个符号的原始源码切片（--compact、--signature、--lines）
read <file> --lines 100-150,200-210	原始行区间切片（不走 AST）
deps <file>	导入/模块依赖图（本地 / 外部 / 忽略）
exec <cmd> [--keep <pat>]	运行命令并压缩其输出
mcp	将全部命令作为 MCP 工具经 stdio 提供（可选适配器）

全局参数

• --json — 机器契约：固定信封、稳定 schema 版本、错误输出到 stdout。等价于 --format json。
• --config <path> — 显式配置文件（最高优先级）。
• --no-saved — 不显示 saved N% 统计。
• --output <path> — 把完整负载写入 <path> 而不是 stdout；stderr 输出一条 wrote <path> 确认，stdout 保持为空。

配置解析

配置文件只保存默认行为偏好——绝不保存索引、状态或会话。查找优先级从高到低：

1. --config <path>（显式指定）
2. .ctxctl/config.toml（项目级，像 .git 一样向上逐级查找）
3. $XDG_CONFIG_HOME/ctxctl/config.toml（XDG 全局）
4. 内置默认值

退出码

码	含义
0	成功 / 被包裹命令执行成功
1	文件或命令读取失败
2	不支持的扩展名 / 无效行区间
3	解析失败
4	未找到符号
非零透传	exec 透传子进程的退出码
128 + 信号	Unix 下 exec 的子进程被信号杀死时

字节稳定

输出正文绝不包含时间戳、计数器、随机值、机器相关路径或 PID。相同输入 + 相同配置 → 字节级一致的输出，这正是首次节省之后 provider 提示词缓存持续命中的原因。saved% 由 cl100k_base BPE 分词器确定性地计算——从不依赖外部测量。

完整的行为契约——JSON 信封、折叠规则、流合并、流式压缩——见公开的 CLI 契约规范。