twentythree-skills 1.3.5 → 1.3.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "twentythree-skills",
-  "version": "1.3.5",
+  "version": "1.3.7",
   "description": "AI agent skills for the TwentyThree CLI",
   "license": "MIT",
   "author": "TwentyThree",

package/skills/reference/audience.md

@@ -22,18 +22,30 @@ Verify: `twentythree auth status --json`
 
 **Auth scope:** read  **Side effects:** none  **Output:** table (UUID, Name, Email, Company, Score, Timelines)
 
-Flags:
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--page` | no | Page number |
-| `--size` | no | Page size (max 500) |
-| `--offset` | no | Offset for pagination |
-| `--orderby` | no | Order by field (recent, timeline_count, score, first) |
-| `--order` | no | Sort direction (asc/desc) |
-| `--search` | no | Free-text search across names and emails |
-| `--identified` | no | Filter to identified profiles only |
-| `--objects` | no | Filter by viewed object IDs (space-separated) |
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--page` | no | — | Page number |
+| `--size` | no | — | Page size (max 500) |
+| `--offset` | no | — | Offset for pagination |
+| `--orderby` | no | — | Order by: `profile_count`, `recent`, `timeline_count`, `score`, `first` |
+| `--order` | no | — | Sort direction: `asc`, `desc` |
+| `--search` | no | — | Free-text search across names and emails |
+| `--identified` | no | — | Filter to identified profiles only |
+| `--objects` | no | — | Filter by viewed object IDs (space-separated) |
+| `--attended-objects` | no | — | Filter to profiles that attended specific object IDs (space-separated) |
+| `--company` | no | — | Filter by company name |
+| `--identity-sources` | no | — | Filter by the source of profile information |
+| `--score` | no | — | Filter by exact engagement score |
+| `--score-interval` | no | — | Filter by a range of engagement scores (e.g. `50:100`) |
+| `--activity-interval` | no | — | Filter to profiles with activity within this date interval (e.g. `30d`) |
+| `--first` | no | — | Filter to profiles first seen after this date |
+| `--recent` | no | — | Filter to profiles with recent activity after this date |
+| `--event-type` | no | — | Filter by conversion event type |
+| `--include-timelines` | no | — | Include viewing timelines in the result |
+| `--include-events` | no | — | Include conversion events in the result |
+| `--include-total-count` | no | — | Include the total matching profile count in the response |
+| `--export-format` | no | — | Export results as a file: `csv`, `xlsx` |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List all audience members (paginated)
@@ -41,6 +53,15 @@ twentythree audience list --json
 
 # List identified audience members ordered by engagement score
 twentythree audience list --identified --orderby score --order desc --size 100 --json
+
+# Filter to high-engagement profiles active in the last 30 days
+twentythree audience list --score-interval "50:100" --activity-interval "30d" --json
+
+# Export audience to CSV
+twentythree audience list --export-format csv > audience.csv
+
+# List profiles that attended specific webinars
+twentythree audience list --attended-objects "12345 67890" --include-timelines --json
 ```
 
 ### audience search

package/skills/reference/category.md

@@ -26,11 +26,16 @@ Category `list` does not require auth — it works before running `twentythree a
 
 **Auth scope:** anonymous  **Side effects:** none  **Output:** table (ID, Title, Hidden, Created)
 
-Flags:
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--include-hidden` | no | Include hidden categories in the results |
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--include-hidden` | no | — | Include hidden categories in the results |
+| `--search` | no | — | Search categories by title |
+| `--album-id` | no | — | Filter to categories attached to a specific album |
+| `--photo-id` | no | — | Filter to categories attached to a specific video |
+| `--user-id` | no | — | Filter to categories created by a specific user |
+| `--orderby` | no | — | Order by: `sortkey`, `title`, `editing_date`, `creation_date`, `live_create` |
+| `--order` | no | — | Sort direction: `asc`, `desc` |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List all visible categories
@@ -38,6 +43,12 @@ twentythree category list --json
 
 # Include hidden categories
 twentythree category list --include-hidden --json
+
+# Search for categories by name, ordered alphabetically
+twentythree category list --search "product" --orderby title --order asc --json
+
+# List categories for a specific album
+twentythree category list --album-id <album-id> --json
 ```
 
 ### category create

package/skills/reference/comment.md

@@ -22,25 +22,33 @@ Verify: `twentythree auth status --json`
 
 **Auth scope:** read  **Side effects:** none  **Output:** table (ID, Author, Content, Type, Date)
 
-Flags:
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--object-id` | no | Filter by object ID |
-| `--object-type` | no | Filter by object type (photo, album, live) |
-| `--comment-type` | no | Filter by comment type (comment, question, chat) |
-| `--search` | no | Search comments by content |
-| `--order` | no | Sort order for results |
-| `--include-reactions` | no | Include reactions on each comment |
-| `--include-replies` | no | Include reply-to comments |
-| `--promoted` | no | Filter to promoted comments only |
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--object-id` | no | — | Filter by object ID |
+| `--object-type` | no | — | Filter by object type: `photo`, `album` |
+| `--comment-type` | no | — | Filter by comment type: `comment`, `question`, `chat` |
+| `--search` | no | — | Search comments by content |
+| `--order` | no | — | Sort order: `asc`, `desc` |
+| `--comment-id` | no | — | Limit to a specific comment by its ID |
+| `--comment-user-id` | no | — | List comments by a specific user |
+| `--include-reactions` | no | — | Include emoji reaction counts for each comment |
+| `--include-replies` | no | — | Include details about the parent comment for reply comments |
+| `--promoted` | no | — | Filter to promoted comments only |
+| `--prioritize-promoted` | no | — | Sort promoted comments before non-promoted ones |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List all comments in the workspace
 twentythree comment list --json
 
-# List only questions on a specific webinar
-twentythree comment list --object-id <webinar-id> --object-type live --comment-type question --json
+# List only questions on a specific video
+twentythree comment list --object-id <video-id> --object-type photo --comment-type question --json
+
+# List comments by a specific user with reactions
+twentythree comment list --comment-user-id <user-id> --include-reactions --json
+
+# List promoted questions, promoted first
+twentythree comment list --comment-type question --prioritize-promoted --json
 ```
 
 ### comment add

package/skills/reference/poll.md

@@ -23,19 +23,28 @@ Verify: `twentythree auth status --json`
 
 **Auth scope:** anonymous  **Side effects:** none  **Output:** table (ID, Question, Open, Results Visible)
 
-Flags:
-
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--object-id` | yes | Object ID (webinar or live object) |
-| `--object-token` | no | Object token (auto-looked up if omitted) |
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--object-id` | yes | — | Object ID (webinar or live object) |
+| `--object-token` | no | — | Object token (auto-looked up if omitted) |
+| `--poll-id` | no | — | Limit results to a single poll by its ID |
+| `--open` | no | — | Filter by open/closed status (use `--no-open` for closed) |
+| `--public` | no | — | Filter by public/non-public status (use `--no-public` for non-public) |
+| `--display-results` | no | — | Filter to polls with publicly displayed results (use `--no-display-results` to negate) |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List all polls for a webinar
 twentythree poll list --object-id <webinar-id> --json
 
-# List polls using a specific object token
-twentythree poll list --object-id <webinar-id> --object-token <token> --json
+# List only open polls
+twentythree poll list --object-id <webinar-id> --open --json
+
+# Get a specific poll by ID
+twentythree poll list --object-id <webinar-id> --poll-id <poll-id> --json
+
+# List public polls with results displayed
+twentythree poll list --object-id <webinar-id> --public --display-results --json
 ```
 
 ### poll add

package/skills/reference/spot.md

@@ -23,17 +23,19 @@ Verify: `twentythree auth status --json`
 
 **Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Type, Active)
 
-Flags:
-
 | Flag | Required | Description |
 |------|----------|-------------|
 | `--page` | no | Page number |
 | `--size` | no | Number of results per page |
-| `--search` | no | Search term |
-| `--spot-type` | no | Filter by spot type |
-| `--active` | no | Filter by active status (boolean) |
-| `--orderby` | no | Field to order results by |
-| `--order` | no | Sort order (asc or desc) |
+| `--search` | no | Search spots by name |
+| `--spot-id` | no | Filter to a specific spot by ID |
+| `--spot-type` | no | Filter by spot type: `page` or `widget` |
+| `--spot-object-type` | no | Filter by object type the spot is configured for: `live` or `video` |
+| `--active` / `--no-active` | no | Filter by active status |
+| `--include-analytics` | no | Include impression analytics data for each spot |
+| `--orderby` | no | Sort field: `spot_name`, `creation_time`, or `title` |
+| `--order` | no | Sort direction: `asc` or `desc` |
+| `--fields` | no | Comma-separated list of fields to return |
 
 ```bash
 # List all spots in the workspace
@@ -41,6 +43,12 @@ twentythree spot list --json
 
 # List only active spots
 twentythree spot list --active --json
+
+# List page-type spots sorted by creation time
+twentythree spot list --spot-type page --orderby creation_time --order desc --json
+
+# List webinar spots with analytics
+twentythree spot list --spot-object-type live --include-analytics --json
 ```
 
 ### spot create

package/skills/reference/user.md

@@ -26,14 +26,21 @@ Run `twentythree auth status --json` to confirm the current workspace's bearer t
 
 **Auth scope:** admin  **Side effects:** none  **Output:** table (ID, Username, Display Name, URL)
 
-Flags:
-
 | Flag | Required | Description |
 |------|----------|-------------|
 | `--page` | no | Page number |
 | `--size` | no | Number of results per page |
 | `--search` | no | Search query (username, display name, or email) |
 | `--user-id` | no | Filter by user ID |
+| `--user-group-id` | no | Filter to users assigned to a specific user group |
+| `--only-admins` | no | Return only admin users |
+| `--only-owner` | no | Return only the workspace owner |
+| `--seated` / `--no-seated` | no | Filter by seated status |
+| `--include-disabled-login` | no | Include users with disabled login |
+| `--include-metrics` | no | Include per-user performance metrics |
+| `--orderby` | no | Field to order results by |
+| `--order` | no | Sort direction: `asc` or `desc` |
+| `--fields` | no | Comma-separated list of fields to return |
 
 ```bash
 # List all users in the workspace
@@ -41,6 +48,12 @@ twentythree user list --json
 
 # Search for a user by name or email
 twentythree user list --search "alice" --json
+
+# List only admin users
+twentythree user list --only-admins --json
+
+# List users in a specific group, sorted
+twentythree user list --user-group-id 5 --orderby display_name --order asc --json
 ```
 
 ### user create

package/skills/reference/video.md

@@ -58,7 +58,29 @@ twentythree video upload ./video.mp4 --title "Q2 Keynote" --category-id <cat-id>
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--limit` | no | — | Maximum number of videos to return (default: all) |
+| `--search` | no | — | Search by title, description, or tags |
+| `--album-id` | no | — | Filter to videos in one or more categories (comma-separated IDs) |
+| `--user-id` | no | — | Filter by uploader (`me` for authenticated user) |
+| `--photo-id` | no | — | Limit results to a single video by its ID |
+| `--live-id` | no | — | Filter to videos associated with a specific webinar |
+| `--tag` | no | — | Filter to videos with a specific tag |
+| `--tags` | no | — | Space-separated list of tags to filter by |
+| `--tag-mode` | no | — | How to combine tag filters: `and` or `or` |
+| `--order-by` | no | — | Sort field: `uploaded`, `published`, `created`, `creation`, `taken`, `title`, `views`, `comments`, `rating`, `numratings`, `video_length`, `words`, `related`, `posted`, `rank`, `default-published` |
+| `--order` | no | — | Sort direction: `asc` or `desc` |
+| `--before-time` | no | — | Filter to videos uploaded before this timestamp (ISO 8601) |
+| `--after-time` | no | — | Filter to videos uploaded after this timestamp (ISO 8601) |
+| `--year` | no | — | Filter to videos from a specific year |
+| `--month` | no | — | Filter to videos from a specific month (1–12, requires `--year`) |
+| `--day` | no | — | Filter to videos from a specific day (1–31, requires `--year` and `--month`) |
+| `--published` / `--no-published` | no | — | Filter by published status |
+| `--promoted` / `--no-promoted` | no | — | Filter by promoted status |
+| `--unalbummed` | no | — | Filter to videos not assigned to any category |
 | `--include-unpublished` | no | — | Include unpublished videos in results |
+| `--include-stats` | no | — | Include per-video performance statistics (view count, play rate, engagement) |
+| `--include-sections-count` | no | — | Include the number of chapters for each video |
+| `--include-user-group` | no | — | Include the user group assignment for each video |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List all published videos
@@ -66,6 +88,24 @@ twentythree video list --json
 
 # List up to 20 videos including unpublished
 twentythree video list --limit 20 --include-unpublished --json
+
+# Search for videos by keyword, sorted by most viewed
+twentythree video list --search "intro" --order-by views --order desc --json
+
+# Filter to videos in a category
+twentythree video list --album-id 42 --json
+
+# Filter to videos uploaded by the authenticated user
+twentythree video list --user-id me --limit 10 --json
+
+# Filter by date range
+twentythree video list --after-time 2024-01-01T00:00:00Z --before-time 2024-12-31T23:59:59Z --json
+
+# List with stats included
+twentythree video list --include-stats --include-sections-count --json
+
+# Return only specific fields
+twentythree video list --fields photo_id,title,views --json
 ```
 
 ---
@@ -346,6 +386,11 @@ Subtitle commands manage caption tracks on a video (SRT/WebVTT formats). Use `tw
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--include-drafts` | no | — | Include draft (unpublished) subtitle tracks |
+| `--subtitle-format` | no | — | Format for subtitle download URLs: `websrt`, `json`, `adobe`, `subviewer`, `webvtt` |
+| `--type` | no | — | Filter by subtitle type: `general`, `closedcaptions`, `audiodescriptions` |
+| `--stripped` | no | — | Return a stripped (timing-only) version of the subtitle file |
+| `--detect-language` | no | — | Use the viewer's browser language to determine the default subtitle |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List published subtitle tracks for a video
@@ -353,6 +398,12 @@ twentythree video subtitle list <id> --json
 
 # List all tracks including drafts
 twentythree video subtitle list <id> --include-drafts --json
+
+# List closed-captions tracks with WebVTT download URLs
+twentythree video subtitle list <id> --type closedcaptions --subtitle-format webvtt --json
+
+# List all tracks including drafts, return specific fields
+twentythree video subtitle list <id> --include-drafts --fields "locale,type,status" --json
 ```
 
 ---

package/skills/reference/webinar.md

@@ -61,16 +61,41 @@ twentythree webinar create --title "Product Launch" --live-date "2026-05-15T16:0
 |------|----------|---------|-------------|
 | `--limit` | no | 20 | Maximum number of webinars to return |
 | `--all` | no | false | Fetch all webinars across all pages (overrides --limit) |
-| `--include-private` | no | false | Include private webinars in results |
-| `--status` | no | — | Filter by status: `upcoming`, `live`, or `previous` |
 | `--search` | no | — | Search webinars by keyword |
+| `--status` | no | — | Filter by status: `upcoming`, `live`, or `previous` |
+| `--include-private` | no | false | Include private webinars in results |
+| `--live-id` | no | — | Limit to a single webinar by ID |
+| `--album-id` | no | — | Filter to webinars in a specific category |
+| `--user-id` | no | — | Filter by creator (`me` for authenticated user) |
+| `--live-format` | no | — | Filter by format: `event` or `webinar` |
+| `--live-series-id` | no | — | Filter to webinars in a specific series |
+| `--ordering` | no | — | Sort field: `private`, `promoted`, `streaming`, `broadcasting`, `name`, `live_label`, `live_status`, `live_date`, `creation_date` |
+| `--order` | no | — | Sort direction: `asc` or `desc` |
+| `--promoted` / `--no-promoted` | no | — | Filter by promoted status |
+| `--draft` / `--no-draft` | no | — | Filter by draft status |
+| `--cancelled` / `--no-cancelled` | no | — | Filter by cancelled status |
+| `--streaming` | no | — | Filter to currently streaming webinars only |
+| `--template` | no | — | Filter to webinar templates only |
+| `--include-stats` | no | — | Include performance statistics for each webinar |
+| `--include-speakers` | no | — | Include speaker information for each webinar |
+| `--include-albums` | no | — | Include category information for each webinar |
+| `--fields` | no | — | Comma-separated list of fields to return |
 
 ```bash
 # List upcoming webinars
 twentythree webinar list --status upcoming --json
 
+# List all webinars sorted by date ascending
+twentythree webinar list --all --ordering live_date --order asc --json
+
 # Search for a webinar by title and include private
 twentythree webinar list --search "Q2 Town Hall" --include-private --json
+
+# List webinars in a series with speakers included
+twentythree webinar list --live-series-id 42 --include-speakers --json
+
+# List webinars by the authenticated user
+twentythree webinar list --user-id me --live-format webinar --json
 ```
 
 ---
@@ -259,13 +284,23 @@ Speakers are presenters attached to a webinar. Commands cover list, add, update,
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--token` | no | — | Webinar token (auto-looked up if omitted) |
+| `--speaker-id` | no | — | Filter to a specific speaker by ID |
+| `--request-status` | no | — | Filter by request status: `requested`, `approved`, `denied`, `expired` |
+| `--creation-source` | no | — | Filter by creation source: `admin`, `guest` |
+| `--exclude-hidden` | no | — | Exclude hidden speakers from the results |
+| `--include-unapproved` | no | — | Include unapproved speakers |
+| `--include-hidden-guests` | no | — | Include hidden guest speakers |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List speakers for a webinar
 twentythree webinar speaker list <id> --json
 
-# Example with a real ID
-twentythree webinar speaker list 12345 --json
+# List only approved speakers
+twentythree webinar speaker list <id> --request-status approved --json
+
+# List admin-created speakers, excluding hidden ones
+twentythree webinar speaker list <id> --creation-source admin --exclude-hidden --json
 ```
 
 ---
@@ -276,15 +311,20 @@ twentythree webinar speaker list 12345 --json
 
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
-| `--name` | no | — | Speaker name |
-| `--email` | no | — | Speaker email |
+| `--name` | yes | — | Speaker name |
+| `--email` | no | — | Speaker email (required for WebRTC speakers) |
 | `--title` | no | — | Speaker title or job title |
 | `--description` | no | — | Speaker bio or description |
+| `--connection-type` | no | `webrtc` | Speaker connection type: `webrtc`, `gearmode`, `rtmp`, `whip`, `srt`, `url` |
+| `--connection-type-pull-url` | no | — | Pull URL for connection types that support stream pull (`whip`, `url`) |
 
 ```bash
-# Add a speaker with name and email
+# Add a WebRTC speaker (email required for webrtc)
 twentythree webinar speaker add <id> --name "Jane Doe" --email jane@example.com --json
 
+# Add an RTMP speaker (no email required)
+twentythree webinar speaker add <id> --name "John Smith" --connection-type rtmp --json
+
 # Add a speaker with full details
 twentythree webinar speaker add <id> --name "John Smith" --email john@example.com --title "CTO" --description "Engineering lead" --json
 ```
@@ -341,11 +381,16 @@ twentythree webinar speaker add-from-user <id> --user-id <user-id> --json
 | `--email` | no | — | Speaker email |
 | `--title` | no | — | Speaker title or job title |
 | `--description` | no | — | Speaker bio or description |
+| `--connection-type` | no | — | Speaker connection type: `webrtc`, `gearmode`, `rtmp`, `whip`, `srt`, `url` |
+| `--connection-type-pull-url` | no | — | Pull URL for connection types that support stream pull (`whip`, `url`) |
 
 ```bash
 # Update a speaker's title and email
 twentythree webinar speaker update <id> <speaker-id> --title "CEO" --email ceo@example.com --json
 
+# Change a speaker's connection type to RTMP
+twentythree webinar speaker update <id> <speaker-id> --connection-type rtmp --json
+
 # Update speaker bio
 twentythree webinar speaker update <id> <speaker-id> --description "Updated bio" --json
 ```
@@ -512,14 +557,40 @@ A series groups multiple webinars together (e.g. a recurring show). Commands cov
 
 **Auth scope:** read  **Side effects:** none  **Output:** table (ID, Name, Status, Created)
 
-No additional flags.
+| Flag | Required | Default | Description |
+|------|----------|---------|-------------|
+| `--page` | no | — | Page number |
+| `--size` | no | — | Page size |
+| `--all` | no | — | Fetch all pages automatically |
+| `--search` | no | — | Search series by name |
+| `--live-series-id` | no | — | Filter to a specific series by ID |
+| `--live-id` | no | — | Filter to series containing a specific webinar ID |
+| `--album-id` | no | — | Filter by album ID |
+| `--user-id` | no | — | Filter by user ID |
+| `--series-type` | no | — | Filter by type: `liveevent`, `series` |
+| `--ordering` | no | — | Order by: `name`, `private`, `live_status`, `live_date`, `creation_date`, `updated_date` |
+| `--order` | no | — | Sort direction: `asc`, `desc` |
+| `--cancelled` | no | — | Include cancelled series (allowNo) |
+| `--draft` | no | — | Include draft series (allowNo) |
+| `--private` | no | — | Include private series (allowNo) |
+| `--include-private` | no | — | Include private series in results |
+| `--include-speakers` | no | — | Include speaker data in response |
+| `--include-stats` | no | — | Include statistics in response |
+| `--include-albums` | no | — | Include album data in response |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List all webinar series
 twentythree webinar series list --json
 
-# Use the ID to reference a series in other commands
-twentythree webinar series list --json
+# List series ordered by creation date descending
+twentythree webinar series list --ordering creation_date --order desc --json
+
+# List all live event series including speakers
+twentythree webinar series list --series-type liveevent --include-speakers --json
+
+# Fetch all pages of series
+twentythree webinar series list --all --json
 ```
 
 ---
@@ -737,6 +808,9 @@ Mail templates and scheduled emails associated with a webinar (invitations, remi
 | Flag | Required | Default | Description |
 |------|----------|---------|-------------|
 | `--series-id` | no | — | Series ID — list mails for a series instead of a webinar |
+| `--mail-id` | no | — | Return a specific mail by its ID |
+| `--include-metrics` | no | — | Include metrics on mail performance in the response |
+| `--fields` | no | — | Comma-separated list of fields to return in the API response |
 
 ```bash
 # List emails for a webinar
@@ -744,6 +818,9 @@ twentythree webinar mail list <id> --json
 
 # List emails for a series
 twentythree webinar mail list --series-id <series-id> --json
+
+# Get a specific mail with performance metrics
+twentythree webinar mail list <id> --mail-id <mail-id> --include-metrics --json
 ```
 
 ---