---
name: pp-circle
description: "Run a Circle community from the terminal: spaces as files, courses as files, seat counts, and an offline mirror. Trigger phrases: `did enough people pay for the circle course`, `how many founding seats are left on circle`, `push the course to circle`, `pull the circle course into files`, `apply this spaces file to circle`, `what needs me in the circle community`, `onboard these people to circle`, `schedule the next show and tell`, `draft the show and tell recap`, `use circle`, `run circle-pp-cli`."
author: "Cathryn Lavery"
license: "Apache-2.0"
argument-hint: "<command> [args] | install cli|mcp"
allowed-tools: "Read Bash"
metadata:
  openclaw:
    requires:
      bins:
        - circle-pp-cli
---
<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/social-and-messaging/circle/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

# Circle — Printing Press CLI

## Prerequisites: Install the CLI

This skill drives the `circle-pp-cli` binary. **You must verify the CLI is installed before invoking any command from this skill.** If it is missing, install it first:

1. Install via the Printing Press installer. It defaults binaries to `$HOME/.local/bin` on macOS/Linux and `%LOCALAPPDATA%\Programs\PrintingPress\bin` on Windows:
   ```bash
   npx -y @mvanhorn/printing-press-library install circle --cli-only
   ```
2. Verify: `circle-pp-cli --version`
3. Ensure the reported install directory is on `$PATH` for the agent/runtime that will invoke this skill.

If the `npx` install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.10 or newer). This installs into `$GOPATH/bin` (default `$HOME/go/bin`), so add that directory to `$PATH` instead:

```bash
go install github.com/mvanhorn/printing-press-library/library/social-and-messaging/circle/cmd/circle-pp-cli@latest
```

If `--version` reports "command not found" after install, the runtime cannot see the binary directory on `$PATH`. Do not proceed with skill commands until verification succeeds.

Every Circle Admin API V2 endpoint, plus commands built for operators who run a paid community and a course on Circle. Declare spaces in a file and apply only the diff, keep a course as markdown folders, count founding seats, onboard members without invite emails, and triage what needs you from a local SQLite mirror.

## When to Use This CLI

Use this CLI when an agent needs to set up or run a Circle community through the Admin API: create or update spaces from a file, push a course from markdown, onboard members, count paid seats, schedule recurring events, or triage new activity. It suits scripted and agent use where every write should be previewed first.

## Anti-triggers

Do not use this CLI for:
- Creating a paywall, price, or coupon: the Admin API has no create endpoint, use the Circle admin UI
- Reading lesson completion or progress: the API only writes progress
- Member-facing features in your own app: use Circle's Headless Member API
- Sending DMs or announcement emails without a person approving them

## Unique Capabilities

### Live sessions and triage
- **`inbox`** — See new members, unreplied posts, flagged content, form submissions, failed charges and cancellations since a time, read from the local mirror.

  _Run sync first: inbox reads only the local mirror, and an empty or missing mirror returns empty sections with exit 0, not an all-clear._

  ```bash
  circle-pp-cli inbox --since 24h --agent
  ```
- **`show-tell schedule`** — Create the next Show & Tell events on a cadence by duplicating a template event.

  _Prints the series plan by default; --yes creates the occurrences as quiet drafts and records them so reruns skip dates already scheduled._

  ```bash
  circle-pp-cli show-tell schedule --template 123 --every 2w --until 2027-01-17
  ```
- **`show-tell recap`** — Pull a past session's RSVPed attendees and its live-room transcript into a markdown recap draft.

  _A transcript needs a live-room recording near the event time; otherwise the recap says none was found (transcript_found false). --post --yes saves it as a draft post._

  ```bash
  circle-pp-cli show-tell recap 123 --agent
  ```

### Community structure as files
- **`spaces apply`** — Make Circle's space groups and spaces match a YAML file, with a plan printed before any write.

  _Use this to set up or change community structure repeatably; rerunning an applied file is a no-op._

  ```bash
  circle-pp-cli spaces apply ./spaces.yaml --agent
  ```
- **`course push`** — Upload a course kept as module folders and markdown lessons to a Circle course space, new lessons as drafts.

  _Prints the plan by default; add --yes to push. New lessons land as drafts, and lesson order is tracked in course.yaml because Circle's API does not expose it._

  ```bash
  circle-pp-cli course push ./course --space 1000969 --agent
  ```
- **`course pull`** — Download a Circle course space into module folders with one file per lesson; lesson bodies stay as Circle's HTML and media is not downloaded.

  _Use this to back up a course or hand it to an agent to edit as files; files are numbered in creation order because Circle's API does not expose lesson order._

  ```bash
  circle-pp-cli course pull ./course --space 1000969 --agent
  ```

### Seats and members
- **`seats`** — Count paying members against a seat cap and list who paid.

  _Use this to see how many founding seats are left; active, trialing and past-due subscriptions plus paid charges count as paid._

  ```bash
  circle-pp-cli seats --cap 30 --agent
  ```
- **`onboard`** — Add people to the community, their spaces, space groups and access groups, and tag them, without sending invite emails by default.

  _Prints the plan by default; --yes applies it. No invite email goes out unless you add --send together with --yes._

  ```bash
  circle-pp-cli onboard ada@example.com --tag founding
  ```
- **`founding`** — Answer whether at least N people paid with GO or NO-GO and the count.

  _Use this for the launch decision. Exit 8 means NO-GO; exit 2 means a usage error. Trialing and past-due subscriptions count as paid._

  ```bash
  circle-pp-cli founding --go-no-go 10 --agent
  ```

## Command Reference

**access-groups** — Manage access groups

- `circle-pp-cli access-groups create` — Creates an active access group in the community with a name and an optional description.
- `circle-pp-cli access-groups delete` — Archives an access group; the record is kept and can be restored by unarchiving it.
- `circle-pp-cli access-groups list` — Lists the community's access groups as a paginated list.
- `circle-pp-cli access-groups update` — Updates the name and/or description of an access group.

**advanced-search** — Manage advanced search

- `circle-pp-cli advanced-search` — Searches the community by keyword across members, spaces, posts, comments, lessons and events.

**chat-preferences** — Manage chat preferences

- `circle-pp-cli chat-preferences` — Updates the community's chat settings for messaging, group messaging, voice messages and member-to-member messaging.

**chat-room-message-imports** — Manage chat room message imports

- `circle-pp-cli chat-room-message-imports` — Imports a historical message into a chat space on behalf of the specified user.

**comments** — Manage comments

- `circle-pp-cli comments create` — Creates a comment on a post, or a reply when parent_comment_id is given.
- `circle-pp-cli comments delete` — Permanently deletes a comment by ID. Replies to the comment are deleted with it.
- `circle-pp-cli comments get` — Returns a single comment by ID, including its replies, author, post and space.
- `circle-pp-cli comments list` — Lists comments in the community, newest first, optionally filtered by post or space. Results are paginated.

**community** — Manage community

- `circle-pp-cli community list` — Gets the community the API token belongs to, including its general, access, landing page
- `circle-pp-cli community update` — Updates the community the API token belongs to.

**community-leads** — Manage community leads

- `circle-pp-cli community-leads create` — Creates a non-member contact (also called a lead) in the community from an email address.
- `circle-pp-cli community-leads delete` — Deletes a non-member contact (also called a lead) from the community's audience.

**community-member-charges** — Manage community member charges

- `circle-pp-cli community-member-charges export` — Creates a background task that exports community member charges matching the given filters to a CSV
- `circle-pp-cli community-member-charges list` — Searches community member charges for a community

**community-member-spaces** — Manage community member spaces

- `circle-pp-cli community-member-spaces` — Lists the spaces a community member belongs to, as a paginated list.

**community-member-subscriptions** — Manage community member subscriptions

- `circle-pp-cli community-member-subscriptions export` — Creates a background task that exports community member subscriptions matching the given filters to a CSV
- `circle-pp-cli community-member-subscriptions list` — Searches community member subscriptions for a community

**community-members** — Manage community members

- `circle-pp-cli community-members create` — Creates a community member with the given email.
- `circle-pp-cli community-members delete` — Removes a member from the community by deactivating (soft-deleting)
- `circle-pp-cli community-members get` — Gets a single community member by ID.
- `circle-pp-cli community-members list` — Lists the community's members as a paginated list.
- `circle-pp-cli community-members list-communitymembers` — Finds a single community member by exact email address, including invited members who have not completed profile setup.
- `circle-pp-cli community-members update` — Updates a community member's profile, avatar, profile fields, moderation flag and preferences

**community-reviews** — Manage community reviews

- `circle-pp-cli community-reviews get` — Retrieves a single community review by id.
- `circle-pp-cli community-reviews list` — Lists the community's reviews, newest first by default.
- `circle-pp-cli community-reviews list-communityreviews` — Returns the community's precomputed review totals: review count, average rating, and the rating distribution.

**community-segments** — Manage community segments

- `circle-pp-cli community-segments create` — Creates a community segment
- `circle-pp-cli community-segments delete` — Permanently deletes a community segment.
- `circle-pp-cli community-segments list` — Lists the segments shown on the community's Segments page, newest first
- `circle-pp-cli community-segments update` — Updates an existing community segment

**contacts** — Manage contacts


**course-lesson-progress** — Manage course lesson progress

- `circle-pp-cli course-lesson-progress` — Marks a course lesson as completed or incomplete for a member of the lesson's course space, identified by email.

**course-lessons** — Manage course lessons

- `circle-pp-cli course-lessons create` — Creates a lesson in a course section. section_id is required.
- `circle-pp-cli course-lessons delete` — Permanently deletes a course lesson, including members' completion records for it.
- `circle-pp-cli course-lessons get` — Gets a single lesson from one of the community's course spaces by ID.
- `circle-pp-cli course-lessons list` — Lists lessons across the community's course spaces as a paginated list, oldest first by default.
- `circle-pp-cli course-lessons reorder` — Reorders a course's sections and lessons, and moves lessons between sections.
- `circle-pp-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-pp-cli course-sections create` — Creates a section in a course space. The section is added at the end of the course and starts with no lessons.
- `circle-pp-cli course-sections delete` — Permanently deletes a course section together with all of its lessons, and removes it from the course's section order.
- `circle-pp-cli course-sections get` — Gets a single section from one of the community's course spaces by ID.
- `circle-pp-cli course-sections list` — Lists sections across the community's course spaces as a paginated list, oldest first by default.
- `circle-pp-cli course-sections update` — Renames a course section.

**direct-uploads** — Manage direct uploads

- `circle-pp-cli direct-uploads` — Creates a presigned URL for file upload. Upload the file via PUT to the returned direct_upload.

**embeds** — Manage embeds

- `circle-pp-cli embeds create` — Creates an embed from a URL and returns the embed data with an sgid
- `circle-pp-cli embeds get` — Retrieves an embed by its sgid

**event-attendees** — Manage event attendees

- `circle-pp-cli event-attendees create` — Invites a community member, identified by email, to an event and adds them to the event's space if needed.
- `circle-pp-cli event-attendees delete` — Removes a member's RSVP from an event by setting their RSVP status to no.
- `circle-pp-cli event-attendees list` — Lists the confirmed attendees of an event (members who RSVPed yes), with each member's name, email and RSVP status.

**events** — Manage events

- `circle-pp-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-pp-cli events delete` — Permanently deletes an event by ID, along with its attendees and comments.
- `circle-pp-cli events get` — Gets an event by ID, including its schedule, location, RSVP and notification settings, and its space.
- `circle-pp-cli events list` — Lists published events in the community, newest first by default.
- `circle-pp-cli events update` — Updates an event by ID. The top-level space_id must be the space the event currently belongs to.

**filter-kit-configuration** — Manage filter kit configuration

- `circle-pp-cli filter-kit-configuration` — Returns the resolved runtime filter configuration members currently see, including defaults and saved customizations.

**filter-kit-controls** — Manage filter kit controls

- `circle-pp-cli filter-kit-controls create` — Creates one saved filter customisation for the member directory or a member space.
- `circle-pp-cli filter-kit-controls delete` — Deletes one member filter kit control
- `circle-pp-cli filter-kit-controls get` — Retrieves a single member directory or member space filter customisation by ID.
- `circle-pp-cli filter-kit-controls list` — Lists a community's saved filter customisations, including whether each filter is enabled and the member directory
- `circle-pp-cli filter-kit-controls update` — Updates an existing member directory or member space filter customisation.

**flagged-contents** — Manage flagged contents

- `circle-pp-cli flagged-contents create` — Reports a post, comment, connection or chat message for moderation as the API token's user
- `circle-pp-cli flagged-contents list` — Lists moderation reports for content in the community, most recently updated first

**forms** — Manage forms

- `circle-pp-cli forms delete` — Permanently deletes a form along with its elements and submissions.
- `circle-pp-cli forms get` — Returns a form by ID with its settings, styles, submission count and element tree.
- `circle-pp-cli forms list` — Lists the community's forms, newest first, optionally filtered by a case-insensitive partial match on name.
- `circle-pp-cli forms update` — Updates a form's settings and styles, and its elements when a non-empty elements list is sent.

**gamification** — Manage gamification

- `circle-pp-cli gamification` — Returns the community's gamification leaderboard: up to 10 active members ranked by points

**invitation-links** — Manage invitation links

- `circle-pp-cli invitation-links create` — Creates an active invitation link.
- `circle-pp-cli invitation-links delete` — Delete an invitation link by setting its status to deleted
- `circle-pp-cli invitation-links list` — Lists the community's invitation links, newest first
- `circle-pp-cli invitation-links update` — Updates an invitation link.

**live** — Manage live

- `circle-pp-cli live get` — Returns the raw VTT transcripts for a given live room.
- `circle-pp-cli live list` — Returns a paginated list of live rooms for the community.

**locations** — Manage locations

- `circle-pp-cli locations` — Resolves a free-text location query into geocoded candidates via Mapbox.

**member-tags** — Manage member tags

- `circle-pp-cli member-tags create` — Creates a member tag in the community. Tags are labels admins apply to members to organize and segment them.
- `circle-pp-cli member-tags delete` — Permanently deletes a member tag and removes it from every member who has it.
- `circle-pp-cli member-tags get` — Gets a single member tag by ID, including its appearance and display settings.
- `circle-pp-cli member-tags list` — Lists the community's member tags as a paginated list, oldest first by default.
- `circle-pp-cli member-tags update` — Updates the name, appearance or visibility of a member tag. Only the fields provided are changed.

**messages** — Manage messages

- `circle-pp-cli messages` — Sends a chat message from the authenticated community member.

**page-profile-fields** — Manage page profile fields

- `circle-pp-cli page-profile-fields` — Get Page Profile Fields

**payment-method-setting** — Manage payment method setting

- `circle-pp-cli payment-method-setting` — Returns the enabled/disabled state and Stripe capability status for every supported payment method (Apple Pay

**paywall-affiliate-payouts** — Manage paywall affiliate payouts

- `circle-pp-cli paywall-affiliate-payouts export-payouts` — Creates a background task that exports processing affiliate payouts to a CSV
- `circle-pp-cli paywall-affiliate-payouts mark-paid` — Moves processing affiliate payouts to paid, optionally scoped to specific community members
- `circle-pp-cli paywall-affiliate-payouts start` — Moves due affiliate payouts to processing, optionally scoped to specific community members

**paywall-affiliates** — Manage paywall affiliates

- `circle-pp-cli paywall-affiliates create` — Invites existing community members to the affiliate program
- `circle-pp-cli paywall-affiliates list` — Searches affiliates for a community
- `circle-pp-cli paywall-affiliates update` — Updates an affiliate's status

**paywall-coupons** — Manage paywall coupons

- `circle-pp-cli paywall-coupons <id>` — Deletes a paywall coupon. Removes any Stripe-side coupon and invalidates offers that reference it.

**paywall-groups** — Manage paywall groups

- `circle-pp-cli paywall-groups create` — Creates a new subscription group (paywall group) for the community.
- `circle-pp-cli paywall-groups update` — Updates a subscription group's name. The currency can only be changed while the group has no paywalls attached to it.

**paywalls** — Manage paywalls

- `circle-pp-cli paywalls delete` — Permanently deletes a paywall. Fails if the paywall has real transactions -- archive it instead.
- `circle-pp-cli paywalls list` — Search a community's paywalls and their prices. Only authorized community admins may search.

**posts** — Manage posts

- `circle-pp-cli posts create` — Creates a basic post in a basic-type space. Use tiptap_body instead of body_html for rich text content.
- `circle-pp-cli posts delete` — Removes a basic post by ID from its space and unpins it if it was the pinned post.
- `circle-pp-cli posts get` — Returns a single basic post by ID, including its content, status, settings and engagement counts.
- `circle-pp-cli posts list` — Lists basic