@inplain/cli

Plain CLI

AI-native Office,在终端里。Agent 优先,人是副产品。

plain 是 Plain 项目的命令行入口,主要用于:

1. 被 AI agent 调用(通过 MCP 协议 / 直接 CLI)— 让 Claude Code、Cursor、Codex 等把 Plain 当成"做文档/汇报/表格"的工具
2. 自动化 / CI— 在脚本里生成、编辑、导出 deck/doc/sheet
3. 人手敲(副产品)— 快速从一句话生成一份汇报,跳过 web UI

安装(repo 内开发)

pnpm install
pnpm plain --help

Install

npm i -g @inplain/cli
plain login
plain deck generate "an 8-slide pitch deck on Q3 growth"

也可一次性运行:npx @inplain/cli login。包含 MCP server:plain mcp。

命令树

plain deck   generate | edit                  PPT
plain doc    generate | edit                  Word
plain sheet  generate | edit                  Excel
plain export <file> --to=pptx|docx|xlsx       导出
plain mcp                                     起 stdio MCP server
plain login                                   浏览器授权 CLI(local callback)
plain login --api-key <pat>                   或直接传 PAT(CI / 自动化)
plain config                                  查看当前配置
plain logout                                  清除 api key

加 --json 切机器模式(stdout 只输 JSON,stderr 仍走进度)。

鉴权

CLI 和 Web 端走同一套 — 都过 Plain gateway,都认 user.id,都扣同一个积分池。

plain login          # 浏览器打开 /account/cli-auth → 一键授权 → key 自动写回 ~/.config/plain
plain deck generate --intent "Q1 销售战略,8 页" -o q1.deck.md

plain login 流程:

1. CLI 起一个临时 localhost server(34567 起的第一个空闲端口)
2. 自动打开浏览器到 https://www.inplain.app/account/cli-auth?callback=http://127.0.0.1:<port>/cb&state=<random>
3. 你点 "Authorize CLI",浏览器把新生成的 key redirect 回 localhost
4. CLI 拿到 key,核对 state,写入 ~/.config/plain/config.json(权限 0600)

之后所有 plain deck/doc/sheet/export 命令,LLM 调用走 gateway 透明计费, 跟你在网页工作台用同一个 user 同一个积分池。在 /account 可以随时撤销 key。

Dev 账号(Plain 团队)

Plain 团队成员的 user.id 写进 server 端 PLAIN_DEV_USER_IDS 白名单(Vercel env) 后,该账号走 gateway 时会:

• 跳过 plan_status past_due / canceled 检查
• 不扣积分,不向 OpenMeter push(免费通道)
• 仍然写 usage_events 表(便于 dogfood 看自己用量)

这意味着 CLI 永远只有一条路径:plain login → gateway。 不再有 BYOK 后门,不再 fallback 到 ANTHROPIC_API_KEY 等。 Plain 开发者也跑 plain login,只是 server 识别后免费放行。

用例

1) 一句话生成一份 deck,导出 PPTX

plain login                                       # 一次就够
plain deck generate --intent "Q1 销售战略,8 页" -o q1.deck.md
plain export q1.deck.md --to pptx -o q1.pptx

2) 用 JSON Patch 精准改 deck(不调 LLM,本地确定性)

plain deck edit q1.deck.md \
  --patch '[{"op":"replace","path":"/slides/0/title","value":"Q1 战略评审"}]'

3) AI agent 通过自然语言改 deck

plain deck edit q1.deck.md \
  --instruction "把第三页改成 stats layout,4 个核心指标横排"

4) Pipe 模式(stdin → stdout,适合 Unix-style 链)

# 生成 → 立刻编辑 → 立刻导出,不落盘
plain deck generate --intent "三句话产品介绍" \
  | plain deck edit /dev/stdin --instruction "加个封面页" -o /dev/stdout \
  | plain export /dev/stdin --to pptx -o intro.pptx

5) 启动 MCP server,被 Claude Code 等调用

plain mcp                  # listen on stdio

在 Claude Code 配置(~/.claude/settings.json):

{
  "mcpServers": {
    "plain": {
      "command": "tsx",
      "args": ["/path/to/plain/cli/src/index.ts", "mcp"],
      "env": { "PLAIN_API_KEY": "plain_pk_..." }
    }
  }
}

之后 Claude Code 会看到 9 个 plain 工具:generate_deck / edit_deck / generate_doc / ... / export_sheet_xlsx。

配置

配置文件:$XDG_CONFIG_HOME/plain/config.json(默认 ~/.config/plain/config.json),权限 0o600。

字段:

{
  "apiKey": "plain_pk_xxx",
  "gatewayUrl": "https://gateway.plain.ai/v1",
  "defaultAgentId": "your-agent-name"
}

env 永远 override 配置文件:PLAIN_API_KEY / PLAIN_GATEWAY_URL / PLAIN_AGENT_ID。

defaultAgentId 给按 agent 计费埋点用。Phase 3 接 Stripe 后,gateway 按 agent 维度统计用量,这是 Plain 区别于"按 user 席位"定价的核心。

烟雾测试

pnpm cli:smoke   # 6 路径,不调 LLM

覆盖:--help / config / deck edit --patch / export → pptx / mcp tools/list / mcp export_deck_pptx。

设计决策

详见 memory/reference_plain_oss_benchmarks.md(开源对标研究)。关键判断:

1. CLI 是生产接口,MCP 是浏览器插件 — MCP 比 CLI 贵 10–32x token,所以 MCP 工具是 CLI 子命令的薄包装
2. 粗粒度 MCP 工具 — 不暴露 apply_json_patch 给 agent,只给 generate_deck / edit_deck(防 prompt injection,LLM 调用更可靠)
3. --json 切机器模式,默认人类输出 — 跟 gh CLI 一致
4. gateway 走 OpenAI 兼容协议 — gateway URL 嵌 agent-id (/v1/agent/<id>),复用现有 model.ts 的 custom provider,CLI 端不需要新抽象层