A unified command-line utility (CLI) and AI Agent Skill designed for Circle.so community administrators. It automates common administrative operations, schedules events with cover images, and performs concurrent security/spam safety audits.
Built as a zero-dependency, single-file CLI script in Python, it integrates seamlessly with AI coding agents (like Antigravity, Claude Code, Cursor, and Gemini CLI) while working perfectly as a standalone CLI for humans.
- Member Management: Lookup members by email/ID and toggle messaging permissions (e.g. banning spam accounts from sending DMs).
- DM Security Auditing: Retrieve conversation transcripts and raw JSON logs of single members via Headless API to audit suspected phishing or fraud.
- Concurrent DM Scanning: Concurrently scan DMs of recently joined members (sliding window) to detect spam behavior:
- High Risk: Message sent within 1 hour of joining, or template messages sent to multiple users.
- Watch: Messaging starts within 24 hours, or has 3+ active non-admin DM threads.
- Blacklist Monitoring: Scan recent signups against a text/markdown blacklist file containing known malicious email addresses (zero headless API quota consumption).
- Event Scheduling & Cover Uploads: Create draft/published events. Handles Active Storage Direct Uploads to S3 automatically—calculating file checksums, performing multipart PUT uploads, and generating the required event settings.
- Poll Audits: Read active poll questions, vote numbers, and response percentages.
- AI Agent Integration: Ships with
SKILL.mdto immediately teach AI coding agents how to execute CLI tasks and perform browser automation (e.g., scheduling polls, which is not supported by Circle's API).
Clone this repository:
git clone https://github.com/Watermelon4000/circle-admin-skill.git
cd circle-admin-skillOr just download the CLI script:
curl -o circle_admin.py https://raw.githubusercontent.com/Watermelon4000/circle-admin-skill/main/scripts/circle_admin.py
chmod +x circle_admin.pySet your Circle Admin API V2 tokens and Headless API tokens in your environment:
# Add to your shell profile (~/.zshrc or ~/.bashrc)
export CIRCLE_ADMIN_TOKEN="your_admin_v2_token_here"
export CIRCLE_HEADLESS_TOKEN="your_headless_token_here"
# (Optional) If managing multiple communities, you can set community-specific tokens
export PF_CIRCLE_ADMIN_TOKEN="your_pathunfold_admin_token"
export PF_CIRCLE_HEADLESS_TOKEN="your_pathunfold_headless_token"- Admin Token: Generate in Circle Settings → Developers → API Keys.
- Headless Token: Generate via the Circle Headless Admin console.
Run python3 scripts/circle_admin.py --help for full usage documentation.
The CLI supports two preconfigured community shorthand profiles:
onb: 一口新饭 (One New Bite)pf: 用AI发电 (PathUnfold)
Pass --community onb or --community pf to load community defaults. Otherwise, specify your community base URL and credentials using global flags (e.g., --base-url, --admin-token, --headless-token).
python3 scripts/circle_admin.py --community onb member search --email member@domain.compython3 scripts/circle_admin.py --community onb member update-preference --id 123456 --messaging-enabled-by-admin falsepython3 scripts/circle_admin.py --community onb dm audit --email suspect@gmail.com --output ./audit_logs/python3 scripts/circle_admin.py --community onb dm scan --days 30 --workers 10 --db-path ./db/member_db.json --output-dir ./results/python3 scripts/circle_admin.py dm blacklist-check --days 7 --blacklist-file blacklist.mdpython3 scripts/circle_admin.py --community onb event create \
--space-id 2205346 \
--name "Intro to AI Workflow Automation" \
--host "Zihong Chen" \
--starts-at "2026-07-15T19:00:00Z" \
--ends-at "2026-07-15T20:30:00Z" \
--body "<h2>Workshop Overview</h2><p>Learn to design stateful AI agent loops.</p>" \
--location-type live_room \
--access-type open \
--cover ./banners/workshop_cover.png \
--status draftTo teach an AI agent how to manage your Circle community:
Copy this repository or its files into your agent config:
mkdir -p ~/.gemini/antigravity/skills/circle-admin-skill
cp -r SKILL.md scripts/ ~/.gemini/antigravity/skills/circle-admin-skill/Add the skill files to the Claude skills directory:
mkdir -p ~/.claude/skills/circle-admin-skill
cp -r SKILL.md scripts/ ~/.claude/skills/circle-admin-skill/Add SKILL.md rules or link the files inside your project .cursorrules.
The AI agent will read SKILL.md to autonomously discover command-line parameters, security classification thresholds, and interactive browser steps (such as poll scheduling) to execute community manager tasks on your behalf.
circle-admin-skill/
├── LICENSE # MIT License
├── README.md # Developer/User documentation
├── SKILL.md # Agent system instructions (system prompts)
└── scripts/
└── circle_admin.py # Unified single-file Python CLI script
This project is licensed under the MIT License. See LICENSE for details.
Created by Zihong Chen (小西瓜).