circle-so-cli 0.1.0__tar.gz

circle_so_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -e .[dev]
+      - run: pytest tests/ -v

circle_so_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,21 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: false

circle_so_cli-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.env
+*.db
+.pytest_cache/
+.ruff_cache/
+.DS_Store

circle_so_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Damilola Afolabi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

circle_so_cli-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: circle-so-cli
+Version: 0.1.0
+Summary: CLI toolkit for managing Circle.so communities at scale
+Project-URL: Homepage, https://github.com/boiyelove/circle-so
+Project-URL: Repository, https://github.com/boiyelove/circle-so
+Author: Damilola Afolabi
+License-Expression: MIT
+License-File: LICENSE
+Keywords: circle,circle.so,cli,community,management
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: circle-so-python-sdk>=0.1.0
+Requires-Dist: click>=8.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# circle-so
+
+CLI toolkit for managing Circle.so communities at scale.
+
+Built on top of [circle-so-python-sdk](https://github.com/boiyelove/circle-so-python-sdk).
+
+## Installation
+
+```bash
+pip install circle-so
+```
+
+## Quick Start
+
+```bash
+export CIRCLE_API_TOKEN="your_token"
+
+# Spaces
+circle-so spaces list --prefix kcna
+circle-so spaces search "KCNA 048"
+circle-so spaces lock --prefix kcna
+circle-so spaces rename 1761784 --name "KCNA 072" --slug "kcna-072"
+
+# Members
+circle-so members import learners.csv
+circle-so members audit --prefix kcna --cache
+circle-so members add learners.csv --space "KCNA 048"
+circle-so members fix-missing --dry-run
+circle-so members move --from "KCNA 046" --to "KCNA 073" --max 100
+
+# Moderators
+circle-so moderators verify moderators.csv
+circle-so moderators add moderators.csv
+
+# Reports
+circle-so report counts --prefix kcna
+circle-so report inactive
+circle-so report missing
+circle-so report export moves
+```
+
+## Configuration
+
+Set via environment variables or `.env` file:
+
+```bash
+CIRCLE_API_TOKEN=your_token
+CIRCLE_COMMUNITY_URL=https://your-community.circle.so
+CIRCLE_SO_DB=./circle-so.db
+CIRCLE_SO_DATA_DIR=~/Documents/Andela-K8s
+```
+
+## License
+
+MIT

circle_so_cli-0.1.0/README.md

@@ -0,0 +1,55 @@
+# circle-so
+
+CLI toolkit for managing Circle.so communities at scale.
+
+Built on top of [circle-so-python-sdk](https://github.com/boiyelove/circle-so-python-sdk).
+
+## Installation
+
+```bash
+pip install circle-so
+```
+
+## Quick Start
+
+```bash
+export CIRCLE_API_TOKEN="your_token"
+
+# Spaces
+circle-so spaces list --prefix kcna
+circle-so spaces search "KCNA 048"
+circle-so spaces lock --prefix kcna
+circle-so spaces rename 1761784 --name "KCNA 072" --slug "kcna-072"
+
+# Members
+circle-so members import learners.csv
+circle-so members audit --prefix kcna --cache
+circle-so members add learners.csv --space "KCNA 048"
+circle-so members fix-missing --dry-run
+circle-so members move --from "KCNA 046" --to "KCNA 073" --max 100
+
+# Moderators
+circle-so moderators verify moderators.csv
+circle-so moderators add moderators.csv
+
+# Reports
+circle-so report counts --prefix kcna
+circle-so report inactive
+circle-so report missing
+circle-so report export moves
+```
+
+## Configuration
+
+Set via environment variables or `.env` file:
+
+```bash
+CIRCLE_API_TOKEN=your_token
+CIRCLE_COMMUNITY_URL=https://your-community.circle.so
+CIRCLE_SO_DB=./circle-so.db
+CIRCLE_SO_DATA_DIR=~/Documents/Andela-K8s
+```
+
+## License
+
+MIT

circle_so_cli-0.1.0/docs/ROADMAP.md

@@ -0,0 +1,58 @@
+# Roadmap
+
+## Phase 1: Core CLI (Current)
+- [x] Project scaffolding
+- [ ] CLI framework with click
+- [ ] Config management (env vars, .env, flags)
+- [ ] DB schema with versioned migrations
+- [ ] `spaces` commands: list, search, rename, lock/unlock
+- [ ] `members` commands: import, audit, add, fix-missing
+- [ ] `moderators` commands: verify, add
+- [ ] `report` commands: counts, inactive, missing, export
+
+## Phase 2: Caching Layer
+- [ ] `--cache` flag on read commands
+- [ ] TTL-based cache in SQLite (default 1 hour)
+- [ ] `--refresh` flag to force fresh fetch
+- [ ] Cache invalidation on write operations
+- [ ] Cache stats command (`circle-so cache stats`, `circle-so cache clear`)
+
+## Phase 3: Member Movement
+- [ ] `members move` with engagement detection (posts, comments)
+- [ ] Move planning with local preview (zero API calls)
+- [ ] Move execution with verification
+- [ ] Rollback support for failed moves
+- [ ] Move history and audit trail in DB
+
+## Phase 4: Bulk Operations
+- [ ] Batch member invitations with progress bar
+- [ ] Batch space creation from CSV/template
+- [ ] Batch moderator assignment (when Circle API supports per-space moderators)
+- [ ] Rate limit awareness with ETA display
+
+## Phase 5: Observability
+- [ ] `--verbose` and `--debug` flags on all commands
+- [ ] Structured JSON logging option
+- [ ] Operation audit log in DB (who did what, when)
+- [ ] Diff reports (before/after state comparison)
+
+## Phase 6: Multi-Community
+- [ ] Named profiles (`circle-so --profile staging`)
+- [ ] Profile management (`circle-so profile add/list/switch`)
+- [ ] Per-profile DB and cache isolation
+
+## Phase 7: Advanced Reports
+- [ ] Member engagement scoring per space
+- [ ] Inactive member detection with configurable thresholds
+- [ ] Space health dashboard (member count, activity, moderator coverage)
+- [ ] CSV/JSON/Markdown export formats
+
+## Phase 8: Plugin System
+- [ ] Hook system for pre/post command execution
+- [ ] Custom command registration
+- [ ] Webhook receiver for real-time sync
+
+## Non-Goals
+- Replacing the Circle.so web UI for day-to-day operations
+- Real-time chat or notification management
+- Content creation or moderation workflows

circle_so_cli-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "circle-so-cli"
+version = "0.1.0"
+description = "CLI toolkit for managing Circle.so communities at scale"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Damilola Afolabi" }]
+keywords = ["circle", "circle.so", "community", "cli", "management"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Typing :: Typed",
+]
+dependencies = [
+    "circle-so-python-sdk>=0.1.0",
+    "click>=8.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "ruff>=0.1.0",
+]
+
+[project.scripts]
+circle-so = "circle_so.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/boiyelove/circle-so"
+Repository = "https://github.com/boiyelove/circle-so"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/circle_so"]
+
+[tool.ruff]
+target-version = "py39"
+line-length = 120
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

circle_so_cli-0.1.0/src/circle_so/__init__.py

@@ -0,0 +1,2 @@
+"""circle-so: CLI toolkit for managing Circle.so communities at scale."""
+__version__ = "0.1.0"

circle_so_cli-0.1.0/src/circle_so/cli.py

@@ -0,0 +1,51 @@
+"""Main CLI entry point."""
+import click
+from circle_so.config import Config
+
+pass_config = click.make_pass_decorator(Config, ensure=True)
+
+
+@click.group()
+@click.option("--db", envvar="CIRCLE_SO_DB", default="./circle-so.db", help="Path to SQLite database")
+@click.option("--rate-limit", envvar="CIRCLE_SO_RATE_LIMIT", default=5, type=int, help="API requests per second")
+@click.pass_context
+def main(ctx, db, rate_limit):
+    """CLI toolkit for managing Circle.so communities at scale."""
+    ctx.ensure_object(Config)
+    ctx.obj = Config(db_path=db, rate_limit=rate_limit)
+
+
+@main.group()
+@pass_config
+def spaces(config):
+    """Manage spaces."""
+
+
+@main.group()
+@pass_config
+def members(config):
+    """Manage members."""
+
+
+@main.group()
+@pass_config
+def moderators(config):
+    """Manage moderators."""
+
+
+@main.group()
+@pass_config
+def report(config):
+    """Generate reports."""
+
+
+# Register subcommands
+from circle_so.commands.spaces import register as register_spaces
+from circle_so.commands.members import register as register_members
+from circle_so.commands.moderators import register as register_moderators
+from circle_so.commands.report import register as register_report
+
+register_spaces(spaces)
+register_members(members)
+register_moderators(moderators)
+register_report(report)

circle_so_cli-0.1.0/src/circle_so/commands/__init__.py

@@ -0,0 +1 @@
+"""Commands package."""

circle_so_cli-0.1.0/src/circle_so/commands/members.py

@@ -0,0 +1,155 @@
+"""Member management commands."""
+import csv
+import click
+from circle_so.config import Config
+
+pass_config = click.make_pass_decorator(Config)
+
+
+def register(group):
+    group.add_command(import_members)
+    group.add_command(audit)
+    group.add_command(add)
+    group.add_command(fix_missing)
+
+
+@click.command("import")
+@click.argument("csv_path", type=click.Path(exists=True))
+@pass_config
+def import_members(config, csv_path):
+    """Import members from CSV into local database."""
+    conn = config.get_db()
+    count = 0
+    with open(csv_path, newline="") as f:
+        reader = csv.DictReader(f)
+        plg_col = next((c for c in reader.fieldnames if c.lower() in ("plgs", "plg")), None)
+        country_col = next((c for c in reader.fieldnames if c.lower() == "country"), None)
+        for row in reader:
+            conn.execute(
+                "INSERT OR IGNORE INTO members (first_name, email, country, plg) VALUES (?, ?, ?, ?)",
+                (row.get("first_name", "").strip(), row.get("email", "").strip(),
+                 row.get(country_col, "").strip() if country_col else "",
+                 row.get(plg_col, "").strip() if plg_col else ""))
+            count += 1
+    conn.commit()
+    total = conn.execute("SELECT COUNT(*) FROM members").fetchone()[0]
+    click.echo(f"Imported {count} rows. Total: {total}")
+
+
+@click.command()
+@click.option("--prefix", default="all", help="Filter: kcna, ckad, or all")
+@click.option("--cache", is_flag=True, help="Use cached data")
+@pass_config
+def audit(config, prefix, cache):
+    """Audit members against Circle API."""
+    from circle.pagination import paginate
+    conn = config.get_db()
+    client = config.get_client()
+    where = f"AND plg LIKE '{prefix.upper()}%'" if prefix != "all" else ""
+    spaces = conn.execute(f"SELECT plg, space_id FROM spaces WHERE space_id IS NOT NULL {where} ORDER BY plg").fetchall()
+    click.echo(f"Auditing {len(spaces)} spaces...")
+    conn.execute(f"UPDATE members SET in_space = 0 WHERE 1=1 {where}")
+    for plg, space_id in spaces:
+        emails = set()
+        for m in paginate(client.admin.spaces.list_space_members, space_id=space_id, per_page=200):
+            cm = m.community_member
+            if cm and cm.email:
+                emails.add(cm.email.lower())
+        expected = conn.execute("SELECT id, email FROM members WHERE plg = ?", (plg,)).fetchall()
+        matched = sum(1 for lid, email in expected if email.strip().lower() in emails)
+        for lid, email in expected:
+            if email.strip().lower() in emails:
+                conn.execute("UPDATE members SET in_space = 1 WHERE id = ?", (lid,))
+        click.echo(f"{plg}: {matched}/{len(expected)} matched, {len(expected)-matched} missing")
+    conn.commit()
+    client.close()
+
+
+@click.command()
+@click.argument("csv_path", type=click.Path(exists=True))
+@click.option("--space", required=True, help="PLG name, e.g. 'KCNA 048'")
+@click.option("--dry-run", is_flag=True)
+@pass_config
+def add(config, csv_path, space, dry_run):
+    """Add members from CSV to a space."""
+    from circle.exceptions import CircleAPIError, NotFoundError
+    conn = config.get_db()
+    row = conn.execute("SELECT space_id FROM spaces WHERE plg=?", (space,)).fetchone()
+    if not row:
+        click.echo(f"PLG '{space}' not found. Run: circle-so spaces list")
+        return
+    space_id = row[0]
+    users = []
+    with open(csv_path, newline="") as f:
+        for r in csv.reader(f):
+            if len(r) >= 2 and r[1].strip():
+                users.append({"name": r[0].strip(), "email": r[1].strip()})
+    click.echo(f"{len(users)} users -> {space} (id={space_id})")
+    if dry_run:
+        for u in users:
+            click.echo(f"[DRY RUN] {u['name']} ({u['email']})")
+        return
+    client = config.get_client()
+    sg_id = int(os.environ.get("CIRCLE_SPACE_GROUP_ID", "0"))
+    import os
+    success = failed = 0
+    for u in users:
+        try:
+            client.admin.spaces.add_space_member(email=u["email"], space_id=space_id)
+            success += 1
+        except NotFoundError:
+            try:
+                client.admin.community.create_community_member(
+                    email=u["email"], name=u["name"], skip_invitation=True,
+                    space_group_ids=[sg_id] if sg_id else [])
+                client.admin.spaces.add_space_member(email=u["email"], space_id=space_id)
+                success += 1
+            except CircleAPIError as e:
+                click.echo(f"FAILED: {u['email']}: {e}")
+                failed += 1
+        except CircleAPIError:
+            success += 1  # likely already member
+    click.echo(f"Done: {success} added, {failed} failed")
+    client.close()
+
+
+@click.command("fix-missing")
+@click.option("--dry-run", is_flag=True)
+@pass_config
+def fix_missing(config, dry_run):
+    """Add all members marked as missing in the database to their spaces."""
+    import os
+    from circle.exceptions import CircleAPIError, NotFoundError
+    conn = config.get_db()
+    missing = conn.execute("""
+        SELECT id, first_name, email, plg, space_id FROM members
+        WHERE in_space = 0 AND space_id IS NOT NULL ORDER BY plg
+    """).fetchall()
+    click.echo(f"{len(missing)} missing members")
+    if dry_run:
+        for _, name, email, plg, _ in missing:
+            click.echo(f"[DRY RUN] {name} ({email}) -> {plg}")
+        return
+    client = config.get_client()
+    sg_id = int(os.environ.get("CIRCLE_SPACE_GROUP_ID", "0"))
+    added = failed = 0
+    for lid, name, email, plg, space_id in missing:
+        try:
+            client.admin.spaces.add_space_member(email=email, space_id=space_id)
+        except NotFoundError:
+            try:
+                client.admin.community.create_community_member(
+                    email=email, name=name, skip_invitation=True,
+                    space_group_ids=[sg_id] if sg_id else [])
+                client.admin.spaces.add_space_member(email=email, space_id=space_id)
+            except CircleAPIError as e:
+                click.echo(f"FAILED: {email}: {e}")
+                failed += 1
+                continue
+        except CircleAPIError:
+            pass
+        conn.execute("UPDATE members SET in_space = 1 WHERE id = ?", (lid,))
+        added += 1
+    conn.commit()
+    click.echo(f"Done: {added} added, {failed} failed")
+    client.close()

circle_so_cli-0.1.0/src/circle_so/commands/moderators.py

@@ -0,0 +1,114 @@
+"""Moderator management commands."""
+import csv
+import click
+from circle_so.config import Config
+
+pass_config = click.make_pass_decorator(Config)
+
+
+def register(group):
+    group.add_command(verify)
+    group.add_command(add)
+
+
+@click.command()
+@click.argument("csv_path", type=click.Path(exists=True))
+@pass_config
+def verify(config, csv_path):
+    """Verify moderators are in their spaces with moderator status."""
+    from circle.exceptions import CircleAPIError
+    conn = config.get_db()
+    client = config.get_client()
+    mods = _parse_moderators_csv(csv_path)
+    click.echo(f"{'Name':<35} {'PLG':<12} {'In Space':<10} {'Moderator'}")
+    click.echo("-" * 72)
+    in_space = not_in = moderators = 0
+    for m in mods:
+        space = conn.execute("SELECT space_id FROM spaces WHERE plg=?", (m["plg"],)).fetchone()
+        if not space:
+            click.echo(f"{m['name']:<35} {m['plg']:<12} {'NO SPACE':<10} -")
+            continue
+        try:
+            sm = client.admin.spaces.show_space_member(email=m["email"], space_id=space[0])
+            is_mod = sm.moderator
+            click.echo(f"{m['name']:<35} {m['plg']:<12} {'YES':<10} {'YES' if is_mod else 'NO'}")
+            in_space += 1
+            if is_mod:
+                moderators += 1
+        except CircleAPIError:
+            click.echo(f"{m['name']:<35} {m['plg']:<12} {'NO':<10} -")
+            not_in += 1
+    click.echo(f"\n{in_space} in space, {not_in} missing, {moderators}/{in_space} moderators")
+    client.close()
+
+
+@click.command()
+@click.argument("csv_path", type=click.Path(exists=True))
+@click.option("--dry-run", is_flag=True)
+@pass_config
+def add(config, csv_path, dry_run):
+    """Add moderators to their spaces (membership only -- moderator role requires Circle UI)."""
+    import os
+    from circle.exceptions import CircleAPIError, NotFoundError
+    conn = config.get_db()
+    client = config.get_client()
+    sg_id = int(os.environ.get("CIRCLE_SPACE_GROUP_ID", "0"))
+    mods = _parse_moderators_csv(csv_path)
+    click.echo(f"{len(mods)} moderators to process")
+    added = already = failed = 0
+    for m in mods:
+        space = conn.execute("SELECT space_id FROM spaces WHERE plg=?", (m["plg"],)).fetchone()
+        if not space:
+            click.echo(f"SKIP: {m['name']} -> {m['plg']} (no space)")
+            continue
+        if dry_run:
+            click.echo(f"[DRY RUN] {m['name']} -> {m['plg']}")
+            continue
+        try:
+            client.admin.spaces.show_space_member(email=m["email"], space_id=space[0])
+            already += 1
+            continue
+        except CircleAPIError:
+            pass
+        try:
+            client.admin.spaces.add_space_member(email=m["email"], space_id=space[0])
+            click.echo(f"Added: {m['name']} -> {m['plg']}")
+            added += 1
+        except NotFoundError:
+            try:
+                client.admin.community.create_community_member(
+                    email=m["email"], name=m["name"], skip_invitation=True,
+                    space_group_ids=[sg_id] if sg_id else [])
+                client.admin.spaces.add_space_member(email=m["email"], space_id=space[0])
+                click.echo(f"Invited+Added: {m['name']} -> {m['plg']}")
+                added += 1
+            except CircleAPIError as e:
+                click.echo(f"FAILED: {m['name']}: {e}")
+                failed += 1
+        except CircleAPIError:
+            already += 1
+    click.echo(f"\nDone: {added} added, {already} already, {failed} failed")
+    click.echo("NOTE: Moderator role must be assigned in Circle UI.")
+    client.close()
+
+
+def _parse_moderators_csv(csv_path):
+    """Auto-detect CSV format for moderators."""
+    mods = []
+    with open(csv_path, newline="") as f:
+        reader = csv.reader(f)
+        first = next(reader)
+        f.seek(0)
+        if any("email" in c.lower() for c in first):
+            for row in csv.DictReader(f):
+                email = (row.get("email") or row.get("Email Address") or row.get("Email") or "").strip()
+                name = f"{row.get('first_name', row.get('First Name', '')).strip()} {row.get('last_name', row.get('Last Name', '')).strip()}".strip()
+                plg = (row.get("PLGs") or row.get("PLG") or "").strip()
+                if email:
+                    mods.append({"email": email, "name": name, "plg": plg})
+        else:
+            f.seek(0)
+            for row in csv.reader(f):
+                if len(row) >= 3:
+                    mods.append({"email": row[0].strip(), "name": f"{row[1].strip()} {row[2].strip()}", "plg": row[-1].strip()})
+    return mods

circle_so_cli-0.1.0/src/circle_so/commands/report.py

@@ -0,0 +1,94 @@
+"""Report commands."""
+import csv
+import os
+import click
+from circle_so.config import Config
+
+pass_config = click.make_pass_decorator(Config)
+
+
+def register(group):
+    group.add_command(counts)
+    group.add_command(inactive)
+    group.add_command(missing)
+    group.add_command(export)
+
+
+@click.command()
+@click.option("--prefix", default="all", help="Filter: kcna, ckad, or all")
+@click.option("--over", default=0, type=int, help="Only show PLGs with more than N members")
+@pass_config
+def counts(config, prefix, over):
+    """Show member counts per PLG."""
+    conn = config.get_db()
+    where = f"WHERE m.plg LIKE '{prefix.upper()}%'" if prefix != "all" else ""
+    rows = conn.execute(f"""
+        SELECT m.plg, COUNT(*) as cnt, s.space_id, s.slug
+        FROM members m LEFT JOIN spaces s ON m.plg = s.plg
+        {where} GROUP BY m.plg ORDER BY m.plg
+    """).fetchall()
+    click.echo(f"{'PLG':<12} {'Count':<8} {'Space ID':<10} {'Slug'}")
+    click.echo("-" * 45)
+    total = 0
+    for plg, cnt, sid, slug in rows:
+        if cnt > over:
+            click.echo(f"{plg:<12} {cnt:<8} {sid or 'MISSING':<10} {slug or 'MISSING'}")
+        total += cnt
+    click.echo(f"\nTotal: {total}")
+
+
+@click.command()
+@pass_config
+def inactive(config):
+    """List inactive members from last audit."""
+    conn = config.get_db()
+    try:
+        rows = conn.execute("""
+            SELECT space_name, COUNT(*) FROM move_audit WHERE status='inactive'
+            GROUP BY space_name ORDER BY space_name
+        """).fetchall()
+        for name, cnt in rows:
+            click.echo(f"{name}: {cnt} inactive")
+    except Exception:
+        click.echo("No audit data. Run: circle-so members audit")
+
+
+@click.command()
+@pass_config
+def missing(config):
+    """List members not in their assigned space."""
+    conn = config.get_db()
+    rows = conn.execute("""
+        SELECT plg, COUNT(*) FROM members
+        WHERE in_space = 0 AND space_id IS NOT NULL
+        GROUP BY plg ORDER BY plg
+    """).fetchall()
+    if not rows:
+        click.echo("No missing members.")
+        return
+    for plg, cnt in rows:
+        click.echo(f"{plg}: {cnt} missing")
+
+
+@click.command()
+@click.argument("report_type", type=click.Choice(["inactive", "missing", "moves", "plg_changes"]))
+@click.option("--output", "-o", default=None, help="Output path (default: data dir)")
+@pass_config
+def export(config, report_type, output):
+    """Export report to CSV."""
+    conn = config.get_db()
+    queries = {
+        "inactive": "SELECT space_name, email, access_type, created_at FROM move_audit WHERE status='inactive' ORDER BY space_name",
+        "missing": "SELECT plg, first_name, email FROM members WHERE in_space=0 AND space_id IS NOT NULL ORDER BY plg",
+        "moves": "SELECT from_plg, to_plg, COUNT(*) FROM moves WHERE status='done' GROUP BY from_plg, to_plg",
+        "plg_changes": "SELECT name, email, from_plg, to_plg FROM moves WHERE status='done' ORDER BY to_plg",
+    }
+    query = queries[report_type]
+    rows = conn.execute(query).fetchall()
+    cols = [d[0] for d in conn.execute(query).description]
+    out_path = output or os.path.join(config.data_dir, f"{report_type}.csv")
+    with open(out_path, "w", newline="") as f:
+        w = csv.writer(f)
+        w.writerow(cols)
+        w.writerows(rows)
+    click.echo(f"Exported {len(rows)} rows to {out_path}")

circle_so_cli-0.1.0/src/circle_so/commands/spaces.py

@@ -0,0 +1,91 @@
+"""Space management commands."""
+import click
+from circle_so.config import Config
+
+pass_config = click.make_pass_decorator(Config)
+
+
+def register(group):
+    group.add_command(list_spaces)
+    group.add_command(search)
+    group.add_command(rename)
+    group.add_command(lock)
+
+
+@click.command("list")
+@click.option("--prefix", default="all", help="Filter by prefix: kcna, ckad, or all")
+@click.option("--cache", is_flag=True, help="Use cached data instead of API")
+@pass_config
+def list_spaces(config, prefix, cache):
+    """List all spaces."""
+    from circle.pagination import paginate
+    client = config.get_client()
+    for s in paginate(client.admin.spaces.list_spaces, per_page=200):
+        slug = s.slug or ""
+        if prefix == "all" or slug.startswith(prefix.lower()):
+            click.echo(f"{s.name:<16} id={s.id:<10} slug={slug}")
+    client.close()
+
+
+@click.command()
+@click.argument("names", nargs=-1, required=True)
+@pass_config
+def search(config, names):
+    """Search for spaces by name or slug."""
+    from circle.pagination import paginate
+    client = config.get_client()
+    all_spaces = list(paginate(client.admin.spaces.list_spaces, per_page=200))
+    for target in names:
+        target_slug = target.lower().replace(" ", "-")
+        click.echo(f"'{target}':")
+        found = False
+        for s in all_spaces:
+            if (s.name and s.name.strip() == target) or (s.slug and s.slug.startswith(target_slug)):
+                click.echo(f"  name='{s.name}' id={s.id} slug={s.slug} type={s.space_type}")
+                found = True
+        if not found:
+            click.echo("  Not found")
+    client.close()
+
+
+@click.command()
+@click.argument("space_id", type=int)
+@click.option("--name", required=True, help="New space name")
+@click.option("--slug", default=None, help="New slug (auto-generated if omitted)")
+@pass_config
+def rename(config, space_id, name, slug):
+    """Rename a space."""
+    client = config.get_client()
+    kwargs = {"name": name}
+    if slug:
+        kwargs["slug"] = slug
+    result = client.admin.spaces.update_space(space_id, **kwargs)
+    click.echo(f"Renamed: {result.name} (slug={result.slug})")
+    client.close()
+
+
+@click.command()
+@click.option("--prefix", default="all", help="Filter: kcna, ckad, or all")
+@click.option("--unlock", is_flag=True, help="Unlock instead of lock")
+@click.option("--dry-run", is_flag=True, help="Preview without changes")
+@pass_config
+def lock(config, prefix, unlock, dry_run):
+    """Lock/unlock spaces: disable member posting and member-adding."""
+    from circle.pagination import paginate
+    client = config.get_client()
+    action = "Unlocking" if unlock else "Locking"
+    success = 0
+    for s in paginate(client.admin.spaces.list_spaces, per_page=200):
+        slug = s.slug or ""
+        if prefix != "all" and not slug.startswith(prefix.lower()):
+            continue
+        if dry_run:
+            click.echo(f"[DRY RUN] {action}: {s.name}")
+            continue
+        client.admin.spaces.update_space(s.id,
+            is_post_disabled=not unlock,
+            prevent_members_from_adding_others=not unlock)
+        click.echo(f"{action}: {s.name}")
+        success += 1
+    click.echo(f"\nDone: {success} spaces")
+    client.close()

circle_so_cli-0.1.0/src/circle_so/config.py

@@ -0,0 +1,29 @@
+"""Configuration management. Reads from env vars, .env file, and CLI flags."""
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+class Config:
+    def __init__(self, **overrides):
+        self.api_token = overrides.get("api_token") or os.environ.get("CIRCLE_API_TOKEN")
+        self.community_url = overrides.get("community_url") or os.environ.get("CIRCLE_COMMUNITY_URL")
+        self.db_path = overrides.get("db_path") or os.environ.get("CIRCLE_SO_DB", "./circle-so.db")
+        self.data_dir = overrides.get("data_dir") or os.environ.get("CIRCLE_SO_DATA_DIR", ".")
+        self.rate_limit = int(overrides.get("rate_limit") or os.environ.get("CIRCLE_SO_RATE_LIMIT", "5"))
+        self.cache_ttl = int(overrides.get("cache_ttl") or os.environ.get("CIRCLE_SO_CACHE_TTL", "3600"))
+
+    def get_client(self):
+        from circle import CircleClient
+        return CircleClient(
+            api_token=self.api_token,
+            community_url=self.community_url,
+            rate_limit=self.rate_limit,
+        )
+
+    def get_db(self):
+        from circle_so.db.connection import get_connection
+        return get_connection(self.db_path)

circle_so_cli-0.1.0/src/circle_so/db/__init__.py

@@ -0,0 +1 @@
+"""DB package."""

circle_so_cli-0.1.0/src/circle_so/db/connection.py

@@ -0,0 +1,109 @@
+"""DB connection and schema migrations."""
+import sqlite3
+
+MIGRATIONS = [
+    # v1: core tables
+    """
+    CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY);
+    INSERT OR IGNORE INTO schema_version VALUES (0);
+    """,
+    # v1: spaces
+    """
+    CREATE TABLE IF NOT EXISTS spaces (
+        id INTEGER PRIMARY KEY,
+        plg TEXT UNIQUE,
+        space_id INTEGER,
+        slug TEXT
+    );
+    """,
+    # v2: members
+    """
+    CREATE TABLE IF NOT EXISTS members (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        first_name TEXT,
+        email TEXT UNIQUE,
+        country TEXT,
+        plg TEXT,
+        space_id INTEGER,
+        in_community BOOLEAN,
+        in_space BOOLEAN,
+        community_member_id INTEGER
+    );
+    """,
+    # v3: moderators
+    """
+    CREATE TABLE IF NOT EXISTS moderators (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        email TEXT,
+        name TEXT,
+        plg TEXT,
+        space_id INTEGER,
+        in_space BOOLEAN,
+        is_moderator BOOLEAN,
+        UNIQUE(email, plg)
+    );
+    """,
+    # v4: moves
+    """
+    CREATE TABLE IF NOT EXISTS moves (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        email TEXT,
+        name TEXT,
+        community_member_id INTEGER,
+        from_space_id INTEGER,
+        from_plg TEXT,
+        to_space_id INTEGER,
+        to_plg TEXT,
+        status TEXT DEFAULT 'planned'
+    );
+    """,
+    # v5: cache
+    """
+    CREATE TABLE IF NOT EXISTS cache (
+        key TEXT PRIMARY KEY,
+        data TEXT,
+        fetched_at TEXT DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE TABLE IF NOT EXISTS space_members_cache (
+        id INTEGER PRIMARY KEY,
+        space_id INTEGER,
+        email TEXT,
+        community_member_id INTEGER,
+        moderator BOOLEAN,
+        access_type TEXT,
+        status TEXT,
+        created_at TEXT,
+        UNIQUE(space_id, email)
+    );
+    """,
+    # v6: engaged users
+    """
+    CREATE TABLE IF NOT EXISTS engaged_users (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        space_id INTEGER,
+        community_member_id INTEGER,
+        engagement_type TEXT,
+        UNIQUE(space_id, community_member_id, engagement_type)
+    );
+    """,
+]
+
+
+def get_connection(db_path: str) -> sqlite3.Connection:
+    conn = sqlite3.connect(db_path)
+    conn.execute("PRAGMA journal_mode=WAL")
+    _migrate(conn)
+    return conn
+
+
+def _migrate(conn: sqlite3.Connection):
+    conn.execute("CREATE TABLE IF NOT EXISTS schema_version (version INTEGER PRIMARY KEY)")
+    conn.execute("INSERT OR IGNORE INTO schema_version VALUES (0)")
+    current = conn.execute("SELECT MAX(version) FROM schema_version").fetchone()[0]
+
+    for i, sql in enumerate(MIGRATIONS):
+        if i <= current:
+            continue
+        conn.executescript(sql)
+        conn.execute("INSERT INTO schema_version VALUES (?)", (i,))
+        conn.commit()

circle_so_cli-0.1.0/tests/__init__.py

@@ -0,0 +1,28 @@
+"""Test fixtures."""
+import os
+import pytest
+import sqlite3
+from click.testing import CliRunner
+from circle_so.cli import main
+from circle_so.config import Config
+from circle_so.db.connection import get_connection
+
+
+@pytest.fixture
+def runner():
+    return CliRunner()
+
+
+@pytest.fixture
+def tmp_db(tmp_path):
+    db_path = str(tmp_path / "test.db")
+    conn = get_connection(db_path)
+    yield db_path, conn
+    conn.close()
+
+
+@pytest.fixture(autouse=True)
+def env_setup(tmp_path, monkeypatch):
+    monkeypatch.setenv("CIRCLE_API_TOKEN", "test_token")
+    monkeypatch.setenv("CIRCLE_SO_DB", str(tmp_path / "test.db"))
+    monkeypatch.setenv("CIRCLE_SO_DATA_DIR", str(tmp_path))

circle_so_cli-0.1.0/tests/test_cli.py

@@ -0,0 +1,139 @@
+"""Tests for CLI commands."""
+import os
+import csv
+from click.testing import CliRunner
+from circle_so.cli import main
+from circle_so.db.connection import get_connection
+
+
+class TestCLI:
+    def test_help(self):
+        result = CliRunner().invoke(main, ["--help"])
+        assert result.exit_code == 0
+        assert "spaces" in result.output
+        assert "members" in result.output
+        assert "moderators" in result.output
+        assert "report" in result.output
+
+    def test_spaces_help(self):
+        result = CliRunner().invoke(main, ["spaces", "--help"])
+        assert result.exit_code == 0
+        assert "list" in result.output
+        assert "search" in result.output
+        assert "rename" in result.output
+        assert "lock" in result.output
+
+    def test_members_help(self):
+        result = CliRunner().invoke(main, ["members", "--help"])
+        assert result.exit_code == 0
+        assert "import" in result.output
+        assert "audit" in result.output
+        assert "add" in result.output
+        assert "fix-missing" in result.output
+
+    def test_moderators_help(self):
+        result = CliRunner().invoke(main, ["moderators", "--help"])
+        assert result.exit_code == 0
+        assert "verify" in result.output
+        assert "add" in result.output
+
+    def test_report_help(self):
+        result = CliRunner().invoke(main, ["report", "--help"])
+        assert result.exit_code == 0
+        assert "counts" in result.output
+        assert "inactive" in result.output
+        assert "missing" in result.output
+        assert "export" in result.output
+
+
+class TestMembersImport:
+    def test_import_csv(self, tmp_path, monkeypatch):
+        db_path = str(tmp_path / "test.db")
+        monkeypatch.setenv("CIRCLE_SO_DB", db_path)
+
+        csv_path = str(tmp_path / "learners.csv")
+        with open(csv_path, "w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["first_name", "email", "country", "PLG"])
+            w.writerow(["Alice", "alice@example.com", "Kenya", "KCNA 001"])
+            w.writerow(["Bob", "bob@example.com", "Nigeria", "KCNA 002"])
+
+        result = CliRunner().invoke(main, ["--db", db_path, "members", "import", csv_path])
+        assert result.exit_code == 0
+        assert "Imported 2" in result.output
+
+        conn = get_connection(db_path)
+        count = conn.execute("SELECT COUNT(*) FROM members").fetchone()[0]
+        assert count == 2
+        conn.close()
+
+    def test_import_idempotent(self, tmp_path, monkeypatch):
+        db_path = str(tmp_path / "test.db")
+        monkeypatch.setenv("CIRCLE_SO_DB", db_path)
+
+        csv_path = str(tmp_path / "learners.csv")
+        with open(csv_path, "w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["first_name", "email", "country", "PLG"])
+            w.writerow(["Alice", "alice@example.com", "Kenya", "KCNA 001"])
+
+        CliRunner().invoke(main, ["--db", db_path, "members", "import", csv_path])
+        CliRunner().invoke(main, ["--db", db_path, "members", "import", csv_path])
+
+        conn = get_connection(db_path)
+        count = conn.execute("SELECT COUNT(*) FROM members").fetchone()[0]
+        assert count == 1
+        conn.close()
+
+
+class TestReportCounts:
+    def test_counts_empty(self, tmp_path, monkeypatch):
+        db_path = str(tmp_path / "test.db")
+        monkeypatch.setenv("CIRCLE_SO_DB", db_path)
+        result = CliRunner().invoke(main, ["--db", db_path, "report", "counts"])
+        assert result.exit_code == 0
+        assert "Total: 0" in result.output
+
+    def test_counts_with_data(self, tmp_path, monkeypatch):
+        db_path = str(tmp_path / "test.db")
+        monkeypatch.setenv("CIRCLE_SO_DB", db_path)
+
+        csv_path = str(tmp_path / "learners.csv")
+        with open(csv_path, "w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["first_name", "email", "country", "PLG"])
+            w.writerow(["Alice", "a@example.com", "Kenya", "KCNA 001"])
+            w.writerow(["Bob", "b@example.com", "Kenya", "KCNA 001"])
+            w.writerow(["Carol", "c@example.com", "Kenya", "KCNA 002"])
+
+        CliRunner().invoke(main, ["--db", db_path, "members", "import", csv_path])
+        result = CliRunner().invoke(main, ["--db", db_path, "report", "counts"])
+        assert result.exit_code == 0
+        assert "KCNA 001" in result.output
+        assert "KCNA 002" in result.output
+        assert "Total: 3" in result.output
+
+    def test_counts_with_prefix_filter(self, tmp_path, monkeypatch):
+        db_path = str(tmp_path / "test.db")
+        monkeypatch.setenv("CIRCLE_SO_DB", db_path)
+
+        csv_path = str(tmp_path / "learners.csv")
+        with open(csv_path, "w", newline="") as f:
+            w = csv.writer(f)
+            w.writerow(["first_name", "email", "country", "PLG"])
+            w.writerow(["Alice", "a@example.com", "Kenya", "KCNA 001"])
+            w.writerow(["Bob", "b@example.com", "Kenya", "CKAD 001"])
+
+        CliRunner().invoke(main, ["--db", db_path, "members", "import", csv_path])
+        result = CliRunner().invoke(main, ["--db", db_path, "report", "counts", "--prefix", "kcna"])
+        assert "KCNA 001" in result.output
+        assert "CKAD" not in result.output
+
+
+class TestReportMissing:
+    def test_missing_none(self, tmp_path, monkeypatch):
+        db_path = str(tmp_path / "test.db")
+        monkeypatch.setenv("CIRCLE_SO_DB", db_path)
+        result = CliRunner().invoke(main, ["--db", db_path, "report", "missing"])
+        assert result.exit_code == 0
+        assert "No missing" in result.output

circle_so_cli-0.1.0/tests/test_config.py

@@ -0,0 +1,27 @@
+"""Tests for config."""
+import os
+from circle_so.config import Config
+
+
+class TestConfig:
+    def test_defaults(self, monkeypatch):
+        monkeypatch.setenv("CIRCLE_API_TOKEN", "tok123")
+        c = Config()
+        assert c.api_token == "tok123"
+        assert c.rate_limit == 5
+        assert c.cache_ttl == 3600
+
+    def test_overrides(self):
+        c = Config(api_token="override", rate_limit=20, db_path="/tmp/test.db")
+        assert c.api_token == "override"
+        assert c.rate_limit == 20
+        assert c.db_path == "/tmp/test.db"
+
+    def test_env_vars(self, monkeypatch):
+        monkeypatch.setenv("CIRCLE_API_TOKEN", "env_tok")
+        monkeypatch.setenv("CIRCLE_SO_RATE_LIMIT", "15")
+        monkeypatch.setenv("CIRCLE_SO_CACHE_TTL", "7200")
+        c = Config()
+        assert c.api_token == "env_tok"
+        assert c.rate_limit == 15
+        assert c.cache_ttl == 7200

circle_so_cli-0.1.0/tests/test_db.py

@@ -0,0 +1,33 @@
+"""Tests for DB connection and migrations."""
+import sqlite3
+from circle_so.db.connection import get_connection, MIGRATIONS
+
+
+class TestMigrations:
+    def test_creates_tables(self, tmp_path):
+        db_path = str(tmp_path / "test.db")
+        conn = get_connection(db_path)
+        tables = [r[0] for r in conn.execute("SELECT name FROM sqlite_master WHERE type='table'").fetchall()]
+        assert "spaces" in tables
+        assert "members" in tables
+        assert "moderators" in tables
+        assert "moves" in tables
+        assert "cache" in tables
+        assert "schema_version" in tables
+        conn.close()
+
+    def test_migration_is_idempotent(self, tmp_path):
+        db_path = str(tmp_path / "test.db")
+        conn1 = get_connection(db_path)
+        conn1.close()
+        conn2 = get_connection(db_path)
+        version = conn2.execute("SELECT MAX(version) FROM schema_version").fetchone()[0]
+        assert version == len(MIGRATIONS) - 1
+        conn2.close()
+
+    def test_schema_version_tracks(self, tmp_path):
+        db_path = str(tmp_path / "test.db")
+        conn = get_connection(db_path)
+        version = conn.execute("SELECT MAX(version) FROM schema_version").fetchone()[0]
+        assert version >= 0
+        conn.close()