contentstudio
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseInstall ContentStudio CLI if it doesn't exist
若未安装 ContentStudio CLI,请先安装
bash
npm install -g contentstudio-clibash
npm install -g contentstudio-clior
or
pnpm install -g contentstudio-cli
npm release: https://www.npmjs.com/package/contentstudio-cli
contentstudio-agent github: https://github.com/contentstudioio/contentstudio-agent
contentstudio API docs: https://api.contentstudio.io/api-docs
official website: https://contentstudio.io
---
| Property | Value |
|----------|-------|
| **name** | contentstudio |
| **description** | Social-media automation CLI for scheduling posts and managing media/accounts via the ContentStudio public API |
| **allowed-tools** | Bash(contentstudio:*) |
---pnpm install -g contentstudio-cli
npm 发布地址: https://www.npmjs.com/package/contentstudio-cli
contentstudio-agent GitHub 地址: https://github.com/contentstudioio/contentstudio-agent
contentstudio API 文档: https://api.contentstudio.io/api-docs
官方网站: https://contentstudio.io
---
| 属性 | 值 |
|----------|-------|
| **name** | contentstudio |
| **description** | 基于 ContentStudio 公开 API 的社交媒体自动化 CLI,用于调度帖子及管理媒体/账户 |
| **allowed-tools** | Bash(contentstudio:*) |
---⚠️ Authentication Required
⚠️ 需要身份验证
You MUST authenticate before running any contentstudio CLI command. All commands will fail without a valid API key.
Before doing anything else, check auth status:
bash
contentstudio auth:statusIf is , ask the user for their ContentStudio API key. They can generate one from ContentStudio Dashboard → Settings → API Keys. Then:
has_api_keyfalsebash
contentstudio auth:login --api-key cs_...Then verify a workspace is selected:
bash
contentstudio --json workspaces:currentIf is , list workspaces and ask the user to pick one:
active_workspace_idnullbash
contentstudio --json workspaces:list
contentstudio workspaces:use <workspace_id>在运行任何 contentstudio CLI 命令之前,必须完成身份验证。 没有有效的 API 密钥,所有命令都会执行失败。
在进行任何操作之前,先检查身份验证状态:
bash
contentstudio auth:status如果 为 ,请向用户索要其 ContentStudio API 密钥。用户可从 ContentStudio 控制台 → 设置 → API 密钥 生成密钥。然后执行:
has_api_keyfalsebash
contentstudio auth:login --api-key cs_...随后验证是否已选择工作区:
bash
contentstudio --json workspaces:current如果 为 ,列出所有工作区并让用户选择一个:
active_workspace_idnullbash
contentstudio --json workspaces:list
contentstudio workspaces:use <workspace_id>Invocation rules for agents
Agent 调用规则
- Always pass before the subcommand for stable, parseable output.
--json - Envelope shape:
- Success:
{"ok": true, "data": <payload>, "pagination"?: {...}} - Error:
{"ok": false, "error": {"type": "<ErrorType>", "message": "...", "http_status": <int>, "hint": "..."}}
- Success:
- Exit codes are non-zero on error. Check both and
returncode.ok - Parse stdout only — human messages go to stderr.
- Before any mutating action (posts/comments/media), run it with first to verify the payload is correct.
--dry-runnever touches the API.--dry-run
- 始终在子命令前传递 参数,以获得稳定、可解析的输出。
--json - 返回格式:
- 成功:
{"ok": true, "data": <payload>, "pagination"?: {...}} - 错误:
{"ok": false, "error": {"type": "<ErrorType>", "message": "...", "http_status": <int>, "hint": "..."}}
- 成功:
- 错误时退出码非零。需同时检查 和
returncode字段。ok - 仅解析标准输出(stdout) —— 面向人类的提示信息会输出到标准错误(stderr)。
- 在执行任何变更操作(帖子/评论/媒体)之前,先添加 参数运行,以验证请求内容是否正确。
--dry-run不会调用 API。--dry-run
Confirm the target workspace before mutating actions
执行变更操作前确认目标工作区
The CLI silently defaults to the active workspace (whatever was set by ). That default is fine for read-only calls (, , , , etc.) — just use the active workspace.
workspaces:useworkspaces:listaccounts:listposts:listmedia:listBut for any mutating action — , , , , , , , , — you MUST confirm the workspace with the user first, even if a workspace is already active. Don't assume the active workspace is the one they want to mutate.
accounts:connectaccounts:add-blueskyaccounts:add-facebook-groupposts:createposts:deleteposts:approveposts:rejectcomments:addmedia:uploadPattern:
- Run to see what's active.
contentstudio --json workspaces:current - Tell the user: "Your active workspace is (
<name>). Do you want to connect/post/delete in this workspace, or a different one?"<id> - If they say a different one, run , let them pick, then either:
workspaces:list- Run to switch the default, or
workspaces:use <id> - Pass on the single mutating call (preferred when it's a one-off — does not change the active workspace).
--workspace <id>
- Run
- Only then run the mutating command.
This is mandatory even when the user's request seems to imply the active workspace ("connect a Facebook page", "create a draft post") — they may have just switched contexts in their head and forgotten which workspace is active in the CLI.
CLI 会默认使用当前激活的工作区(即通过 设置的工作区)。对于只读调用(、、、 等),使用默认工作区即可。
workspaces:useworkspaces:listaccounts:listposts:listmedia:list但对于任何变更操作 —— 、、、、、、、、 —— 即使已有激活的工作区,也必须先与用户确认目标工作区。不要假设激活的工作区就是用户想要操作的工作区。
accounts:connectaccounts:add-blueskyaccounts:add-facebook-groupposts:createposts:deleteposts:approveposts:rejectcomments:addmedia:upload操作流程:
- 执行 查看当前激活的工作区。
contentstudio --json workspaces:current - 告知用户:"您当前激活的工作区是 (
<name>)。您是否要在此工作区中进行连接/发布/删除操作,还是切换到其他工作区?"<id> - 如果用户选择其他工作区,执行 列出所有工作区,让用户选择,然后执行以下操作之一:
workspaces:list- 执行 切换默认工作区,或
workspaces:use <id> - 在单次变更命令中传递 参数(适用于一次性操作,不会更改激活的工作区)。
--workspace <id>
- 执行
- 之后再执行变更命令。
即使用户的请求看似指向激活的工作区(如"连接一个 Facebook 页面"、"创建一篇草稿帖子"),也必须执行此步骤 —— 用户可能刚切换了操作上下文,却忘记了 CLI 中当前激活的工作区。
Pagination — be proactive, don't silently truncate
分页处理 —— 主动处理,勿静默截断
All list commands return a block in JSON mode when more results exist than fit on one page:
paginationjson
{
"ok": true,
"data": [ /* current page of items */ ],
"pagination": {
"current_page": 1,
"per_page": 10,
"total": 48,
"last_page": 5,
"from": 1,
"to": 10,
"has_more": true
}
}Mandatory rule: Whenever , the user has more data than what was returned. You MUST NOT silently treat the current page as "all results". Pick one of these three strategies:
pagination.has_more === true-
Ask the user (default for ambiguous requests):"I retrieved 10 of your 48 workspaces. Do you want me to fetch the rest, or is the first 10 enough for what you're doing?"
-
Auto-paginate — if the user's request implies they want everything (e.g. "list ALL my accounts", "show every draft post", "delete all queued posts"):
- Call again with to get everything in one round-trip:
--per-page <total>bashcontentstudio --json workspaces:list --per-page 48 - Or iterate ,
--page 2, …--page 3if--page <last_page>is large (>200) and you want bounded pages.total
- Call again with
-
Filter, don't paginate — if the user asked for something specific (e.g. "Facebook accounts only"), use the relevant filter flag (,
--platform facebook,--search "...") instead of paginating. Smaller result set = no pagination needed.--status draft
所有列表类命令在 JSON 模式下,当结果超过单页容量时,会返回 块:
paginationjson
{
"ok": true,
"data": [ /* 当前页的内容 */ ],
"pagination": {
"current_page": 1,
"per_page": 10,
"total": 48,
"last_page": 5,
"from": 1,
"to": 10,
"has_more": true
}
}强制规则: 当 时,用户还有更多数据未返回。绝对不能将当前页视为"全部结果"。请选择以下三种策略之一:
pagination.has_more === true-
询问用户(模糊请求的默认处理方式):"已获取您的 48 个工作区中的 10 个。是否需要获取剩余的工作区,还是这 10 个就满足您的需求?"
-
自动分页 —— 如果用户的请求明确表示需要全部数据(如"列出我所有的账户"、"显示所有草稿帖子"、"删除所有已排队的帖子"):
- 使用 参数再次调用,一次性获取全部数据:
--per-page <total>bashcontentstudio --json workspaces:list --per-page 48 - 如果总数据量较大(>200),可通过迭代 、
--page 2……--page 3参数来分批次获取。--page <last_page>
- 使用
-
过滤而非分页 —— 如果用户的请求有明确指向(如"仅列出 Facebook 账户"),使用相关过滤参数(、
--platform facebook、--search "...")代替分页。结果集越小,越不需要分页。--status draft
Quick decision tree for the agent
Agent 快速决策树
Did the user say "all" / "every" / "complete list" / "every single"?
→ YES: auto-paginate using --per-page <pagination.total>
→ NO:
Did the user give a specific count? ("show me top 5", "first 20 posts")
→ YES: respect that count; use --per-page accordingly
→ NO:
pagination.has_more === true?
→ YES: ASK the user before assuming you have everything
→ NO: you have all the data; proceed用户是否提到了"全部"/"所有"/"完整列表"/"每一个"?
→ 是: 使用 --per-page <pagination.total> 自动分页
→ 否:
用户是否指定了数量?(如"显示前5个"、"前20篇帖子")
→ 是: 遵循指定数量;相应设置 --per-page 参数
→ 否:
pagination.has_more === true?
→ 是: 在假设获取全部数据前询问用户
→ 否: 已获取全部数据;继续操作Examples
示例
User: "list my workspaces"
Agent should:
- Run (high default to often avoid pagination)
contentstudio --json workspaces:list --per-page 50 - If is still true, say: "I see 50 of N workspaces. Want me to fetch all N?"
pagination.has_more
User: "delete all my draft posts"
Agent should:
- Run to peek at
contentstudio --json posts:list --status draft --per-page 1total - Run to get them all
contentstudio --json posts:list --status draft --per-page <total> - Iterate over and delete each
data[] - Never delete just the first page and report "done"
User: "show me my Facebook accounts"
Agent should:
- Use filter — usually returns 0 or a handful, no pagination concern
--platform facebook - If still true (>20 FB accounts), ask before auto-fetching
has_more
用户: "列出我的工作区"
Agent 应:
- 执行 (设置较高的默认值以避免分页)
contentstudio --json workspaces:list --per-page 50 - 如果 仍为 true,告知用户:"我看到您有 N 个工作区,已获取其中 50 个。是否需要获取全部 N 个?"
pagination.has_more
用户: "删除我所有的草稿帖子"
Agent 应:
- 执行 查看总数量
contentstudio --json posts:list --status draft --per-page 1 - 执行 获取所有草稿帖子
contentstudio --json posts:list --status draft --per-page <total> - 遍历 并逐个删除
data[] - 绝对不能只删除第一页就报告"已完成"
用户: "显示我的 Facebook 账户"
Agent 应:
- 使用 过滤参数 —— 通常返回0个或少量结果,无需担心分页问题
--platform facebook - 如果 仍为 true(超过20个 Facebook 账户),在自动获取前询问用户
has_more
Endpoints that paginate
支持分页的端点
All commands paginate:
, , , , , , , , .
*:listworkspaces:listaccounts:listposts:listcomments:listmedia:listcampaigns:listcategories:listlabels:listteam:listNon-list commands (, , , , etc.) never include in their envelope.
auth:whoamiposts:createposts:deletemedia:uploadpagination所有 命令均支持分页:
, , , , , , , , .
*:listworkspaces:listaccounts:listposts:listcomments:listmedia:listcampaigns:listcategories:listlabels:listteam:list非列表类命令(、、、 等)的返回结果中永远不会包含 块。
auth:whoamiposts:createposts:deletemedia:uploadpaginationCommand Reference
命令参考
All commands are invoked as .
contentstudio <group>:<command>所有命令均以 的形式调用。
contentstudio <group>:<command>Authentication
身份验证
| Command | Purpose |
|---|---|
| Store and verify API key |
| Forget stored credentials |
| Hit |
| Show local config (key redacted) |
| 命令 | 用途 |
|---|---|
| 存储并验证 API 密钥 |
| 清除存储的凭证 |
| 调用 |
| 显示本地配置(密钥已脱敏) |
Workspaces
工作区
| Command | Purpose |
|---|---|
| List user's workspaces |
| Set active workspace |
| Show active workspace |
| 命令 | 用途 |
|---|---|
| 列出用户的所有工作区 |
| 设置激活的工作区 |
| 显示当前激活的工作区 |
Social accounts (read + connect)
社交账户(查看 + 连接)
| Command | Purpose |
|---|---|
| List connected social accounts |
| List platforms supported for new account connections |
| Generate a one-time OAuth URL to connect a new account |
| Refresh an expired/invalid account |
| Connect a Bluesky account (no browser — uses app password) |
| Manually add a Facebook Group connection |
--platformaccounts:listfacebooklinkedintwitterinstagramyoutubetiktokpinterestgmb<platform>accounts:connectfacebookfacebook-profileinstagraminstagram-via-facebooktwitterlinkedinpinteresttiktokyoutubethreadsgmbtumblrAccount-connection flow for AI agents:
- Run to see what's supported and which method each uses (
platforms:list/oauth/credentials).manual - For OAuth platforms (most), call and surface the returned URL to the user — they open it in their browser to authorize. The CLI itself never handles credentials.
accounts:connect <platform> - For Bluesky, ask the user for their handle + app-password (link them to https://bsky.app/settings/app-passwords) and call .
accounts:add-bluesky - For Facebook Groups, just call .
accounts:add-facebook-group --name "..."
| 命令 | 用途 |
|---|---|
| 列出已连接的社交账户 |
| 列出支持连接新账户的平台 |
| 生成一次性 OAuth 链接以连接新账户 |
| 刷新过期/无效的账户 |
| 连接 Bluesky 账户(无需浏览器 —— 使用应用密码) |
| 手动添加 Facebook 群组连接 |
accounts:list--platformfacebooklinkedintwitterinstagramyoutubetiktokpinterestgmbaccounts:connect<platform>facebookfacebook-profileinstagraminstagram-via-facebooktwitterlinkedinpinteresttiktokyoutubethreadsgmbtumblrAI Agent 账户连接流程:
- 执行 查看支持的平台及对应的连接方式(
platforms:list/oauth/credentials)。manual - 对于 OAuth 平台(大多数),调用 并将返回的链接提供给用户 —— 用户在浏览器中打开链接完成授权。CLI 本身不会处理凭证。
accounts:connect <platform> - 对于 Bluesky,向用户索要其用户名(handle)和应用密码(可引导用户访问 https://bsky.app/settings/app-passwords 获取),然后调用 。
accounts:add-bluesky - 对于 Facebook 群组,直接调用 。
accounts:add-facebook-group --name "..."
Posts
帖子
| Command | Purpose |
|---|---|
| List posts |
| Create a post (shortcut mode) |
| Create a post with full JSON body |
| Delete a post |
| Approve a pending post |
| Reject a pending post |
-t / --publish-typedraftscheduledqueuedcontent_category| 命令 | 用途 |
|---|---|
| 列出帖子 |
| 创建帖子(快捷模式) |
| 使用完整 JSON 内容创建帖子 |
| 删除帖子 |
| 审批待处理的帖子 |
| 驳回待处理的帖子 |
-t / --publish-typedraftscheduledqueuedcontent_categoryComments / Internal notes
评论 / 内部笔记
| Command | Purpose |
|---|---|
| List comments on a post |
| Add public comment or internal note |
| 命令 | 用途 |
|---|---|
| 列出帖子的评论 |
| 添加公开评论或内部笔记 |
Media library
媒体库
| Command | Purpose |
|---|---|
| List media assets |
| Upload a local file |
| Import from external URL |
| 命令 | 用途 |
|---|---|
| 列出媒体资源 |
| 上传本地文件 |
| 从外部 URL 导入媒体 |
Lookup tables
查找表
| Command | Purpose |
|---|---|
| List campaigns (folders) |
| List content categories |
| List labels |
| List workspace team members |
| 命令 | 用途 |
|---|---|
| 列出营销活动(文件夹) |
| 列出内容分类 |
| 列出标签 |
| 列出工作区团队成员 |
Facebook helpers
Facebook 辅助工具
| Command | Purpose |
|---|---|
| List Facebook colored-background presets (use |
| 命令 | 用途 |
|---|---|
| 列出 Facebook 彩色背景预设(纯文本帖子中可使用 |
Examples
示例
Verify the stored key is valid
验证存储的密钥是否有效
bash
contentstudio --json auth:whoamibash
contentstudio --json auth:whoami→ {"ok": true, "data": {"_id": "...", "email": "...", "full_name": "..."}}
→ {"ok": true, "data": {"_id": "...", "email": "...", "full_name": "..."}}
undefinedundefinedFind a Facebook account to post to
查找用于发布的 Facebook 账户
bash
contentstudio --json accounts:list --platform facebook --per-page 10bash
contentstudio --json accounts:list --platform facebook --per-page 10Pick an _id, e.g. <account_id>
选择一个 _id,例如 <account_id>
undefinedundefinedSafely preview a post before creating it
创建帖子前安全预览
bash
contentstudio --json posts:create --dry-run \
-c "Our new blog is live! https://example.com/post" \
-i <account_id> \
-t scheduled \
-s "2026-05-01 10:00:00" \
-m https://example.com/hero.jpgbash
contentstudio --json posts:create --dry-run \
-c "我们的新博客上线了!https://example.com/post" \
-i <account_id> \
-t scheduled \
-s "2026-05-01 10:00:00" \
-m https://example.com/hero.jpgReturns: {"ok": true, "data": {"dry_run": true, "endpoint": "...", "body": {...}}}
返回: {"ok": true, "data": {"dry_run": true, "endpoint": "...", "body": {...}}}
undefinedundefinedActually create the post (drop --dry-run)
实际创建帖子(移除 --dry-run 参数)
bash
contentstudio --json posts:create \
-c "Our new blog is live!" \
-i <account_id> \
-t draftbash
contentstudio --json posts:create \
-c "我们的新博客上线了!" \
-i <account_id> \
-t draftCreate a post with a complex body (platform options, approval workflow)
使用复杂内容创建帖子(平台选项、审批流程)
Write a JSON body and pass via :
--bodyjsonc
{
"content": {
"text": "Hello world",
"media": {"images": ["https://example.com/img.jpg"]}
},
"accounts": ["<account_id>"],
"scheduling": {
"publish_type": "scheduled",
"scheduled_at": "2026-05-01 10:00:00"
},
"first_comment": {"message": "🔗 link in bio", "accounts": ["<account_id>"]},
"labels": ["<label_id>"],
"campaign_id": "<campaign_id>",
"approval": {
"approvers": ["<user_id>"],
"approve_option": "anyone",
"notes": "please review"
}
}bash
contentstudio --json posts:create --body /tmp/post.json编写 JSON 内容并通过 参数传递:
--bodyjsonc
{
"content": {
"text": "Hello world",
"media": {"images": ["https://example.com/img.jpg"]}
},
"accounts": ["<account_id>"],
"scheduling": {
"publish_type": "scheduled",
"scheduled_at": "2026-05-01 10:00:00"
},
"first_comment": {"message": "🔗 链接在简介中", "accounts": ["<account_id>"]},
"labels": ["<label_id>"],
"campaign_id": "<campaign_id>",
"approval": {
"approvers": ["<user_id>"],
"approve_option": "anyone",
"notes": "请审核"
}
}bash
contentstudio --json posts:create --body /tmp/post.jsonList recent draft posts
列出最近的草稿帖子
bash
contentstudio --json posts:list --status draft --per-page 5bash
contentstudio --json posts:list --status draft --per-page 5Delete a post (and from social)
删除帖子(同时从社交平台删除)
bash
contentstudio --json posts:delete <post_id> --delete-from-socialbash
contentstudio --json posts:delete <post_id> --delete-from-socialAdd an internal note on a post (private)
在帖子上添加内部笔记(私密)
bash
contentstudio --json comments:add <post_id> "Double-check the link" --notebash
contentstudio --json comments:add <post_id> "请检查链接" --noteOverride workspace for a single call
为单次调用覆盖工作区
bash
contentstudio --json --workspace <other_ws_id> posts:list --per-page 3bash
contentstudio --json --workspace <other_ws_id> posts:list --per-page 3Error handling
错误处理
| | Typical hint |
|---|---|---|
| 401, 403 | Run |
| 404 | The resource doesn't exist or isn't in this workspace. |
| 422 | Flattened Laravel-style field errors from the API. |
| 429 | Wait a moment and retry. |
| 5xx or network | Retry after a short backoff. |
| — (local) | Missing API key / workspace; run |
| | 典型提示 |
|---|---|---|
| 401, 403 | 使用有效的密钥执行 |
| 404 | 资源不存在或不在当前工作区中。 |
| 422 | API 返回的 Laravel 风格字段错误信息。 |
| 429 | 稍等片刻后重试。 |
| 5xx 或网络错误 | 短暂等待后重试。 |
| —(本地错误) | 缺少 API 密钥/工作区;执行 |
When NOT to use this skill
何时不应使用此技能
- The user is asking about running their own ContentStudio backend (Laravel source); this CLI only talks to the deployed API.
- Tasks not exposed by the v1 API (e.g., billing changes, first-time social account connection — those happen in the ContentStudio web UI).
- 用户询问的是自行部署 ContentStudio 后端(Laravel 源码)相关问题;此 CLI 仅与已部署的 API 交互。
- v1 API 未暴露的任务(如账单变更、首次社交账户连接 —— 这些操作需在 ContentStudio 网页端完成)。
Version
版本
1.0.0
1.0.0