cli-printing-press-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Printing Press Generator

CLI Printing Press 生成器

Skill by ara.so — Devtools Skills collection.

CLI Printing Press generates production-ready CLIs from any API — REST, GraphQL, or browser-sniffed traffic. Each generated CLI includes SQLite-backed local storage, offline full-text search, compound insight commands, and dual interfaces (Cobra CLI + MCP server). Designed for AI agents first with typed exit codes, auto-JSON output when piped, and token-efficient

--compact

mode.

由 ara.so 开发的Skill — 属于Devtools Skills集合。

CLI Printing Press 可从任意API（REST、GraphQL或浏览器捕获的流量）生成可用于生产环境的CLI。每个生成的CLI都包含基于SQLite的本地存储、离线全文搜索、复合洞察命令以及双接口（Cobra CLI + MCP服务器）。专为AI Agent设计，支持类型化退出码、管道输出时自动返回JSON，以及高效节省Token的

--compact

模式。

What It Does

功能介绍

The Printing Press follows a 6-phase autonomous workflow:

Research: Discovers official docs, competing CLIs, MCP servers, and community patterns
Non-Obvious Insight: Identifies the API's secret identity (what it's actually useful for)
Code Generation: Builds Go CLI with domain-specific SQLite tables, FTS5 indexes, sync engine
Verification: Runs scorecard, dogfood tests, proof-of-behavior checks, live API smoke tests
Polish: Auto-fixes verify failures, removes dead code, cleans descriptions
Publishing: Packages for library, generates PR with quality score

Key differentiators:

Local-first: High-gravity resources get domain tables (not JSON blobs) with incremental sync
Compound commands: Cross-resource queries (
```
stale
```
,
```
health
```
,
```
bottleneck
```
) impossible with stateless wrappers
Dual output: Every API generates both
```
<api>-pp-cli
```
(Cobra) and
```
<api>-pp-mcp
```
(MCP server)
No spec required: Point at a website, captures traffic, reverse-engineers the API
Agent-native: Auto-JSON when piped, typed exit codes,
```
--compact
```
flag,
```
--dry-run
```

CLI Printing Press 遵循6阶段自主工作流：

调研阶段：发现官方文档、竞品CLI、MCP服务器和社区模式
深度洞察：识别API的核心价值（它真正的实用场景）
代码生成：构建带有领域专属SQLite表、FTS5索引和同步引擎的Go语言CLI
验证阶段：运行评分卡、内部测试、行为验证和实时API冒烟测试
优化打磨：自动修复验证失败问题、移除死代码、优化描述内容
发布上线：打包为库、生成带有质量评分的PR

核心差异化特性：

本地优先：重要资源存储为领域专属表（而非JSON blob），支持增量同步
复合命令：支持跨资源查询（如
```
stale
```
、
```
health
```
、
```
bottleneck
```
），这是无状态包装器无法实现的
双输出：每个API都会生成
```
<api>-pp-cli
```
（Cobra）和
```
<api>-pp-mcp
```
（MCP服务器）两种产物
无需规范文件：只需指向一个网站，即可捕获流量并逆向工程API
Agent原生：管道输出时自动返回JSON、类型化退出码、
```
--compact
```
标志、
```
--dry-run
```
模式

Installation

安装步骤

Prerequisites

前置依赖

Go 1.26.3+ (install)
Claude Code or compatible AI agent harness
Git (for cloning skills repo)

Go 1.26.3+（安装地址）
Claude Code 或兼容的AI Agent工具
Git（用于克隆技能仓库）

1. Install Binary

1. 安装二进制文件

bash

go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest

Verify:

bash

printing-press --version

bash

go install github.com/mvanhorn/cli-printing-press/v4/cmd/printing-press@latest

验证安装：

bash

printing-press --version

2. Install Skills (Recommended Method)

2. 安装Skills（推荐方式）

Clone the repo to get skills and automatic updates via

git pull

bash

git clone https://github.com/mvanhorn/cli-printing-press.git
cd cli-printing-press

克隆仓库以获取技能，并通过

git pull

获取自动更新：

bash

git clone https://github.com/mvanhorn/cli-printing-press.git
cd cli-printing-press

3. Start Printing Session

3. 启动生成会话

From the cloned repo root:

bash

undefined

在克隆的仓库根目录执行：

bash

undefined

Load skills directly from this repo

直接从此仓库加载技能

claude --plugin-dir .

Or in a new git worktree (for parallel runs)

或在新的git工作树中启动（支持并行运行）

claude --plugin-dir . -w

undefined

claude --plugin-dir . -w

undefined

Core Commands

核心命令

Primary Generation Command

主生成命令

Inside Claude Code session:

text

/printing-press <api-name>
/printing-press <url>
/printing-press <api-name> codex

Examples:

text

undefined

在Claude Code会话中执行：

text

/printing-press <api-name>
/printing-press <url>
/printing-press <api-name> codex

示例：

text

undefined

Generate from API name (auto-discovers docs/specs)

通过API名称生成（自动发现文档/规范）

/printing-press Notion

Generate from website (browser-sniff traffic)

通过网站生成（捕获浏览器流量）

/printing-press https://postman.com/explore

Use Codex for code generation (60% fewer Opus tokens)

使用Codex生成代码（减少60%的Opus Token消耗）

/printing-press HubSpot codex

Reprint existing CLI under latest machine

基于最新机制重新生成现有CLI

/printing-press-reprint notion

undefined

/printing-press-reprint notion

undefined

Polish Existing CLI

优化现有CLI

Runs diagnostics, fixes verify failures, removes dead code:

text

/printing-press-polish <api-name>

Example:

text

/printing-press-polish linear

运行诊断、修复验证失败问题、移除死代码：

text

/printing-press-polish <api-name>

示例：

text

/printing-press-polish linear

Publish to Library

发布到库

Validates, packages, creates PR:

text

/printing-press-publish <api-name>

Example:

text

/printing-press-publish superhuman

验证、打包并创建PR：

text

/printing-press-publish <api-name>

示例：

text

/printing-press-publish superhuman

Amend from Dogfood Session

基于内部测试会话修正

Turn session friction into PR (auto-detects target CLI):

text

/printing-press-amend
/printing-press-amend <api-name>

将会话中的问题转化为PR（自动检测目标CLI）：

text

/printing-press-amend
/printing-press-amend <api-name>

Binary CLI Usage

二进制CLI使用方式

The

printing-press

binary is called by skills but can be used directly:

bash

undefined

printing-press

二进制文件由Skills调用，也可直接使用：

bash

undefined

Research phase

调研阶段

printing-press research <api-name> --output ./output

Generate full CLI

生成完整CLI

printing-press generate notion --output ~/clis/notion-pp-cli

Verify generated CLI

验证生成的CLI

printing-press verify ~/clis/notion-pp-cli

Score quality

质量评分

printing-press scorecard ~/clis/notion-pp-cli

Dogfood test

内部测试

printing-press dogfood ~/clis/notion-pp-cli

undefined

printing-press dogfood ~/clis/notion-pp-cli

undefined

Configuration

配置说明

Output Locations

输出目录结构

Default structure (auto-managed by skills):

~/printing-press/
├── .runstate/<scope>/runs/<run-id>/working/<api>-pp-cli/  # Active runs
├── library/<api>/                                          # Published CLIs
└── manuscripts/<api>/<run-id>/                            # Archived runs
    ├── research/
    ├── proofs/
    ├── discovery/
    └── pipeline/

<scope>

derives from git checkout path (parallel worktrees don't conflict).

默认结构（由Skills自动管理）：

~/printing-press/
├── .runstate/<scope>/runs/<run-id>/working/<api>-pp-cli/  # 活跃运行任务
├── library/<api>/                                          # 已发布的CLI
└── manuscripts/<api>/<run-id>/                            # 归档运行任务
    ├── research/
    ├── proofs/
    ├── discovery/
    └── pipeline/

<scope>

由git checkout路径派生（并行工作树不会冲突）。

Override Output

自定义输出路径

bash

printing-press generate stripe --output /custom/path/stripe-cli

bash

printing-press generate stripe --output /custom/path/stripe-cli

Environment Variables

环境变量

Generated CLIs use these patterns:

bash

undefined

生成的CLI遵循以下环境变量模式：

bash

undefined

API authentication

API认证

export NOTION_API_KEY="secret_..." export LINEAR_API_KEY="lin_api_..." export GITHUB_TOKEN="ghp_..."

SQLite store location (override default)

SQLite存储位置（覆盖默认路径）

export NOTION_PP_STORE_PATH="/custom/notion.db"

Refresh settings for auto data-source

自动数据源刷新设置

export LINEAR_PP_REFRESH_TTL="5m"

undefined

export LINEAR_PP_REFRESH_TTL="5m"

undefined

Generated CLI Patterns

生成的CLI规范

Every generated CLI follows these conventions:

每个生成的CLI都遵循以下约定：

Authentication Setup

认证设置

bash

undefined

bash

undefined

Interactive auth setup (writes to ~/.config/<api>-pp-cli/config.yaml)

交互式认证设置（写入~/.config/<api>-pp-cli/config.yaml）

notion-pp-cli auth login

Or set directly

或直接设置环境变量

export NOTION_API_KEY="secret_abc123"

undefined

export NOTION_API_KEY="secret_abc123"

undefined

Data Source Modes

数据源模式

bash

undefined

bash

undefined

Auto mode: refresh if TTL expired (default)

自动模式：如果TTL过期则刷新（默认）

linear-pp-cli issues list --data-source auto

Force live API call

强制调用实时API

linear-pp-cli issues list --data-source live

Local-only (offline)

仅本地模式（离线）

linear-pp-cli issues list --data-source local

undefined

linear-pp-cli issues list --data-source local

undefined

Sync and Search

同步与搜索

bash

undefined

bash

undefined

Initial sync

初始同步

notion-pp-cli sync

Incremental sync

增量同步

notion-pp-cli sync --incremental

Full-text search (FTS5)

全文搜索（FTS5）

notion-pp-cli search "authentication flow"

Direct SQL query

直接SQL查询

notion-pp-cli sql "SELECT title FROM pages WHERE updated_at > date('now', '-7 days')"

undefined

notion-pp-cli sql "SELECT title FROM pages WHERE updated_at > date('now', '-7 days')"

undefined

Agent-Native Features

Agent原生特性

bash

undefined

bash

undefined

Auto-JSON when piped

管道输出时自动返回JSON

linear-pp-cli issues list | jq '.[] | select(.priority == "urgent")'

Compact mode (60-80% fewer tokens)

紧凑模式（减少60-80%的Token消耗）

linear-pp-cli issues list --compact

Dry-run (safe exploration)

试运行模式（安全探索）

linear-pp-cli issues create --title "Test" --dry-run

Typed exit codes

类型化退出码

linear-pp-cli issues get ISSUE-123 echo $? # 0=success, 2=not found, 3=auth, 4=validation, 5=server, 7=offline

undefined

linear-pp-cli issues get ISSUE-123 echo $? # 0=成功, 2=未找到, 3=认证失败, 4=验证失败, 5=服务器错误, 7=离线

undefined

Compound Commands

复合命令

Generated CLIs include domain-specific insight commands:

bash

undefined

生成的CLI包含领域专属洞察命令：

bash

undefined

Linear example

Linear示例

linear-pp-cli stale --threshold 7d # Issues blocked >7 days linear-pp-cli health --team backend # Team velocity metrics linear-pp-cli bottleneck # Most-blocking issues

linear-pp-cli stale --threshold 7d # 阻塞超过7天的问题 linear-pp-cli health --team backend # 团队交付速度指标 linear-pp-cli bottleneck # 最影响进度的阻塞问题

Discord example

Discord示例

discord-pp-cli knowledge --channel docs # Thread knowledge graph discord-pp-cli stale-threads --days 30 # Unanswered >30 days

discord-pp-cli knowledge --channel docs # 线程知识图谱 discord-pp-cli stale-threads --days 30 # 超过30天未回复的线程

Stripe example

Stripe示例

stripe-pp-cli churn-signals # Failed charges + cancellations stripe-pp-cli cohort-health --month 2026-04

undefined

stripe-pp-cli churn-signals # 支付失败+用户取消订阅信号 stripe-pp-cli cohort-health --month 2026-04

undefined

Code Examples

代码示例

Using a Generated CLI in Go

在Go中使用生成的CLI

package main

import (
    "context"
    "fmt"
    "os"
    "os/exec"
    "encoding/json"
)

// Call generated Linear CLI
func getBlockedIssues() ([]Issue, error) {
    cmd := exec.Command("linear-pp-cli", "stale", 
        "--threshold", "7d",
        "--output", "json")
    
    output, err := cmd.Output()
    if err != nil {
        return nil, fmt.Errorf("CLI error: %w", err)
    }
    
    var issues []Issue
    if err := json.Unmarshal(output, &issues); err != nil {
        return nil, err
    }
    
    return issues, nil
}

// Use MCP server programmatically
func callMCPServer(ctx context.Context, method string, params map[string]interface{}) error {
    // MCP servers expose stdio interface
    cmd := exec.CommandContext(ctx, "linear-pp-mcp")
    
    stdin, _ := cmd.StdinPipe()
    stdout, _ := cmd.StdoutPipe()
    
    if err := cmd.Start(); err != nil {
        return err
    }
    
    req := map[string]interface{}{
        "jsonrpc": "2.0",
        "method": method,
        "params": params,
        "id": 1,
    }
    
    json.NewEncoder(stdin).Encode(req)
    
    var resp map[string]interface{}
    json.NewDecoder(stdout).Decode(&resp)
    
    return cmd.Wait()
}

package main

import (
    "context"
    "fmt"
    "os"
    "os/exec"
    "encoding/json"
)

// 调用生成的Linear CLI
func getBlockedIssues() ([]Issue, error) {
    cmd := exec.Command("linear-pp-cli", "stale", 
        "--threshold", "7d",
        "--output", "json")
    
    output, err := cmd.Output()
    if err != nil {
        return nil, fmt.Errorf("CLI error: %w", err)
    }
    
    var issues []Issue
    if err := json.Unmarshal(output, &issues); err != nil {
        return nil, err
    }
    
    return issues, nil
}

// 以编程方式调用MCP服务器
func callMCPServer(ctx context.Context, method string, params map[string]interface{}) error {
    // MCP服务器暴露标准IO接口
    cmd := exec.CommandContext(ctx, "linear-pp-mcp")
    
    stdin, _ := cmd.StdinPipe()
    stdout, _ := cmd.StdoutPipe()
    
    if err := cmd.Start(); err != nil {
        return err
    }
    
    req := map[string]interface{}{
        "jsonrpc": "2.0",
        "method": method,
        "params": params,
        "id": 1,
    }
    
    json.NewEncoder(stdin).Encode(req)
    
    var resp map[string]interface{}
    json.NewDecoder(stdout).Decode(&resp)
    
    return cmd.Wait()
}

Integrating Generated CLI into Scripts

将生成的CLI集成到脚本中

bash

#!/bin/bash

bash

#!/bin/bash

Deploy blocker detection script

部署阻塞检测脚本

Sync latest data

同步最新数据

notion-pp-cli sync --incremental

Find stale blockers

查找阻塞超过7天的问题

BLOCKERS=$(notion-pp-cli sql " SELECT b.id, b.title, i.title as blocked_issue FROM issues i JOIN issues b ON i.blocker_id = b.id WHERE b.state = 'in_progress' AND b.updated_at < date('now', '-7 days') " --output json)

Send to Slack if any found

如果找到则发送到Slack

if [ "$(echo "$BLOCKERS" | jq 'length')" -gt 0 ]; then echo "$BLOCKERS" | jq -r '.[] | "⚠️ (.blocked_issue) blocked by stale: (.title)"'
| slack-cli send --channel "#deploy-alerts" fi

undefined

if [ "$(echo "$BLOCKERS" | jq 'length')" -gt 0 ]; then echo "$BLOCKERS" | jq -r '.[] | "⚠️ (.blocked_issue) 被阻塞问题停滞: (.title)"'
| slack-cli send --channel "#deploy-alerts" fi

undefined

Creating Custom Commands

创建自定义命令

Generated CLIs support plugin architecture:

// Add to cmd/custom/reconcile.go in generated CLI
package custom

import (
    "github.com/spf13/cobra"
    "github.com/mvanhorn/linear-pp-cli/internal/store"
)

func NewReconcileCmd(st *store.Store) *cobra.Command {
    cmd := &cobra.Command{
        Use:   "reconcile",
        Short: "Find issues in API but missing from local store",
        RunE: func(cmd *cobra.Command, args []string) error {
            // Query local store
            localIDs := st.GetAllIssueIDs()
            
            // Query live API
            liveIDs := fetchLiveIssueIDs()
            
            // Diff
            missing := difference(liveIDs, localIDs)
            
            for _, id := range missing {
                fmt.Printf("Missing: %s\n", id)
            }
            
            return nil
        },
    }
    return cmd
}

生成的CLI支持插件架构：

// 添加到生成的CLI中的cmd/custom/reconcile.go
package custom

import (
    "github.com/spf13/cobra"
    "github.com/mvanhorn/linear-pp-cli/internal/store"
)

func NewReconcileCmd(st *store.Store) *cobra.Command {
    cmd := &cobra.Command{
        Use:   "reconcile",
        Short: "查找API中存在但本地存储缺失的问题",
        RunE: func(cmd *cobra.Command, args []string) error {
            // 查询本地存储
            localIDs := st.GetAllIssueIDs()
            
            // 查询实时API
            liveIDs := fetchLiveIssueIDs()
            
            // 对比差异
            missing := difference(liveIDs, localIDs)
            
            for _, id := range missing {
                fmt.Printf("缺失: %s\n", id)
            }
            
            return nil
        },
    }
    return cmd
}

Troubleshooting

故障排查

Generation Failures

生成失败

Problem: Research phase hangs or fails

bash

undefined

问题： 调研阶段停滞或失败

bash

undefined

Check if API has publicly accessible docs

检查API是否有公开可访问的文档

curl -I https://developers.notion.com

Try explicit spec URL

尝试使用明确的规范URL

/printing-press https://raw.githubusercontent.com/notion/openapi/main/spec.yaml

Use browser-sniff mode for private APIs

对私有API使用浏览器捕获模式

/printing-press https://internal-tool.company.com


**Problem:** Codex mode fails repeatedly

The press auto-falls back to local generation after 3 Codex failures. Check logs:

```bash
tail -f ~/.printing-press/.runstate/<scope>/runs/<run-id>/logs/generation.log

/printing-press https://internal-tool.company.com


**问题：** Codex模式反复失败

CLI生成器在3次Codex失败后会自动回退到本地生成。查看日志：

```bash
tail -f ~/.printing-press/.runstate/<scope>/runs/<run-id>/logs/generation.log

Verification Errors

验证错误

Problem: Scorecard shows low score

bash

undefined

问题： 评分卡显示低分

bash

undefined

Run polish to auto-fix

运行优化命令自动修复

/printing-press-polish <api-name>

Check specific failure

检查具体失败原因

printing-press verify ~/printing-press/library/<api> --verbose


**Problem:** Auth tests fail

```bash

printing-press verify ~/printing-press/library/<api> --verbose


**问题：** 认证测试失败

```bash

Verify credentials work manually

手动验证凭证是否有效

export API_KEY="your_key" curl -H "Authorization: Bearer $API_KEY" https://api.service.com/test

Check generated auth.go

检查生成的auth.go文件

cat ~/printing-press/library/<api>-pp-cli/internal/auth/auth.go

undefined

cat ~/printing-press/library/<api>-pp-cli/internal/auth/auth.go

undefined

Runtime Issues with Generated CLIs

生成的CLI运行时问题

Problem: Sync fails with rate limit

bash

undefined

问题： 同步因速率限制失败

bash

undefined

Use incremental sync with backoff

使用带退避策略的增量同步

api-pp-cli sync --incremental --rate-limit 10/min

Check cursor tracking

检查游标跟踪情况

api-pp-cli sql "SELECT resource, cursor, updated_at FROM sync_cursors"


**Problem:** Search returns no results

```bash

api-pp-cli sql "SELECT resource, cursor, updated_at FROM sync_cursors"


**问题：** 搜索无结果返回

```bash

Rebuild FTS5 index

重建FTS5索引

api-pp-cli sql "DELETE FROM pages_fts" api-pp-cli sync --rebuild-index

Verify FTS table

验证FTS表

api-pp-cli sql "SELECT * FROM sqlite_master WHERE type='table' AND name LIKE '%_fts'"


**Problem:** Compound command errors

```bash

api-pp-cli sql "SELECT * FROM sqlite_master WHERE type='table' AND name LIKE '%_fts'"


**问题：** 复合命令报错

```bash

Check if required tables exist

检查所需表是否存在

api-pp-cli sql ".schema" | grep -A 5 "CREATE TABLE"

Run with debug output

启用调试输出运行

api-pp-cli stale --threshold 7d --log-level debug

undefined

api-pp-cli stale --threshold 7d --log-level debug

undefined

MCP Server Issues

MCP服务器问题

Problem: MCP server not responding

bash

undefined

问题： MCP服务器无响应

bash

undefined

Test stdio interface directly

直接测试标准IO接口

echo '{"jsonrpc":"2.0","method":"ping","id":1}' | linear-pp-mcp

Check MCP manifest

检查MCP清单

cat ~/printing-press/library/linear-pp-mcp/mcp.json


**Problem:** IDE can't find MCP server

Add to Claude Code config (`~/.config/claude-code/mcp-servers.json`):

```json
{
  "linear": {
    "command": "/path/to/linear-pp-mcp",
    "env": {
      "LINEAR_API_KEY": "${LINEAR_API_KEY}"
    }
  }
}

cat ~/printing-press/library/linear-pp-mcp/mcp.json


**问题：** IDE无法找到MCP服务器

添加到Claude Code配置文件（`~/.config/claude-code/mcp-servers.json`）：

```json
{
  "linear": {
    "command": "/path/to/linear-pp-mcp",
    "env": {
      "LINEAR_API_KEY": "${LINEAR_API_KEY}"
    }
  }
}

Performance Optimization

性能优化

Problem: Large dataset sync is slow

bash

undefined

问题： 大数据集同步缓慢

bash

undefined

Enable batch mode

启用批量模式

api-pp-cli sync --batch-size 1000 --workers 4

Use partial sync

使用部分同步

api-pp-cli sync --resources "issues,comments" --since "2026-01-01"


**Problem:** Search queries are slow

```bash

api-pp-cli sync --resources "issues,comments" --since "2026-01-01"


**问题：** 搜索查询缓慢

```bash

Analyze query plan

分析查询计划

api-pp-cli sql "EXPLAIN QUERY PLAN SELECT * FROM pages_fts WHERE pages_fts MATCH 'search term'"

Add covering index

添加覆盖索引

api-pp-cli sql "CREATE INDEX idx_pages_updated ON pages(updated_at DESC)"

undefined

api-pp-cli sql "CREATE INDEX idx_pages_updated ON pages(updated_at DESC)"

undefined

Best Practices

最佳实践

Always run polish after generation: Auto-fixes 80% of verify failures
Use
--compact
for agent calls: 60-80% fewer tokens, same data
Sync incrementally in production: Full sync only on init
Set refresh TTL based on data volatility: Real-time (1m), hourly (5m), daily (1h)
Use typed exit codes for error handling: Don't parse stderr
Leverage compound commands: They're the CLI's superpower
Credit sources in custom commands: Check generated README's "Sources and Inspiration"

生成后始终运行优化命令：自动修复80%的验证失败问题
Agent调用时使用
--compact
模式：减少60-80%的Token消耗，数据内容一致
生产环境使用增量同步：仅在初始化时执行全量同步
根据数据波动设置刷新TTL：实时数据(1m)、小时级数据(5m)、日级数据(1h)
使用类型化退出码处理错误：不要解析stderr输出
充分利用复合命令：这是该CLI的核心优势
自定义命令中注明来源：查看生成的README中的"Sources and Inspiration"