circle-cli

# Circle CLI **Every Circle Admin API operation, plus a local cache that makes member audits, bulk ops, and analytics free of API quota.** circle-cli mirrors the full Circle Admin V2 surface and adds what the thin Circle ecosystem never had: a local SQLite cache with offline full-text search, quota-aware preflight, dry-run bulk member ops, and CLI-native analytics and export. Because Circle bills failed and repeated reads against your monthly quota, answering questions from the local cache is a money-saver, not just a speed-up. ## Install ### Go (recomendado) Requer Go 1.26.4+: ```bash go install github.com/thaleslaray/circle-cli/cmd/circle-cli@latest ``` ### A partir do código ```bash git clone https://github.com/thaleslaray/circle-cli cd circle-cli go build -o circle-cli ./cmd/circle-cli ``` ### Como skill do Claude Code Este repo traz um `SKILL.md` que ensina o Claude a usar o `circle-cli`. Para ativar: ```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 ``` Depois, peça em linguagem natural (ex.: "liste meus membros do circle") e o Claude roda o CLI. ### Como servidor MCP (Claude Desktop / agentes) Instale o servidor MCP incluso: ```bash go install github.com/thaleslaray/circle-cli/cmd/circle-cli-mcp@latest ``` Adicione ao config do Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "circle": { "command": "circle-cli-mcp", "env": { "CIRCLE_API_TOKEN": "<your-key>" } } } } ``` ## Authentication Create an Admin API V2 token in your community under Settings > Developers > Tokens, then set CIRCLE_API_TOKEN. The token is sent as `Authorization: Bearer <token>`. Requires a Circle Business plan or above. ## Quick Start ```bash # health check: confirms the API base resolves before you spend a token circle-cli quota --dry-run # verify your token works and see your community circle-cli community list --json # pull your community into the local cache once circle-cli sync --resources community-members,spaces,posts,comments # offline full-text search across cached members and posts at zero quota cost circle-cli search "founder" --json # fuzzy-resolve a space name to its ID for later writes circle-cli resolve "vip lounge" --type space --json ``` ## Unique Features These capabilities aren't available in any other tool for this API. ### Quota-saving local intelligence - **`resolve`** — Turn a fuzzy name, email, or slug into the exact typed ID you need for any write, instantly and with zero API calls. _Reach for this before any write that needs an ID — it never burns quota and never 429s._ ```bash circle-cli resolve "vip lounge" --type space --json ``` - **`quota`** — Validate your token, check your rate limit, and estimate what a bulk op will cost before you run it. _Use before any bulk operation to avoid blind-burning paid quota or hitting a silent 403._ ```bash circle-cli quota --plan "bulk --add-to-space VIP" --json ``` ### Member audits - **`audit members`** — Find members missing required profile fields or not assigned to any space, so onboarding gaps are visible at a glance. _Run after sync to surface incomplete or stranded members the API can't query for._ ```bash circle-cli audit members --missing bio --not-in-any-space --json ``` - **`audit duplicates`** — Surface duplicate members (same email or name) and orphaned memberships pointing at deleted spaces. _Use for community hygiene before a migration or billing reconciliation._ ```bash circle-cli audit duplicates --by email --json ``` - **`inactive`** — Find members who haven't posted or commented in N days, for re-engagement or pruning. _Use to build re-engagement or cleanup lists without paging the whole community live._ ```bash circle-cli inactive --days 90 --select id,email,last_activity --json ``` ### Bulk operator ops - **`bulk`** — Preview exactly which members change space, tag, or role before committing, then apply only the real deltas. _Use for any mass membership change — the dry-run diff makes paid writes safe and minimal._ ```bash circle-cli bulk --filter "tag:trial" --add-to-space "VIP Lounge" --dry-run ``` ### Analytics & export - **`digest`** — One screen of what changed in your community since a time window: new members, new posts, top threads. _Use as a daily standup for your community without N live calls._ ```bash circle-cli digest --since 24h --json ``` - **`analytics engagement`** — Per-space and per-member engagement, posting cadence, and a true leaderboard built from your own data. _Use for content/community health reporting the Circle dashboard doesn't expose via CLI._ ```bash circle-cli analytics engagement --by space --top 20 --json ``` - **`export-all`** — Dump members, spaces, posts, and comments to CSV or JSON for backup, BI, or compliance in one command. _Use for periodic backups or feeding a warehouse without burning live quota._ ```bash circle-cli export-all --format csv --out ./backup ``` ### Course authoring - **`lesson add`** — Add a course lesson to a section by name, with the body inline or from a markdown file, previewed before it posts. _Use to publish lessons from your editor or repo without clicking through the Circle UI._ ```bash circle-cli lesson add --course "Onboarding" --section "Week 1" --title "Intro" --file intro.md --dry-run ``` ## Recipes ### Daily community standup ```bash circle-cli digest --since 24h --json ``` New members, posts, and top threads since yesterday, computed from the local cache. ### Find and re-engage lapsed members ```bash circle-cli inactive --days 60 --select id,email,last_activity --json ``` Lists members with no post or comment in the window, ready to pipe into a tag or DM step. ### Safe bulk space move ```bash circle-cli bulk --filter "tag:trial" --add-to-space "VIP Lounge" --dry-run ``` Shows the exact membership diff before any paid write is made. ### Narrow a large member list for an agent ```bash circle-cli community-members list --agent --select records.id,records.email,records.name ``` Returns only the fields an agent needs from Circle's verbose member payload using dotted --select paths. ### Full backup before a migration ```bash circle-cli export-all --format csv --out ./backup ``` Dumps members, spaces, posts, and comments locally with zero additional API calls. ## Usage Run `circle-cli --help` for the full command reference and flag list. ## Paths & environment variables This CLI separates local files into four path kinds: | Kind | Contents | |------|----------| | `config` | User-editable settings such as `config.toml` and saved profiles | | `data` | Durable local data: `credentials.toml`, `data.db`, cookies, browser-session proof files, and other auth sidecars | | `state` | Runtime state such as persisted queries, jobs, and `teach.log` | | `cache` | Regenerable HTTP/cache files | Each kind resolves independently. The ladder is: 1. Per-kind env var: `CIRCLE_CONFIG_DIR`, `CIRCLE_DATA_DIR`, `CIRCLE_STATE_DIR`, or `CIRCLE_CACHE_DIR` 2. `--home <dir>` for this invocation 3. `CIRCLE_HOME` for a flat relocated root 4. XDG env vars: `XDG_CONFIG_HOME`, `XDG_DATA_HOME`, `XDG_STATE_HOME`, `XDG_CACHE_HOME` 5. Platform defaults matching existing installs For containers and agent sandboxes, prefer a single relocated root: ```bash export CIRCLE_HOME=/srv/circle circle-cli doctor ``` Under `CIRCLE_HOME=/srv/circle`, the four dirs resolve to `/srv/circle/config`, `/srv/circle/data`, `/srv/circle/state`, and `/srv/circle/cache`. MCP servers do not receive CLI flags from the host. Put relocation in the host `env` block: ```json { "mcpServers": { "circle": { "command": "circle-cli-mcp", "env": { "CIRCLE_HOME": "/srv/circle" } } } } ``` Precedence matters in fleets: an ambient per-kind variable such as `CIRCLE_DATA_DIR` overrides an explicit `--home` for that kind. Use `CIRCLE_HOME` or the per-kind variables for durable fleet relocation; treat `--home` as the weaker per-invocation lever. Relocation is one-way. Unsetting `CIRCLE_HOME` does not move files back to platform defaults, and `doctor` cannot find credentials left under a former root. Move the files manually before unsetting relocation variables. Existing installs keep working because the platform-default rung matches the legacy layout. On the first auth write, stored secrets leave `config.toml` and are consolidated into `credentials.toml` under the data directory. Run `circle-cli doctor --fail-on warn` to check path and credential-location warnings in automation. ## Commands ### access-groups Manage access groups - **`circle-cli access-groups create`** - Create Access Group - **`circle-cli access-groups delete`** - Archive Access Group - **`circle-cli access-groups list`** - List Access Groups - **`circle-cli access-groups update`** - Update Access Group ### advanced-search Manage advanced search - **`circle-cli advanced-search`** - Advanced Search ### chat-preferences Manage chat preferences - **`circle-cli chat-preferences`** - Update Chat Preferences ### comments Manage comments - **`circle-cli comments create`** - Create Comment - **`circle-cli comments delete`** - Destroy Comment - **`circle-cli comments get`** - Show Comment - **`circle-cli comments list`** - List Comments ### community Manage community - **`circle-cli community list`** - Get community details - **`circle-cli community update`** - Update Community ### community-member-spaces Manage community member spaces - **`circle-cli community-member-spaces`** - List Community Member Spaces ### community-members Manage community members - **`circle-cli community-members create`** - Creates a community member with the given email. Avatar requires using the direct_upload flow first (upload to presigned URL, then use signed_id and url). - **`circle-cli community-members delete`** - Deactivate a community member - **`circle-cli community-members get`** - Show a community member - **`circle-cli community-members list`** - List Community Members - **`circle-cli community-members list-communitymembers`** - Search a community member - **`circle-cli community-members update`** - Update a community member ### community-segments Manage community segments - **`circle-cli community-segments create`** - Creates a community segment - **`circle-cli community-segments delete`** - Delete a community segment - **`circle-cli community-segments list`** - List Community Segments - **`circle-cli community-segments update`** - Updates an existing community segment ### course-lesson-progress Manage course lesson progress - **`circle-cli course-lesson-progress`** - Update Course Lesson Progress ### course-lessons Manage course lessons - **`circle-cli course-lessons create`** - Creates a lesson in a course section. section_id is required. Use rich_text_body instead of body_html for rich text content. - **`circle-cli course-lessons delete`** - Delete a course lesson - **`circle-cli course-lessons get`** - Show a course lesson - **`circle-cli course-lessons list`** - List course lessons - **`circle-cli course-lessons update`** - Updates a course lesson. Use rich_text_body instead of body_html for rich text content. ### course-sections Manage course sections - **`circle-cli course-sections create`** - Create a course section - **`circle-cli course-sections delete`** - Delete a course section - **`circle-cli course-sections get`** - Show a course section - **`circle-cli course-sections list`** - List Course Sections - **`circle-cli course-sections update`** - Update a course section ### direct-uploads Manage direct uploads - **`circle-cli direct-uploads`** - Creates a presigned URL for file upload. Upload the file via PUT to the returned direct_upload.url with the provided headers. The checksum is a base64-encoded MD5 hash of the file content. ### embeds Manage embeds - **`circle-cli embeds create`** - Creates an embed from a URL and returns the embed data with an sgid - **`circle-cli embeds get`** - Retrieves an embed by its sgid ### event-attendees Manage event attendees - **`circle-cli event-attendees create`** - Create Event Attendee - **`circle-cli event-attendees delete`** - Delete Event Attendee - **`circle-cli event-attendees list`** - List Event Attendees ### events Manage events - **`circle-cli events create`** - Creates an event in an event-type space. space_id must be provided both at the top level and inside the event object. - **`circle-cli events delete`** - Delete Event - **`circle-cli events get`** - Get Event - **`circle-cli events list`** - List Events - **`circle-cli events update`** - Update Event ### flagged-contents Manage flagged contents - **`circle-cli flagged-contents create`** - Report Flagged Content - **`circle-cli flagged-contents list`** - List Flagged Contents ### forms Manage forms - **`circle-cli forms delete`** - Deletes a form - **`circle-cli forms get`** - Returns form details - **`circle-cli forms list`** - List Forms - **`circle-cli forms update`** - Updates a form with the provided parameters ### gamification Manage gamification - **`circle-cli gamification`** - Show Leaderboard ### invitation-links Manage invitation links - **`circle-cli invitation-links delete`** - Delete an invitation link by setting its status to deleted - **`circle-cli invitation-links list`** - List Invitation Links ### live Manage live - **`circle-cli live get`** - Returns the raw VTT transcripts for a given live room. Transcripts are sourced from the recording blob's media transcript via a polymorphic association. - **`circle-cli live list`** - Returns a paginated list of live rooms for the community. ### member-tags Manage member tags - **`circle-cli member-tags create`** - Creates a new member tag - **`circle-cli member-tags delete`** - Deletes a member tag - **`circle-cli member-tags get`** - Shows a member tag's details - **`circle-cli member-tags list`** - Member Tags List - **`circle-cli member-tags update`** - Updates a member tag ### messages Manage messages - **`circle-cli messages`** - Create Message ### page-profile-fields Manage page profile fields - **`circle-cli page-profile-fields`** - Get Page Profile Fields ### posts Manage posts - **`circle-cli posts create`** - Creates a basic post in a basic-type space. Use tiptap_body instead of body_html for rich text content. - **`circle-cli posts delete`** - Delete Basic Post - **`circle-cli posts get`** - Show Basic Post - **`circle-cli posts list`** - List Basic Posts - **`circle-cli posts update`** - Update Basic Post ### profile-fields Manage profile fields - **`circle-cli profile-fields`** - Profile Fields List ### space-group-member Manage space group member - **`circle-cli space-group-member`** - Show Space Group Member ### space-group-members Manage space group members - **`circle-cli space-group-members create`** - Create Space Group Member - **`circle-cli space-group-members delete`** - Destroy Space Group Member - **`circle-cli space-group-members list`** - List Space Group Members ### space-groups Manage space groups - **`circle-cli space-groups create`** - Create Space Group - **`circle-cli space-groups delete`** - Delete Space Group - **`circle-cli space-groups get`** - Show Space Group - **`circle-cli space-groups list`** - List Space Groups - **`circle-cli space-groups update`** - Update Space Group ### space-member Manage space member - **`circle-cli space-member`** - Show Space Member ### space-members Manage space members - **`circle-cli space-members create`** - Add Space Member - **`circle-cli space-members delete`** - Remove Space Member - **`circle-cli space-members list`** - List Space Members ### spaces Manage spaces - **`circle-cli spaces create`** - Creates a space. space_type defaults to "basic" if not provided. Use course_setting for course-type spaces. Access levels are controlled via is_private and is_hidden_from_non_members. - **`circle-cli spaces delete`** - Delete a space - **`circle-cli spaces get`** - Show a space - **`circle-cli spaces list`** - List Spaces - **`circle-cli spaces update`** - Update Space ### tagged-members Manage tagged members - **`circle-cli tagged-members create`** - Create Tagged Member - **`circle-cli tagged-members delete`** - Delete Tagged Member - **`circle-cli tagged-members get`** - Get Tagged Member - **`circle-cli tagged-members list`** - List Tagged Members ### topics Manage topics - **`circle-cli topics create`** - Creates a topic - **`circle-cli topics delete`** - Deletes a topic - **`circle-cli topics get`** - Show topic details - **`circle-cli topics list`** - Lists topics - **`circle-cli topics update`** - Updates a topic ## Output Formats ```bash # Human-readable table (default in terminal, JSON when piped) circle-cli access-groups list # JSON for scripting and agents circle-cli access-groups list --json # Filter to specific fields circle-cli access-groups list --json --select id,name,status # Dry run — show the request without sending circle-cli access-groups list --dry-run # Agent mode — JSON + compact + no prompts in one flag circle-cli access-groups list --agent ``` ## Agent Usage This CLI is designed for AI agent consumption: - **Non-interactive** - never prompts, every input is a flag - **Pipeable** - `--json` output to stdout, errors to stderr - **Filterable** - `--select id,name` returns only fields you need - **Previewable** - `--dry-run` shows the request without sending - **Explicit retries** - add `--idempotent` to create retries and `--ignore-missing` to delete retries when a no-op success is acceptable - **Confirmable** - `--yes` for explicit confirmation of destructive actions - **Piped input** - write commands can accept structured input when their help lists `--stdin` - **Offline-friendly** - sync/search commands can use the local SQLite store when available - **Agent-safe by default** - no colors or formatting unless `--human-friendly` is set Exit codes: `0` success, `2` usage error, `3` not found, `4` auth error, `5` API error, `7` rate limited, `10` config error. ## Runtime Endpoint This CLI resolves endpoint placeholders at runtime, so one installed binary can target different tenants or API versions without regeneration. Endpoint environment variables: - `CIRCLE_DEFAULT_HOST` resolves `{defaultHost}` Base URL: `https://{defaultHost}/api/admin/v2` ## Health Check ```bash circle-cli doctor ``` Verifies configuration, credentials, and connectivity to the API. ## Configuration Run `circle-cli doctor` to see the resolved config, data, state, and cache directories. The platform-default config path is `~/.config/admin-pp-cli/config.toml`; `--home`, `CIRCLE_HOME`, and per-kind env vars can relocate it. Static request headers can be configured under `headers`; per-command header overrides take precedence. Environment variables: | Name | Kind | Required | Description | | --- | --- | --- | --- | | `CIRCLE_DEFAULTHOST` | endpoint | Yes | | | `CIRCLE_API_TOKEN` | per_call | Yes | Set to your API credential. | ### agentcookie (optional) If you use agentcookie to sync secrets across machines, this CLI auto-adopts agentcookie-managed credentials with no extra setup. When the daemon writes to this CLI's config, `circle-cli doctor` reports `agentcookie: detected` and `auth-status` labels the source as `agentcookie`. Skip this section if you don't use agentcookie - the CLI works the same as any other. ## Troubleshooting **Authentication errors (exit code 4)** - Run `circle-cli doctor` to check credentials - Verify the environment variable is set: `echo $CIRCLE_API_TOKEN` **Not found errors (exit code 3)** - Check the resource ID is correct - Run the `list` command to see available items ### API-specific - **401 or 403 on every call** — Confirm CIRCLE_API_TOKEN is an Admin API V2 token (not Headless or V1) and the creating admin still has admin rights; run `circle-cli quota`. - **429 Too Many Requests** — Circle allows 2000 requests / 5 minutes per IP; the CLI backs off automatically — prefer `sync` once then query the local cache instead of repeated live reads. - **Monthly quota draining fast** — Failed requests also count; run `circle-cli quota` to preflight and use offline `search`/`resolve`/`audit` commands that cost zero quota. - **Can't find a Space ID** — Run `circle-cli resolve "<space name>" --type space` to resolve it from the local cache. ## Sources & Inspiration This CLI was built by studying these projects and resources: - [**circle-so-api-php-sdk**](https://github.com/adrosoftware/circle-so-api-php-sdk) — PHP (4 stars) - [**CirclePy**](https://github.com/atomimus/CirclePy) — Python (1 stars) - [**circleso-go**](https://github.com/miguelbemartin/circleso-go) — Go (1 stars) - [**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 Generated by [CLI Printing Press](https://github.com/mvanhorn/cli-printing-press)