circle-cli

Circle CLI **每个 Circle 管理 API 操作，以及缓存，使得成员审计、批量操作和分析免费，无需 API 配额。** circle-cli 镜像了完整的 Circle Admin V2 接口，并添加了 Circle系统所缺乏的功能： SQLite 缓存，支持全文搜索、配额感知预检、批量成员操作试运行，以及 CLI 原生分析和导出。因为 Circle 会将失败和重复读取计入您的每月配额，因此从本地缓存中回答问题可以节省资金，而不仅仅是加快速度。 ## 安装 ### Go（推荐） 需要 Go 1.26.4+： ``` install github.com/thaleslaray/circle-cli/cmd/circle-cli@latest ``` ### 从源码编译 ```bash git clone https://github.com/thaleslaray/circle-cli cd circle-cli go build -o circle-cli ./cmd/circle-cli ``` ### 作为 Claude Code 技能 此仓库包含一个 `SKILL.md` 文件导 Claude 如何使用 `circle-cli`。要激活： ```bash mkdir -p ~/.claude/skills/circle-cli curl -fsSL https://raw.githubusercontent.com/thaleslaray/circle-cli/main/SKILL.md \ -o ~/.claude/skills/circle-cli/SKILL.md ``` 然后，用自然语言请求（例如，“列出我的 Circle 成员”），Claude 将运行 CLI。 ### 作为 MCP 服务器（Claude Desktop / 代理） 安装包含的 MCP 服务器： ```bash go install github.com/thaleslaray/circle-cli/cmd/circle-cli-mcp@latest ``` 将以下内容添加到 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json`）： ```json { "mcpServers": { "circle": { "command": "circle-cli-mcp", "env": { "CIRCLE_API_TOKEN": "<your-key>" } } } } ``` ## 身份验证 在社区设置 > 开发者 >令牌下创建 Admin API V2 令牌，然后设置 CIRCLE_API_TOKEN。该令牌作为 `Authorization: Bearer <token>` 发送。需要 Circle Business 或以上计划。 ## 快速入门 ```bash # 健康检查：在您花费令牌之前确认 API 基地址已解析 circle-cli quota --dry-run # 验证您的令牌是否有效并查看您的社区 circle-cli community list --json # 将您的社区一次性拉取到本地缓存中 circle-cli sync --resources community-members,spaces,posts,comments # 在零配额成本下，对缓存的成员和帖子进行离线全文搜索 circle-cli search "founder" --json # 模糊解析空间名称为其 ID，用于后续写入 circle-cli resolve "vip lounge" --type space --json ``` ## 独特功能 这些功能在其他 API 工具中不可用。 ### 节省配额的本地智能 - **`resolve`** — 将模糊名称、电子邮件或 slug 转换为您需要的确切类型 ID，瞬间完成，无需任何 API 调用。 _在任何需要 ID 的写入操作之前使用此命令 — 它永远不会消耗配额，也不会返回 429 错误。_ ```bash circle-cli resolve "vip lounge" --type space --json ``` - **`quota`** — 在运行批量操作之前，验证您的令牌，检查您的速率限制，并估算操作的成本。 _在任何批量操作之前使用此命令，以避免盲目消耗付费配额或遇到无声的 403 错误。_ ```bash circle-cli quota --plan --add-to-space VIP" --json ``` ### 成员审计 - **`audit members`** — 查找缺少必填个人资料字段或未分配到任何空间的成员，以便立即可见 onboarding 缺口。 _在同步后运行，以显示 API 无法查询的不完整或孤立成员。_ ```bash circle-cli audit members --missing bio --not-in-any-space --json ``` - **`audit duplicates`** — 显示重复成员（相同电子邮件或名称）和孤立的成员资格，指向已删除的空间。 _或账单核对前的社区卫生检查。_ ```bash circle-cli audit duplicates --by email --json ``` - **`inactive`** — 查找 N 天内未发帖或评论的成员，用于重新参与或修剪。 _用于在不分页整个社区的情况下生成重新参与或清理列表。_ ```bash circle-cli inactive --days 90 --select id,email,last_activity --json ``` ### 批量操作 - **`bulk`** — 在提交之前，预览哪些成员会更改空间、标签或角色，然后仅应用实际的差异。 _用于任何大规模成员资格变更 — 试运行差异使付费写入安全且最小化。_ ```bash circle-cli bulk --filter "tag:trial" --add-to-space "VIP Lounge" --dry-run ``` ### 分析和导出 - **`digest`** — 自某个时间窗口以来，社区中发生了什么：新成员、新帖子、热门话题。 _用作社区的日常站会，无需进行 N 次现场通话。_ ```bash circle-cli digest --since 24h --json ``` - **`analytics engagement`** — 按空间和成员划分的参与度、发帖频率和真正的排行榜，基于您自己的数据。 _用于内容/社区健康报告，Circle 仪表盘无法通过 CLI 提供。_ ```bash circle-cli analytics engagement --by space --top 20 --json ``` - **`export-all`** — 将成员、空间、帖子和评论导出为 CSV 或 JSON，用于备份、BI 或合规，操作命令。 _用于定期备份或填充仓库，无需消耗实时配额。_ ```bash -cli export-all -- --out ./backup ``` ### 课程创作 - **`lesson add`** — 将课程添加到章节中，名称、内联正文或来自 Markdown 文件，在发布前预览。 _用于从编辑器或仓库发布课程，无需点击 Circle UI。_ ```bash circle-cli lesson add --course "On --section "Week 1" --title "Intro" --file intro.md --dry-run ``` ## 配方 ### 每日社区站会 ```bash circle-cli digest --since 24h --json ``` 自昨日以来，新增成员、帖子和热门话题，均从本地缓存计算 查找和重新参与流失成员 ```bash circle-cli inactive --days 60 --select id,email_activity --json ``` 在窗口期内无帖子或评论的成员，准备好导入标签 步骤。 ### 安全的批量空间移动 ```bash circle-cli bulk --filter "tag:trial" --add-to-space "VIP Lounge" --dry-run ``` 在进行任何付费写入之前，显示确切的成员资格差异。 ### 为代理缩小大型成员列表 ```bash circle-cli community-members list --agent --select records.id,records.email,records``` 仅返回 Circle成员有效载荷中代理所需的字段，使用点状 --select 路径。 ### 迁移前完整备份 ```bash circle-cli export-all --format csv --out ./backup ``` 在零额外 API 调用下，将成员、空间、帖子和评论转储到本地。 ## 用法 运行 `circle-cli --help` 以获取完整的命令参考和标志列表。 ## 路径和环境变量 此 CLI 将本地文件分为四种路径类型： 类型 | 内容 | ----------| | ` | 用户可编辑的 `config.toml` 和已保存的配置文件 `data` | 持久本地数据：`credentials.toml`、`data.dbcookie、浏览器会话和其他身份验证辅助文件 `state` |状态，例如已持久化的查询、作业和 `` | | ` | 可再生 HTTP/缓存文件 | 每种类型都独立解析。梯： 1. 按类型划分的环境变量：`CIRCLE_CONFIG_DIR`、`CIRCLE_DATA_DIR`、`CIRCLE_STATE_DIR` 或 `CIRCLE_CACHE_DIR` 2. `--home <dir>` 用于此调用 3. `C_HOME` 用于平面重定位根目录 4. XDG 环境变量：`XDG_CONFIG_HOME`、`XDG_DATA_HOME`、`XDG_STATE_HOME`、`XDG_CACHE_HOME` 5. 平台默认匹配现有安装 对于容器和代理沙盒，请首选单个重定位根目录： ```bash export CIRCLE_HOME=/ircle circle-cli``` 在 `CIRCLE_HOME=/srv/circle` 下，解析为 `/srv/circle/config`、`/srv/circle/data`、`/srv/circle/state` 和 `/srv/circle/cache`。 MCP 服务器不会从主机接收 CLI 标志。将重定位放在主机 `env` 块中： ```json { "mcpServers": { "circle": { "command": "circle-cli-mcp", "env": { "CIRCLE_HOME": "/srv/circle" } } } } ``` 在fleet中，优先级很重要：像 `CIRCLE_DATA_DIR`这样的环境变量优先于显式的 `--home` 用于该类型。使用 `CIRCLE_HOME` 或按类型的变量进行持久化fleet重定位；将 `--home` 视为较弱的按调用重定位杠杆。 重定位是单向的。取消设置 `CIRCLE_HOME` 不会将文件移回平台默认值，`doctor` 无法找到在以前根目录下遗留的凭证。手动移动文件，然后取消设置重定位现有安装继续工作，因为平台默认分支匹配旧布局。在第一次身份验证写入时，存储的机密将离开 `config.toml`，并被合并到 `credentials.toml` 下的数据目录中。运行 `circle-cli doctor --fail-on warn` 以检查自动化中的路径和凭证位置警告。 ## 命令 ### 访问组 管理访问组 - **`circle-cli access-groups create`** - 创建访问组 - **`circle-cli access-groups delete`** - 存档访问组 - **`circle-cli access-groups list`** - 列出访问组 - **`circle-cli access-groups update`** - 更新访问组 ### 高级搜索 管理高级搜索 - **`circle-cli advanced-search`** - 高级搜索 ### 聊天偏好 管理聊天偏好 - **`circle-cli chat-preferences`** - 更新聊天偏好 ### 评论 管理评论 - **`circle-cli comments create`** - 创建评论 - **`circle-cli comments delete`** - 删除评论 - **`circle-cli comments get`** - 显示评论 - **`circle-cli`** - 列出评论 ### 社区 管理社区 - **`circle-cli community list`** - 获取社区详情 - **`circle-cli community update`** - 更新社区 ### 社区成员空间 管理社区成员空间 - **`circle-cli community-member-spaces`** - 列出社区 ### 社区成员 管理社区成员 - **`circle-cli community-members create`** - 使用给定电子邮件创建社区成员。头像需要先使用 direct_upload 流程（上传到预签名 URL，然后使用 signed_id 和 url）。 - **`circle-cli community-members delete`** - 停用社区成员 - **` community-members get`** - 显示社区成员 - **`circle-cli community-members list`** - 列出社区成员 - **`circle-cli community-members list-communitymembers`**搜索社区成员 - **`circle-cli community-members update`** - 更新社区成员 ### 社区分段 管理社区分段 - **`circle-cli community-segments create`** - 创建社区分段 - **`circle-cli community-segments delete`** - 删除社区分段 - **`circle-cli community-segments list`** -社区分段 - **`circle-cli community-segments update`** - 更新现有的社区分段 ### 课程学习进度 管理课程学习进度 - **`circle-cli course-lesson-progress`** - 更新课程学习### 课程 - **`circle-cli course-lessons create`** - 在课程章节中创建课程。在 rich_text_body 中使用 rich_text_body 代替 body_html。 - **`circle-cli course-lessons delete`** - 删除课程 - **`circle-cli course-lessons get`** - 显示课程 - **`circle-cli course-lessons list`** - 列出课程 - **`circle-cli course-lessons update`** - 更新课程。在 rich 中使用 rich 代替 body_html 课程章节 管理课程章节 - **`circle-cli course-sections create`** - 创建课程章节 - **`circle-cli course-sections delete`** - 删除课程章节 - **`circle-cli course-sections get`** - 显示课程章节 - **`circle-cli course-sections list`** - 列出课程章节 - **`circle-cli course-sections update`** - 更新课程章节 ### 直接上传 管理直接上传 - **` direct-uploads`** -上传创建预签名 URL。使用提供的标 PUT 上传文件到返回的 direct_upload.url。 ### 嵌入 管理嵌入 - **`circle-cli embeds create`** - 从 URL 创建嵌入并返回具有 sgid 的嵌入数据 - **`circle-cli embeds get`** - 通过 sgid 检索嵌入 ### 活动出席者 管理活动出席者 - **`circle-cli event-attendees create 创建活动出席者 - **`circle-cli event-attendees delete`** - 删除活动出席者 - **`circle-cli event-attendees list`** - 列出活动出席者 ### 活动 管理活动 - **`circle-cli events create`** - 在事件类型空间中创建活动。必须提供 space_id（在顶级和事件对象中）。 - **`circle-cli events delete`** - 删除活动 - **`circle-cli events get`**活动 --cli events list`** - 列出活动 - **`circle-cli events update 更新活动 ### 标记内容 管理标记内容 - **`circle-cli flagged-contents create`** - 举报标记内容 - **`circle-cli flagged-contents - 列出标记### 表单 - **` forms delete`** - - **`circle-cli forms get`** - 返回表单详情 - **`circle-cli forms list`** - 列出表单 - **`circle-cli forms update`** - 更新表单 ### 游戏化 管理游戏化 - **`circle-cli gamification`** - 显示排行榜 ### 邀请链接 管理邀请链接 - **`circle-cli invitation-links delete 通过设置其状态为已删除来删除邀请链接 - **`circle-cli invitation-links list`** - 列出邀请链接 ### 直播 管理直播 - **`circle-cli live get`** - 返回给定直播房间的原始 VTT 转录稿。转录稿来自录制 blob转录，通过多态。 - **` live list`** - 返回社区的分页直播房间列表。 ### 成员标签 管理成员标签 - **`circle-cli member-tags create`** - 创建新成员标签 - **`circle-cli member-tags delete`** - 删除成员标签 - **`circle-cli member-tags get`** - 显示成员标签的详细信息 - **`circle-cli member-tags list`** - 成员标签列表 **`circle-cli member-tags update`** - 更新成员标签 ### 消息 管理消息 - **`circle-cli messages`** - 创建### 页面配置文件字段页面配置文件字段 - **`circle-cli page-profile-fields`** - 获取页面配置文件字段 ### 帖子 管理帖子 - **`circle-cli posts create`** - 在基本类型空间中创建基本帖子。在 tiptap_body 中使用 tiptap_body 代替 body_html。 - **`circle-cli posts delete`** - 删除基本帖子 - **`circle-cli posts get`** - 显示基本帖子 - **`circle-cli posts list`** - 列出基本帖子 - **`circle-cli posts update`** - 更新基本帖子 ### 配置文件字段 管理配置文件- **`circle-cli profile-fields`** - 配置文件字段列表 ###组成员 管理成员 - **` space-group-member`** - 显示空间组成员 ### 空间组成员 管理空间组成员 - **`circle-cli space-group-members create`** - 创建空间组成员 - **`circle-cli space-group-members delete`** - 删除空间组成员 - **`circle-cli space-group-members list`** - 列出空间组成员 ### 空间组 管理空间组 - **`circle-cli space-groups create`** - 创建空间组 - **`circle-cli space-groups delete`** - 删除 - **`circle-cli space-groups get`** - 显示空间组 - **`circle-cli space-groups list`** - 列出空间组 - **`circle-cli space-groups update`** - 更新空间组 ### 空间成员 管理空间成员 - **`circle-cli space-member`** - 显示空间成员 ### 空间成员 管理空间成员 - **` space-members create`** - 添加空间成员 - **`circle-cli space-members delete`** - 删除空间成员 - **`circle-cli space-members list`** - 列出空间成员 ### 空间 管理空间 - **`circle-cli spaces create`** - 创建空间。space_type 默认值为“basic”。使用 course_setting 进行课程类型空间。访问级别通过 is_private 和 is_hidden_from_non_members 控制。 - **`circle-cli spaces delete`** - 删除空间 - **`circle-cli spaces get`** - 显示空间 - **`circle-cli spaces list`** - 列出空间 - **`circle-cli spaces update`** - 更新空间 ### 标记成员 管理标记成员 circle-cli tagged-members create`** - 创建标记成员 - **`circle-cli tagged-members delete`** - 删除标记成员 - **`circle-cli tagged-members get`** - 获取标记成员 - **`circle-cli tagged-members list`** - 列出标记成员 ### 主题 管理主题 - **`circle-cli topics create`** - 创建主题 - **`circle-cli topics delete`** - 删除主题 - **`circle-cli topics get`** - 显示主题详情 - **`circle-cli topics list`** - 列出主题 - **`circle-cli topics update`** - 更新主题 ## 输出格式 ```bash # 人类可读表格（终端默认，JSON 输出时使用） circle-cli access-groups list # 用于脚本和代理的 JSON circle-cli access-groups list --json # 筛选到特定字段 circle-cli access-groups list --json --select id,name,status # 试运行 - 显示请求而非发送 circle-cli list --dry-run # 代理模式 - JSON + 紧凑 + 单 ## 代理使用 本 CLI 设计用于 AI 代理使用： - **非交互式** - 永远不会提示，每次输入都是标志 - **可管道化** - `--json` 输出到 stdout，错误到 stderr - **可筛选** - `--select id,name` 只返回需要的字段 - **可预览** - `--dry-run` 显示请求而不发送 - **显式重试** - 添加 `--idempotent` 以创建重试，并添加 `--ignore-missing` 以删除重试，当接受无操作成功时 - **可确认** - `--yes` 用于显式确认破坏性操作 - **管道输入** - 写入命令可以在其帮助列表中接受结构化输入 `--stdin` - **适用于离线** - 同步/搜索命令可以在本地 SQLite 存储可用时使用 - **默认代理安全** - 除非设置 `--human-friendly`，否则无颜色或格式 退出代码：`0` 成功，`2` 使用错误，`3` 未找到，`4` 身份验证错误，`5` API 错误，`7` 速率限制，`10` 配置错误。 ## 运行时端点 本 CLI 在运行时解析端点占位符，因此一个安装的二进制文件可以针对不同的租户或 API 版本，而无需重新生成。 端点环境变量： - `CIRCLE_DEFAULT_HOST` 解析 `{defaultHost}` 基准 URL：`https://{defaultHost}/api/admin/v2` ## 健康检查 ```bash circle-cli doctor ``` 验证配置、凭证和与 API 的连接。 ## 配置 运行 `circle-cli doctor` 以查看已解析的配置、数据、状态和缓存目录。平台默认配置路径为 `~/.config/admin-pp-cli/config.toml`；`--home`、`CIRCLE_HOME` 和按类型环境变量可以重新定位它。 静态请求头可以在 `headers` 下配置；按命令头覆盖优先。 环境变量： | 名称 | 类型 | 必需 | 描述 | | --- | --- | --- | --- | | `CIRCLE_DEFAULTHOST` | 端点 | 是 | | | `CIRCLE_API_TOKEN` | per_call | 是 | 设置为您的 API 凭证。 | ### agentcookie （可选） 如果您使用 agentcookie 在机器之间同步机密，此 CLI 自动采用 agentcookie 管理的凭证，无需额外设置。当守护进程写入此 CLI 的配置时，`circle-cli doctor` 报告 `agentcookie: detected` 和 `auth-status` 标签源为 `agentcookie`。如果您不使用 agentcookie，请跳过此部分 - CLI 的工作方式与其他 CLI 相同。 ## 故障排除 **身份验证错误（退出代码 4）** - 运行 `circle-cli doctor` 检查凭证 - 验证环境变量是否设置：`echo $CIRCLE_API_TOKEN` **未找到错误（退出代码 3）** - 检查资源 ID 是否正确 - 运行 `list` 命令查看可用项目 ### API 特定 - **每次调用 401 或 403** — 确认 CIRCLE_API_TOKEN 是 Admin API V2 代币（不是 Headless 或 V1），并且创建的管理员仍然具有管理员权限；运行 `circle-cli quota`。 - **429 请求过多** — Circle 允许 2000 个请求/5 分钟/ IP；CLI 自动回退 — 优先使用 `sync` 然后查询本地缓存，而不是重复实时读取。 - **每月配额快速减少** — 失败的请求也计入；运行 `circle-cli quota` 进行预检，并使用离线 `search`/`resolve`/`audit` 命令，成本为零配额。 - **找不到空间 ID** — 运行 `circle-cli resolve "<space name>" --type space` 从本地缓存中解析它。 ## 来源和灵感 本 CLI 通过研究以下项目和资源构建： - [**circle-so-api-php-sdk**](https://github.com/adrosoftware/circle-so-api-php-sdk) — PHP（4 星） - [**CirclePy**](https://github.com/atomimus/CirclePy) — Python（1 星） - [**circleso-go**](https://github.com/miguelbemartin/circleso-go) — Go（1 星） - [**circle-mcp**](https://github.com/DeepakChander/circle-mcp) — JavaScript - [**circle-so**](https://github.com/boiyelove/circle-so) — Python - [**circle-so-python-sdk**](https://github.com/boiyelove/circle-so-python-sdk) — Python 由 [CLI Printing Press](https://github.com/mvanhorn/cli-printing-press) 生成