paragraph-cli

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Paragraph CLI

CLI for Paragraph — a web3 publishing and newsletter platform. Use it to manage posts, publications, subscribers, and coins.

For direct HTTP or SDK access without installing anything, see the paragraph-api skill instead.

适用于Paragraph的CLI——一个Web3发布和新闻通讯平台。可用于管理帖子、出版物、订阅者和代币。

如果无需安装即可直接通过HTTP或SDK访问，请改用paragraph-api技能。

MCP Server (recommended for MCP-compatible clients)

MCP服务器（推荐给兼容MCP的客户端）

If your client supports MCP, use the Paragraph MCP server instead of the CLI for a more integrated experience.

如果你的客户端支持MCP，请使用Paragraph MCP服务器而非CLI，以获得更集成的体验。

Remote server (recommended)

远程服务器（推荐）

Use the hosted server at

mcp.paragraph.com

— no installation or API key management required. Authenticates via your Paragraph account in the browser.

bash

claude mcp add paragraph --transport http https://mcp.paragraph.com/mcp

For other clients, add

https://mcp.paragraph.com/mcp

as a server URL in your MCP configuration.

使用托管在

mcp.paragraph.com

的服务器——无需安装或管理API密钥。通过浏览器中的Paragraph账户进行身份验证。

bash

claude mcp add paragraph --transport http https://mcp.paragraph.com/mcp

对于其他客户端，在MCP配置中添加

https://mcp.paragraph.com/mcp

作为服务器URL。

Local server

本地服务器

If you prefer to run the server locally (requires Node.js 18+):

bash

claude mcp add paragraph -- npx @paragraph-com/mcp

Local mode requires an API key via

PARAGRAPH_API_KEY

env var or

paragraph login

from the CLI.

The MCP server exposes 18 tools (posts, publications, subscribers, coins, search, feed, users) and shares authentication with the CLI. See full docs.

如果你偏好本地运行服务器（需要Node.js 18+）：

bash

claude mcp add paragraph -- npx @paragraph-com/mcp

本地模式需要通过

PARAGRAPH_API_KEY

环境变量或CLI的

paragraph login

命令提供API密钥。

MCP服务器提供18种工具（帖子、出版物、订阅者、代币、搜索、订阅源、用户），并与CLI共享身份验证。查看完整文档。

CLI Setup

CLI设置

Install globally:

bash

npm install -g @paragraph-com/cli

Authenticate — login persists the key to

~/.paragraph/config.json

bash

paragraph login --token <api-key>
echo "$PARAGRAPH_API_KEY" | paragraph login --with-token

Or skip login and pass the key per-command via env var:

bash

PARAGRAPH_API_KEY=<api-key> paragraph post list --json

Verify:

paragraph whoami --json

全局安装：

bash

npm install -g @paragraph-com/cli

身份验证——登录后密钥将保存到

~/.paragraph/config.json

：

bash

paragraph login --token <api-key>
echo "$PARAGRAPH_API_KEY" | paragraph login --with-token

或者跳过登录，通过环境变量为每个命令传递密钥：

bash

PARAGRAPH_API_KEY=<api-key> paragraph post list --json

验证：

paragraph whoami --json

Working agreement

使用约定

Always use
--json
for parseable output. Data goes to stdout, status/errors to stderr.
Always use
--yes
on
```
delete
```
to skip confirmation prompts.
Use
--dry-run
before
```
delete
```
,
```
publish
```
, and
```
archive
```
to preview what will happen.
Use flags, not just positional args. Every identifier accepts
```
--id
```
so you can chain commands.
Pipe content via stdin when creating or updating posts from files:
```
cat draft.md | paragraph post create --title "My Post"
```

Paginate with
--limit
and
--cursor
. The JSON response includes

pagination.cursor

and

pagination.hasMore

Do not use interactive login. Use
```
--token
```
or
```
--with-token
```
for non-interactive auth.
Check auth before running commands. Run
```
paragraph whoami --json
```
to verify credentials are valid.
Do not publish without explicit user approval. Publishing sends content live and optionally emails subscribers.
Default to draft.
```
post create
```
creates drafts. Only call
```
post publish
```
when the user asks.
Respect rate limits. If you get
```
RATE_LIMITED
```
, wait and retry. Avoid tight loops between paginated requests.

**始终使用
```
--json
```
**以获得可解析的输出。数据输出到stdout，状态/错误输出到stderr。
**删除操作始终使用
```
--yes
```
**以跳过确认提示。
**在执行
```
delete
```
、
```
publish
```
和
```
archive
```
前使用
```
--dry-run
```
**预览操作结果。
使用标志而非仅位置参数。每个标识符都支持
```
--id
```
，以便你可以链式执行命令。
通过stdin管道传输内容从文件创建或更新帖子：
```
cat draft.md | paragraph post create --title "My Post"
```

使用
--limit
和
--cursor
进行分页。JSON响应包含

pagination.cursor

和

pagination.hasMore

。

不要使用交互式登录。使用
```
--token
```
或
```
--with-token
```
进行非交互式身份验证。
执行命令前检查身份验证。运行
```
paragraph whoami --json
```
验证凭据是否有效。
未经用户明确批准不要发布。发布操作会将内容上线，并可能向订阅者发送邮件。
默认创建草稿。
```
post create
```
创建草稿。仅在用户要求时调用
```
post publish
```
。
遵守速率限制。如果收到
```
RATE_LIMITED
```
，请等待并重试。避免在分页请求之间使用紧密循环。

Commands

命令

Posts

帖子

bash

undefined

bash

undefined

Create a draft

创建草稿

paragraph post create --title "My Post" --file ./post.md --tags "web3,defi" --json paragraph post create --title "My Post" --text "# Hello World" --subtitle "A subtitle" --json cat content.md | paragraph post create --title "My Post" --json

List

列出

paragraph post list --json paragraph post list --status draft --limit 20 --json paragraph post list --status scheduled --json paragraph post list --publication <slug-or-id> --json

Get (by ID, URL, or @pub/slug)

获取（通过ID、URL或@pub/slug）

paragraph post get --id <post-id> --json paragraph post get @my-blog/post-slug --json

Extract a single field

提取单个字段

paragraph post get --id <post-id> --field markdown > post.md paragraph post get --id <post-id> --field title

Update

更新

paragraph post update --id <id-or-slug> --title "New Title" --json paragraph post update --id <id-or-slug> --text "Updated content" --subtitle "New subtitle" --json paragraph post update --id <id-or-slug> --file ./updated.md --tags "new,tags" --json

Publish

发布

paragraph post publish --id <id-or-slug> --json paragraph post publish --id <id-or-slug> --newsletter --json

Revert to draft

恢复为草稿

paragraph post draft --id <id-or-slug> --json

归档

paragraph post archive --id <id-or-slug> --json

Schedule a post for future publication

安排帖子未来发布

paragraph post schedule --id <id-or-slug> --at "2026-05-01T09:00:00Z" --json paragraph post schedule --id <id-or-slug> --at "2026-05-01T09:00:00Z" --newsletter --json

Cancel a scheduled publication

取消已安排的发布

paragraph post unschedule --id <id-or-slug> --json

Create and schedule in one step

一步创建并安排发布

paragraph post create --title "Launch Day" --file ./post.md --schedule-at "2026-05-01T09:00:00Z" --newsletter --json

Preview destructive actions

预览破坏性操作

paragraph post delete --id <id-or-slug> --dry-run --json paragraph post publish --id <id-or-slug> --dry-run --json

Delete

删除

paragraph post delete --id <id-or-slug> --yes --json

Send test newsletter email

发送测试新闻通讯邮件

paragraph post test-email --id <post-id> --json

Browse

浏览

paragraph post feed --limit 10 --json paragraph post by-tag --tag web3 --limit 20 --json

undefined

paragraph post feed --limit 10 --json paragraph post by-tag --tag web3 --limit 20 --json

undefined

Publications

出版物

bash

paragraph publication get --id <slug-or-id-or-domain> --json

bash

paragraph publication get --id <slug-or-id-or-domain> --json

Search

搜索

bash

paragraph search post --query "ethereum" --json
paragraph search blog --query "web3" --json

bash

paragraph search post --query "ethereum" --json
paragraph search blog --query "web3" --json

Subscribers

订阅者

bash

paragraph subscriber list --limit 100 --json
paragraph subscriber count --publication <id> --json
paragraph subscriber add --email user@example.com --json
paragraph subscriber add --wallet 0x1234...abcd --json
paragraph subscriber import --csv ./subscribers.csv --json

bash

paragraph subscriber list --limit 100 --json
paragraph subscriber count --publication <id> --json
paragraph subscriber add --email user@example.com --json
paragraph subscriber add --wallet 0x1234...abcd --json
paragraph subscriber import --csv ./subscribers.csv --json

Coins

代币

bash

paragraph coin get --id <id-or-address> --json
paragraph coin popular --limit 10 --json
paragraph coin search --query "ethereum" --json
paragraph coin holders --id <id-or-address> --limit 50 --json
paragraph coin quote --id <id-or-address> --amount <wei> --json

bash

paragraph coin get --id <id-or-address> --json
paragraph coin popular --limit 10 --json
paragraph coin search --query "ethereum" --json
paragraph coin holders --id <id-or-address> --limit 50 --json
paragraph coin quote --id <id-or-address> --amount <wei> --json

Users

用户

bash

paragraph user get --id <user-id-or-wallet> --json

bash

paragraph user get --id <user-id-or-wallet> --json

Auth

身份验证

bash

paragraph login --token <api-key>
echo "<api-key>" | paragraph login --with-token
paragraph whoami --json
paragraph logout

bash

paragraph login --token <api-key>
echo "<api-key>" | paragraph login --with-token
paragraph whoami --json
paragraph logout

JSON response shapes

JSON响应格式

Paginated list (note: the CLI wraps items under

data

; the REST API and SDK use

items

instead):

json

{
  "data": [{ "id": "...", "title": "..." }],
  "pagination": { "cursor": "abc123", "hasMore": true }
}

Single item:

json

{ "id": "...", "title": "...", "markdown": "..." }

Mutation:

json

{ "id": "...", "status": "published" }

Error (on stderr):

json

{ "error": "Not found.", "code": "NOT_FOUND", "status": 404 }

Error codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, RATE_LIMITED, SERVER_ERROR, REQUEST_FAILED, CLIENT_ERROR, UNKNOWN.

分页列表（注意：CLI将项目包裹在

data

下；REST API和SDK使用

items

）：

json

{
  "data": [{ "id": "...", "title": "..." }],
  "pagination": { "cursor": "abc123", "hasMore": true }
}

单个项目：

json

{ "id": "...", "title": "...", "markdown": "..." }

变更操作：

json

{ "id": "...", "status": "published" }

错误（输出到stderr）：

json

{ "error": "Not found.", "code": "NOT_FOUND", "status": 404 }

错误代码：UNAUTHORIZED、FORBIDDEN、NOT_FOUND、RATE_LIMITED、SERVER_ERROR、REQUEST_FAILED、CLIENT_ERROR、UNKNOWN。

Common patterns

常见模式

Create and publish in one flow

一步创建并发布

bash

ID=$(paragraph post create --title "My Post" --file ./post.md --json | jq -r '.id')
paragraph post publish --id "$ID" --newsletter --json

bash

ID=$(paragraph post create --title "My Post" --file ./post.md --json | jq -r '.id')
paragraph post publish --id "$ID" --newsletter --json

Export all posts as markdown

将所有帖子导出为markdown

bash

paragraph post list --limit 100 --json | jq -r '.data[].id' | while read id; do
  SLUG=$(paragraph post get --id "$id" --json | jq -r '.slug')
  paragraph post get --id "$id" --field markdown > "${SLUG}.md"
done

bash

paragraph post list --limit 100 --json | jq -r '.data[].id' | while read id; do
  SLUG=$(paragraph post get --id "$id" --json | jq -r '.slug')
  paragraph post get --id "$id" --field markdown > "${SLUG}.md"
done

Paginate through all subscribers

分页遍历所有订阅者

bash

CURSOR=""
while true; do
  RESULT=$(paragraph subscriber list --limit 100 ${CURSOR:+--cursor "$CURSOR"} --json)
  echo "$RESULT" | jq '.data[]'
  CURSOR=$(echo "$RESULT" | jq -r '.pagination.cursor // empty')
  HAS_MORE=$(echo "$RESULT" | jq '.pagination.hasMore')
  [ "$HAS_MORE" = "true" ] || break
done

bash

CURSOR=""
while true; do
  RESULT=$(paragraph subscriber list --limit 100 ${CURSOR:+--cursor "$CURSOR"} --json)
  echo "$RESULT" | jq '.data[]'
  CURSOR=$(echo "$RESULT" | jq -r '.pagination.cursor // empty')
  HAS_MORE=$(echo "$RESULT" | jq '.pagination.hasMore')
  [ "$HAS_MORE" = "true" ] || break
done

Environment variables

环境变量

Variable	Purpose
PARAGRAPH_API_KEY	API key (skip login)
PARAGRAPH_API_URL	Custom API base URL
PARAGRAPH_NON_INTERACTIVE	Set to 1 to force CLI mode
CI	Set to true to force CLI mode

变量	用途
PARAGRAPH_API_KEY	API密钥（跳过登录）
PARAGRAPH_API_URL	自定义API基础URL
PARAGRAPH_NON_INTERACTIVE	设置为1以强制CLI模式
CI	设置为true以强制CLI模式

Troubleshooting

故障排除

Authentication errors

身份验证错误

If commands fail with

UNAUTHORIZED

bash

undefined

如果命令返回

UNAUTHORIZED

失败：

bash

undefined

Check if logged in

检查是否已登录

paragraph whoami --json

Re-authenticate

重新验证

paragraph login --token <api-key>


The CLI auto-clears stored credentials on 401. Re-login if credentials were revoked.

paragraph login --token <api-key>


CLI会在收到401时自动清除存储的凭据。如果凭据被撤销，请重新登录。

Rate limiting

速率限制

If you get

RATE_LIMITED

, wait and retry. The error includes a

status code. Avoid tight loops — add a delay between paginated requests.

如果收到

RATE_LIMITED

，请等待并重试。错误包含

状态码。避免紧密循环——在分页请求之间添加延迟。

Command hangs

命令挂起

If a command appears to hang, it may be waiting for stdin. Ensure you're passing content via

--text

--file

, or piping to stdin. The CLI times out after 30 seconds if stdin is piped but no data arrives.

如果命令看似挂起，可能是在等待stdin输入。确保你通过

--text

、

--file

或管道将内容传递到stdin。如果stdin被管道连接但未收到数据，CLI会在30秒后超时。

CLI not found after install

安装后找不到CLI

bash

npm install -g @paragraph-com/cli

bash

npm install -g @paragraph-com/cli

Verify

验证

npx paragraph --version

undefined

npx paragraph --version

undefined

paragraph-cli

Original

Translation

Paragraph CLI

Paragraph CLI

MCP Server (recommended for MCP-compatible clients)

MCP服务器（推荐给兼容MCP的客户端）

Remote server (recommended)

远程服务器（推荐）

Local server

本地服务器

CLI Setup

CLI设置

Working agreement

使用约定

Commands

命令

Posts

帖子

Create a draft

创建草稿

List

列出

Get (by ID, URL, or @pub/slug)

获取（通过ID、URL或@pub/slug）

Extract a single field

提取单个字段

Update

更新

Publish

发布

Revert to draft

恢复为草稿

Archive

归档

Schedule a post for future publication

安排帖子未来发布

Cancel a scheduled publication

取消已安排的发布

Create and schedule in one step

一步创建并安排发布

Preview destructive actions

预览破坏性操作

Delete

删除

Send test newsletter email

发送测试新闻通讯邮件

Browse

浏览

Publications

出版物

Search

搜索

Subscribers

订阅者

Coins

代币

Users

用户

Auth

身份验证

JSON response shapes

JSON响应格式

Common patterns

常见模式

Create and publish in one flow

一步创建并发布

Export all posts as markdown

将所有帖子导出为markdown

Paginate through all subscribers

分页遍历所有订阅者

Environment variables

环境变量

Troubleshooting

故障排除

Authentication errors

身份验证错误

Check if logged in

检查是否已登录

Re-authenticate