Skip to content

About

Circle.so Administrator CLI & AI Agent Skill for community management and security audits.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Circle.so Admin Agent Skill & CLI

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.


Features

  • 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.md to 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).

Installation & Setup

1. Download/Clone

Clone this repository:

git clone https://github.com/Watermelon4000/circle-admin-skill.git
cd circle-admin-skill

Or 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.py

2. Configure Environment Variables

Set 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.

Command Line Interface (CLI) Usage

Run python3 scripts/circle_admin.py --help for full usage documentation.

Preconfigured Profiles

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).

Examples

Search for a member:

python3 scripts/circle_admin.py --community onb member search --email member@domain.com

Ban a member from sending messages (admin-level ban):

python3 scripts/circle_admin.py --community onb member update-preference --id 123456 --messaging-enabled-by-admin false

Audit a single suspect member's DMs (consumes 1 Headless API quota unit):

python3 scripts/circle_admin.py --community onb dm audit --email suspect@gmail.com --output ./audit_logs/

Concurrently scan members who joined in the last 30 days:

python3 scripts/circle_admin.py --community onb dm scan --days 30 --workers 10 --db-path ./db/member_db.json --output-dir ./results/

Check recent signups against a blacklist file:

python3 scripts/circle_admin.py dm blacklist-check --days 7 --blacklist-file blacklist.md

Create a live event with a cover image:

python3 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 draft

AI Agent Integration (AI Skill Setup)

To teach an AI agent how to manage your Circle community:

Antigravity / Gemini CLI

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/

Claude Code

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/

Cursor

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.


Repository Structure

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

License

This project is licensed under the MIT License. See LICENSE for details.

Author

Created by Zihong Chen (小西瓜).

About

Circle.so Administrator CLI & AI Agent Skill for community management and security audits.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages