ContentStudio

SKILL.md

---
name: contentstudio
description: ContentStudio is a tool to schedule social-media posts, manage the social inbox, and pull performance analytics across Facebook, LinkedIn, Twitter/X, Instagram, YouTube, TikTok, Pinterest, Threads, Tumblr, Bluesky, and Google Business Profile. Use when the user wants to list/create/delete/approve posts, find the best time to post, generate or edit images with AI, read and reply to DMs, comments and reviews, manage media, audit workspaces, accounts, campaigns, labels, categories, or team-members, or pull analytics reports (top posts, engagement, impressions, follower growth, AI insights, etc.) on their ContentStudio account.
version: 1.5.0
homepage: https://api.contentstudio.io/guide
metadata: {"openclaw":{"emoji":"📅","requires":{"bins":["contentstudio"],"env":["CONTENTSTUDIO_API_KEY"]}}}
---

## Install ContentStudio CLI if it doesn't exist

```bash
npm install -g contentstudio-cli
# or
pnpm install -g contentstudio-cli
```

npm release: https://www.npmjs.com/package/contentstudio-cli
contentstudio-agent github: https://github.com/contentstudioio/contentstudio-agent
contentstudio API docs: https://api.contentstudio.io/api-docs
official website: https://contentstudio.io

---

| Property | Value |
|----------|-------|
| **name** | contentstudio |
| **description** | Social-media automation CLI for scheduling posts and managing media/accounts via the ContentStudio public API |
| **allowed-tools** | Bash(contentstudio:*) |

---

## ⚠️ Authentication Required

**You MUST authenticate before running any contentstudio CLI command.** All commands will fail without a valid API key.

Before doing anything else, check auth status:

```bash
contentstudio auth:status
```

If `has_api_key` is `false`, authenticate one of two ways. The user can generate a key from **ContentStudio Dashboard → Settings → API Keys**.

1. **API key (interactive)** — stores the key in the CLI config file:

```bash
contentstudio auth:login --api-key cs_...
```

2. **Environment variable (headless / agent runtimes)** — the CLI reads `CONTENTSTUDIO_API_KEY` from the environment and it takes precedence over the config file:

```bash
export CONTENTSTUDIO_API_KEY=cs_...
```

> **Headless deployment note (OpenClaw, CI, daemons):** a shell `export` does **not** persist to a service process. Set `CONTENTSTUDIO_API_KEY` in the agent's actual environment — e.g. systemd `Environment=` (`systemctl edit`), an `EnvironmentFile=`, or Docker `-e` / compose `environment:` — then restart the service. Runtimes that gate on declared requirements (e.g. OpenClaw's `requires.env`) will stay blocked until this variable is present in the process environment.

Then verify a workspace is selected:

```bash
contentstudio --json workspaces:current
```

If `active_workspace_id` is `null`, list workspaces and ask the user to pick one:

```bash
contentstudio --json workspaces:list
contentstudio workspaces:use <workspace_id>
```

---

## Invocation rules for agents

- **Always pass `--json` before the subcommand** for stable, parseable output.
- **Envelope shape**:
  - Success: `{"ok": true, "data": <payload>, "pagination"?: {...}}`
  - Error:   `{"ok": false, "error": {"type": "<ErrorType>", "message": "...", "http_status": <int>, "hint": "..."}}`
- **Exit codes** are non-zero on error. Check both `returncode` and `ok`.
- **Parse stdout only** — human messages go to stderr.
- **Before any mutating action (posts/comments/media), run it with `--dry-run`** first to verify the payload is correct. `--dry-run` never touches the API.

### Confirm the target workspace before mutating actions

The CLI silently defaults to the active workspace (whatever was set by `workspaces:use`). That default is fine for **read-only** calls (`workspaces:list`, `accounts:list`, `posts:list`, `media:list`, etc.) — just use the active workspace.

But for any **mutating** action — `accounts:connect`, `accounts:add-bluesky`, `accounts:add-facebook-group`, `accounts:remove`, `posts:create`, `posts:update`, `posts:delete`, `posts:approve`, `posts:reject`, `comments:add`, `media:upload`, `workspaces:update`, `workspaces:delete`, `labels:create`, `labels:update`, `labels:delete`, `campaigns:create`, `campaigns:update`, `campaigns:delete`, `team:add`, `team:update`, `team:remove`, and every `inbox:*` write (`inbox:send`, `inbox:comment-add`, `inbox:comment-delete`, `inbox:review-reply`, `inbox:update`, `inbox:tag-*`, …) — you MUST confirm the workspace with the user first, even if a workspace is already active. Don't assume the active workspace is the one they want to mutate.

> **Inbox writes are customer-facing.** `inbox:send`, `inbox:comment-add`, and `inbox:review-reply` publish text to a real person on a real social platform, and there is no undo on the provider side. Always `--dry-run` first, show the exact message text to the user, and get explicit approval before sending. Never compose-and-send a reply to a customer in one step.

(`workspaces:create` is the one write that is **not** workspace-scoped — it creates a brand-new workspace and ignores the active one.)

Pattern:

1. Run `contentstudio --json workspaces:current` to see what's active.
2. Tell the user: "Your active workspace is **`<name>`** (`<id>`). Do you want to connect/post/delete in this workspace, or a different one?"
3. If they say a different one, run `workspaces:list`, let them pick, then either:
   - Run `workspaces:use <id>` to switch the default, or
   - Pass `--workspace <id>` on the single mutating call (preferred when it's a one-off — does not change the active workspace).
4. Only then run the mutating command.

This is mandatory even when the user's request seems to imply the active workspace ("connect a Facebook page", "create a draft post") — they may have just switched contexts in their head and forgotten which workspace is active in the CLI.

## Pagination — be proactive, don't silently truncate

**All list commands return a `pagination` block** in JSON mode when more results exist than fit on one page:

```json
{
  "ok": true,
  "data": [ /* current page of items */ ],
  "pagination": {
    "current_page": 1,
    "per_page": 10,
    "total": 48,
    "last_page": 5,
    "from": 1,
    "to": 10,
    "has_more": true
  }
}
```

**Mandatory rule**: Whenever `pagination.has_more === true`, the user has more data than what was returned. **You MUST NOT silently treat the current page as "all results"**. Pick one of these three strategies:

1. **Ask the user** (default for ambiguous requests):
   > "I retrieved 10 of your 48 workspaces. Do you want me to fetch the rest, or is the first 10 enough for what you're doing?"

2. **Auto-paginate** — if the user's request implies they want everything (e.g. "list ALL my accounts", "show every draft post", "delete all queued posts"):
   - Call again with `--per-page <total>` to get everything in one round-trip:
     ```bash
     contentstudio --json workspaces:list --per-page 48
     ```
   - Or iterate `--page 2`, `--page 3`, … `--page <last_page>` if `total` is large (>200) and you want bounded pages.

3. **Filter, don't paginate** — if the user asked for something specific (e.g. "Facebook accounts only"), use the relevant filter flag (`--platform facebook`, `--search "..."`, `--status draft`) instead of paginating. Smaller result set = no pagination needed.

### Quick decision tree for the agent

```
Did the user say "all" / "every" / "complete list" / "every single"?
  → YES: auto-paginate using --per-page <pagination.total>
  → NO:
      Did the user give a specific count? ("show me top 5", "first 20 posts")
        → YES: respect that count; use --per-page accordingly
        → NO:
            pagination.has_more === true?
              → YES: ASK the user before assuming you have everything
              → NO: you have all the data; proceed
```

### Examples

**User**: "list my workspaces"
**Agent should**:
1. Run `contentstudio --json workspaces:list --per-page 50` (high default to often avoid pagination)
2. If `pagination.has_more` is still true, say: "I see 50 of N workspaces. Want me to fetch all N?"

**User**: "delete all my draft posts"
**Agent should**:
1. Run `contentstudio --json posts:list --status draft --per-page 1` to peek at `total`
2. Run `contentstudio --json posts:list --status draft --per-page <total>` to get them all
3. Iterate over `data[]` and delete each
4. Never delete just the first page and report "done"

**User**: "show me my Facebook accounts"
**Agent should**:
1. Use `--platform facebook` filter — usually returns 0 or a handful, no pagination concern
2. If `has_more` still true (>20 FB accounts), ask before auto-fetching

### Endpoints that paginate

All `*:list` commands paginate:
`workspaces:list`, `accounts:list`, `posts:list`, `comments:list`, `media:list`, `campaigns:list`, `categories:list`, `labels:list`, `team:list`, `approval-workflows:list`.

Non-list commands (`auth:whoami`, `posts:create`, `posts:delete`, `media:upload`, etc.) never include `pagination` in their envelope.

---

## Command Reference

All commands are invoked as `contentstudio <group>:<command>`.

### Authentication

| Command | Purpose |
|---------|---------|
| `auth:login --api-key cs_...` | Store and verify API key |
| `auth:logout` | Forget stored credentials |
| `auth:whoami` | Hit `/me` and return user info |
| `auth:status` | Show local config (key redacted) |

### Workspaces

| Command | Purpose |
|---------|---------|
| `workspaces:list` | List user's workspaces |
| `workspaces:use <id>` | Set active workspace |
| `workspaces:current` | Show active workspace |
| `workspaces:create --name <n> --logo <url> --timezone <tz> [--super-admin-id <id>] [--note <t>] [--instagram-posting-method api\|mobile] [--first-day-day <Day> --first-day-key <0-6>]` | Create a new workspace (NOT workspace-scoped) |
| `workspaces:update [<id>] [--name] [--logo] [--timezone] [--note] [--instagram-posting-method] [--first-day-day --first-day-key]` | Update a workspace (defaults to active; ≥1 field required) |
| `workspaces:delete <id>` | Delete a workspace |

`workspaces:create` / `workspaces:update`:
- `--name` ≤35 chars, letters/spaces/digits/period only.
- `--logo` must be a URL; `--timezone` is an IANA string (e.g. `Asia/Karachi`).
- `--super-admin-id` (create only) — account owner to create under; required when you manage multiple super admins.
- First day of week is expressed as two paired flags: `--first-day-day <Sunday..Saturday>` + `--first-day-key <index>` where the key is the day's index (`Sunday=0 … Saturday=6`). Both build `first_day: {day, key}`.
- `workspaces:update` defaults to the active workspace if `<id>` is omitted and requires at least one field.
- Errors: `WORKSPACE_DELETE_FAILED` (422) on delete failure; 404 when the workspace doesn't exist.

### Social accounts (read + connect)

| Command | Purpose |
|---------|---------|
| `accounts:list [--platform <p>] [--search <q>]` | List connected social accounts |
| `platforms:list` | List platforms supported for new account connections |
| `accounts:connect <platform>` | Generate a one-time OAuth URL to connect a new account |
| `accounts:connect <platform> --reconnect --account-id <id>` | Refresh an expired/invalid account |
| `accounts:add-bluesky --handle <h> --app-password <p>` | Connect a Bluesky account (no browser — uses app password) |
| `accounts:add-facebook-group --name <n> [--image <url>]` | Manually add a Facebook Group connection |
| `accounts:remove <account_id>` | Remove (disconnect) a social account. `account_id` is the account's `id` from `accounts:list`. Requires the `save_social` permission (403 otherwise). |

`--platform` values for `accounts:list` filter: `facebook`, `linkedin`, `twitter`, `instagram`, `youtube`, `tiktok`, `pinterest`, `gmb`.

`<platform>` values for `accounts:connect`: `facebook`, `facebook-profile`, `instagram`, `instagram-via-facebook`, `twitter`, `linkedin`, `pinterest`, `tiktok`, `youtube`, `threads`, `gmb`, `tumblr`.

**Account-connection flow for AI agents:**
1. Run `platforms:list` to see what's supported and which method each uses (`oauth` / `credentials` / `manual`).
2. For OAuth platforms (most), call `accounts:connect <platform>` and surface the returned URL to the user — they open it in their browser to authorize. The CLI itself never handles credentials.
3. For Bluesky, ask the user for their handle + app-password (link them to <https://bsky.app/settings/app-passwords>) and call `accounts:add-bluesky`.
4. For Facebook Groups, just call `accounts:add-facebook-group --name "..."`.

### Posts

| Command | Purpose |
|---------|---------|
| `posts:list [--status draft\|scheduled\|...] [--date-from] [--date-to]` | List posts |
| `posts:create -c "text" -i <account> -t <publish_type> [-s "YYYY-MM-DD HH:MM:SS"] [-m <image_url>]` | Create a post (shortcut mode) |
| `posts:create -c "text" -t content_category --content-category-id <cat_id>` | Create a content-category post (accounts come from the category) |
| `posts:create -c "text" -i <fb_account> -t draft --facebook-carousel '<json>'` | Create a Facebook carousel post (2–10 cards) |
| `posts:create -c "text" -i <threads_account> -t draft --threads '<json>'` | Create a Threads multi-thread (chained) post (max 10 items) |
| `posts:create -c "text" -i <twitter_account> -t draft --twitter '<json>'` | Create a Twitter/X threaded-tweet post (max 10 tweets) |
| `posts:create -c "text" -i <account> -t draft --first-comment "..." --first-comment-account <id>` | Create a post with a first comment |
| `posts:create -c "text" -i <linkedin_account> -t draft --post-type poll --linkedin-options '<json>'` | Create a LinkedIn poll post (text-only) |
| `posts:create -c "text" -i <ig_account> -t draft --post-type reel --video-url <url> --instagram-trial-reel` | Create an Instagram trial reel (shown to non-followers first) |
| `posts:create -c "common text" -i <fb_account> -i <tiktok_account> -t draft -m <img_url> --platform-overrides '<json>'` | Same post to multiple platforms with a per-platform content override |
| `posts:create --body /path/to/body.json` | Create a post with full JSON body |
| `posts:update <post_id> [same flags as posts:create]` | Update an existing post (same body). Rejected (422) once the post is published/processing |
| `posts:delete <post_id> [--delete-from-social]` | Delete a post |
| `posts:approve <post_id> [--comment "..."]` | Approve a pending post |
| `posts:reject <post_id> [--comment "..."]` | Reject a pending post |

`-t / --publish-type` values: `scheduled`, `draft`, `queued`, `content_category`.

`posts:update <post_id>` takes the **exact same flags and body** as `posts:create` (both `--body` and shortcut mode) — it PUTs to `/workspaces/{w}/posts/{post_id}`. The backend allows the update only while the post's status is **not** `published` or `processing` (otherwise it returns 422). Use `--approval-workflow-action` (below) on update to change an already-attached workflow.

**`posts:create` / `posts:update` shortcut-mode flags:**
- `-c / --content` (required) — post text.
- `-i / --account <id>` (repeatable) — account ID(s) to post to. **Required UNLESS `--content-category-id` is given.**
- `--content-category-id <id>` — sets top-level `content_category_id`. **Required by the backend when `--publish-type content_category`.** When set, accounts are derived from the category, so `--account` is not required (and may be omitted). Use this instead of `--account` for content-category posts.
- `-s / --scheduled-at "YYYY-MM-DD HH:MM:SS"` — scheduling time. The CLI normalizes any parseable date to `YYYY-MM-DD HH:MM:SS` (the backend's required `date_format`) and sends it as a plain wall-clock string. **The API reads it in the workspace's timezone, not UTC** — so pass the local time the user wants the post to fire at, and get the zone from `workspaces:current` if you're unsure. `scheduling:best-times` already returns slots in that zone, so they can be passed straight through.
- `-m / --image-url <url>` (repeatable), `--video-url <url>`, `--media-id <id>` (repeatable) — media.
- `--post-type <type>` — e.g. `feed`, `reel`, `carousel`, `story`, `poll`. A **carousel** is auto-derived by the backend when `post_type=carousel` and 2+ images are attached. A **poll** requires `--post-type poll` **and** a text-only `--linkedin-options` poll block (no media).
- `--label <id>` (repeatable, max 20) → `labels`.
- `--campaign-id <id>` → `campaign_id`.
- `--linkedin-options '<json>'` → `linkedin_options` (**LinkedIn accounts**). Pass a JSON **object**; the CLI parses it locally (invalid JSON → `ConfigError`) and sends it verbatim.
  - Shape: `{ "title"?: <string>, "poll"?: { "question": <≤140>, "options": <string[2..4], each ≤30>, "duration": "ONE_DAY" | "THREE_DAYS" | "SEVEN_DAYS" | "FOURTEEN_DAYS" } }`
  - A **poll** must be paired with `--post-type poll` and text-only content (no images/video). Backend validates and 422s on violations.
- `--facebook-collaborator <user_id>` (repeatable, **max 10**) → `facebook_options.collaborators` (Facebook accounts). Merges with `--facebook-carousel` / `--facebook-background-id`.
- `--instagram-collaborator <user_id>` (repeatable, **max 3**) → `instagram_options.collaborators` (Instagram accounts). Rejected (422) together with `--instagram-trial-reel`.
- `--instagram-trial-reel` (boolean, default `false`) → `instagram_options.trial_reel.enabled`. Publishes an Instagram **trial reel** — shown to non-followers first, so it does not appear on the profile grid or in follower feeds.
  - `--instagram-trial-reel-graduation SS_PERFORMANCE|MANUAL` (default `SS_PERFORMANCE`) → `instagram_options.trial_reel.graduation_strategy`. `SS_PERFORMANCE` lets Instagram auto-graduate it to followers if it performs well; `MANUAL` requires graduating it by hand in the Instagram app (Instagram has no API for that).
  - Requires `--post-type reel` **exactly** (not `feed+reel`) and a video — feed/carousel/story are rejected. The CLI does not pre-validate this; the backend returns 422.
  - **Rejected (422) together with `--instagram-collaborator`.** Share-to-story is silently dropped (not rejected) when combined with a trial reel.
  - Not available when the workspace posts to Instagram via the mobile app (`instagram_posting_option=mobile`).
- `--platform-overrides '<json>'` → `platform_overrides` (top-level, works across any platform in the post). Pass a JSON **object** keyed by platform (`facebook`, `instagram`, `twitter`, `linkedin`, `pinterest`, `youtube`, `tiktok`, `gmb`, `tumblr`, `threads`, `bluesky`, `telegram`); the CLI parses it locally (invalid JSON → `ConfigError`) and sends it verbatim.
  - Shape per platform: `{ "content": { "text"?: <string>, "post_type"?: <string>, "media"?: { "images"?: <url[] ≤10>, "video"?: <url> } } }`.
  - `text` and `post_type` each merge **independently** with the common top-level `content` — an override with only `media` still inherits the common `text`/`post_type`.
  - `media` is **atomic**: if an override's `content` includes a `media` key at all, that platform's media is defined ENTIRELY by the override (no per-field fallback to the common media for whichever of `images`/`video` it omits). Omitting `media` entirely inherits the common `content.media` wholesale. This exists because some platforms (e.g. TikTok) can never support mixed images+video.
  - Omitting `--platform-overrides` entirely publishes the same top-level `content` to every targeted platform.
  - Override images are URLs only (no `media_ids`) and follow the same validation as the top-level media (max 10 images, no mixing images+video in one override).
- **Approval — two mutually-exclusive systems (pass only one):**
  - **Legacy** `--approver <user_id>` (repeatable) + `--approve-option anyone|everyone` (default `anyone`) + `--approval-notes "..."` → builds `approval: {approvers, approve_option, notes}` only when at least one approver is given. The post creator cannot be an approver. `anyone` = any single approver; `everyone` = all must approve.
  - **Workflow** `--approval-workflow-id <id>` + `--approval-workflow-notes "..."` → `approval_workflow: {workflow_id, notes?}` — ATTACH a workflow (works on both create and update). Get the id from `approval-workflows:list` (its `id`).
  - **Workflow (update only)** `--approval-workflow-action restart|resume|renotify_current|keep|remove` + `--approval-workflow-notes "..."` → `approval_workflow: {workflow_action, notes?}` — mutate the already-attached workflow. Only valid on `posts:update`.
  - **Exactly one** of `--approval-workflow-id` / `--approval-workflow-action`, and `--approver` cannot be combined with either `--approval-workflow-*` flag. The CLI errors locally (`ConfigError`) if these rules are broken.
- `--facebook-background-id <id>` → `facebook_options.facebook_background_id` (plain-text Facebook posts only; rejected if media is attached). Get a valid id from `facebook:text-backgrounds`.
- `--facebook-carousel '<json>'` → `facebook_options.carousel` (**Facebook accounts only**). Pass a JSON **object**; the CLI parses it locally (invalid JSON → `ConfigError`) and adds `is_carousel_post: true`. It **merges** with `--facebook-background-id` (neither clobbers the other). The backend validates card counts/CTA/limits and returns a 422 if they're wrong.
  - Shape: `{ "cards": [ { "image": <url, required>, "link": <url, required>, "title"?: <≤255>, "description"?: <≤1000> } ], "call_to_action"?, "end_card"?: <bool>, "end_card_url"?: <url>, "accounts"?: <string[]> }`
  - **MIN 2, MAX 10 cards.** The Facebook account ID(s) still go in the top-level `-i / --account` (or in `carousel.accounts`).
  - `call_to_action` is one of 33 values: `NO_BUTTON`, `ADD_TO_CART`, `APPLY_NOW`, `BET_NOW`, `BOOK_TRAVEL`, `BUY_NOW`, `BUY_TICKETS`, `CALL_NOW`, `CONTACT_US`, `DOWNLOAD`, `GET_DIRECTIONS`, `GET_OFFER`, `GET_QUOTE`, `GO_LIVE`, `INSTALL_MOBILE_APP`, `LEARN_MORE`, `LIKE_PAGE`, `LISTEN_MUSIC`, `OPEN_LINK`, `ORDER_NOW`, `PLAY_GAME`, `REGISTER_NOW`, `REQUEST_TIME`, `SAVE`, `MESSAGE_PAGE`, `WHATSAPP_MESSAGE`, `SHOP_NOW`, `SIGN_UP`, `SUBSCRIBE`, `USE_APP`, `WATCH_MORE`, `WATCH_VIDEO`.
- `--threads '<json>'` → `threads_options` (**Threads accounts only**). Pass a JSON **array** of thread items; the CLI parses it locally (invalid JSON → `ConfigError`), sets `has_multi_threads: true` and `multi_threads: <array>`. The Threads account ID goes in the top-level `-i / --account`.
  - Shape: `[ { "message": <string>, "media"?: <url[] ≤10>, "media_ids"?: <string[] ≤10> } ]`
  - **MAX 10 items.** Each item needs `message` OR `media`. Threads allows mixed media. Backend validates limits and returns a 422 if exceeded.
- `--twitter '<json>'` → `twitter_options` (**Twitter/X accounts only**). Pass a JSON **array** of tweet items; the CLI parses it locally (invalid JSON → `ConfigError`), sets `has_threaded_tweets: true` and `threaded_tweets: <array>`. The Twitter account ID goes in the top-level `-i / --account`. This mirrors `--threads` but for Twitter threaded tweets.
  - Shape: `[ { "message": <string>, "media"?: <url[] ≤10>, "media_ids"?: <string[] ≤10> } ]`
  - **MAX 10 tweets.** Each item needs `message` OR `media`. **Twitter does NOT allow mixed media in one tweet** (no images + video together) and **max 1 video per tweet**. The CLI does not validate tweet contents — the backend enforces these limits and returns a 422 if violated.
- `--first-comment "<message>"` → `first_comment` (≤2000 chars). The CLI builds `first_comment: { message, accounts? }`. The accounts are supplied with `--first-comment-account <id>` (repeatable).
  - `--first-comment-account <id>` (repeatable) → `first_comment.accounts`. **The backend REQUIRES at least one account when a `--first-comment` message is given, and the accounts must be a subset of the post's main `--account` IDs.** The CLI does not hard-block client-side — if you omit `--first-comment-account`, the backend returns a 422.

(`--facebook-carousel`, `--facebook-collaborator`, `--instagram-collaborator`, `--instagram-trial-reel`, `--instagram-trial-reel-graduation`, `--linkedin-options`, `--platform-overrides`, `--threads`, and `--twitter` only apply in shortcut mode. The `--body` JSON mode already supports `facebook_options` (carousel + collaborators), `instagram_options` (`collaborators` + `trial_reel`), `linkedin_options`, `threads_options`, `twitter_options`, `first_comment`, `approval`, `approval_workflow`, and top-level `platform_overrides` natively — use it for posts that mix multiple platform option blocks.)

The `posts:list` payload now includes `linkedin_options` and `approval_workflow` per post (in addition to the existing fields) — they surface automatically in the `--json` output.

### Scheduling — best time to post

| Command | Purpose |
|---------|---------|
| `scheduling:best-times` | Ranked posting slots for the workspace, derived from the connected accounts' history |
| `scheduling:best-times --account <platform>:<account_id>` | Restrict the analysis to specific accounts (repeatable) |
| `scheduling:best-times --global-slots <n> --per-account-slots <n>` | How many recommendations to return (1–24 each) |
| `scheduling:best-times --entities '<json>'` | Full entity array, for per-account slot counts |

A **slot** is one recommended posting time: a weekday and an hour. Slots come back ranked best-first, so `--global-slots 3` means *the three best hours to post*.

- **Times are always in the workspace timezone**, echoed as `meta.timezone`. There is no timezone parameter. That is the same clock `posts:create --scheduled-at` writes against, so a slot can be scheduled as-is — do **not** convert it to UTC first.
- **Omit `--account` to analyse every connected account.** Otherwise pass `<platform>:<account_id>` where both halves come from one `accounts:list` row (its `platform` and `_id`), e.g. `--account facebook:<account_id>`. Supported platforms: `facebook`, `instagram`, `linkedin`, `twitter`, `tiktok`, `youtube`, `pinterest`, `threads`, `gmb`, `tumblr`, `bluesky`, `telegram`.
- `--entities '[{"id":"<account_id>","type":"facebook","slots":3}]'` is the escape hatch for a **different slot count per account**; it cannot be combined with `--account`.
- `--global-slots` (API default 5) sizes the pooled `global` view; `--per-account-slots` (API default 3) sizes each account's list. Both are 1–24 and are validated by the CLI before the call. Neither changes the underlying analysis or the `heatmap_matrix`, which always carries every hour that had signal.

**Response shape** (`data` in the JSON envelope):

- `meta` — `{generated_at, timezone, warnings[], missing_entities[], ai_fallback_entities[]}`.
- `global` — pooled across analysed accounts: `top_recommendations[]` (each `{rank, day, date, time, score, platform_breakdown}`, where `time` is the hour as a bare string, e.g. `"14"` = 14:00), plus `heatmap_matrix.data` (sparse `[hour, day_index, score]` triples, `day_index` 0 = Monday) and `dates_key`. **`null` when no account had usable data.**
- `individual` — the same breakdown keyed by account id, each with `platform` and `source` (`data_driven` or an AI fallback).

**A thin workspace still returns HTTP 200.** Accounts with too little history come back in `meta.missing_entities` and `global` may be `null` — that is a successful read, not an error. Tell the user which accounts were skipped rather than reporting a failure. Accounts listed in `meta.ai_fallback_entities` are estimates, not measurements — say so when you present them.

Errors: 422 for unknown accounts or a workspace with no connected accounts; 502 (`BackendError`) when the optimizer is temporarily unavailable — retry rather than reporting no data.

**Reading is safe.** `scheduling:best-times` only reads, so it needs no `--dry-run` and no workspace confirmation. Scheduling a post from a slot is a mutation, so the usual `--dry-run` + workspace-confirmation rules apply to that step.

### Comments / Internal notes

| Command | Purpose |
|---------|---------|
| `comments:list <post_id>` | List comments on a post |
| `comments:add <post_id> "message" [--note] [--mention <user_id>]` | Add public comment or internal note |

### Media library

| Command | Purpose |
|---------|---------|
| `media:list [--type images\|videos] [--sort recent\|...]` | List media assets |
| `media:upload --file <local_path>` | Upload a local file |
| `media:upload --url <external_url>` | Import from external URL |

### AI images

| Command | Purpose |
|---------|---------|
| `images:tools` | The image tools this API can invoke, with each tool's required inputs and control options |
| `images:models` | Model identifiers `images:generate` accepts |
| `images:brand` | `{configured, enabled}` — whether `--use-brand` will apply anything |
| `images:generate -p "<prompt>"` | Prompt → image, saved to the media library |
| `images:generate -p "<edit>" --image-url <url>` | Edit an existing image instead of generating from scratch |
| `images:product-image --product-image-url <url>` | Restage a product photo |
| `images:headshot --image-url <url>` | Professional headshot from a photo of a person |
| `images:face-swap --target-image-url <url> --face-image-url <url>` | Put one image's face onto another's subject |
| `images:outfit-swap --target-image-url <url> --outfit-image-url <url>` | Virtual try-on |
| `images:upscale --image-url <url>` | Raise an image's resolution |
| `images:remove-background --image-url <url>` | Cut the subject out of its background |
| `images:tool <tool_key> --body '<json>'` | Any tool, with its full control set (this is how you reach `image-to-image`'s `style`, `aspect_ratio`, `image_resolution`, `image_quality`, multiple `attachments`, `reference_image_urls`) |

**Every generation returns the same payload, and `data.media_id` is the handle you pass to `posts:create --media-id`.** That two-step is the normal way to publish an AI image — see the generate-then-publish recipe in the Examples section.

```jsonc
{ "ok": true, "data": {
    "media_id": "66f1a2b3c4d5e6f708192a3b",   // → posts:create --media-id
    "url": "https://storage.googleapis.com/.../generated.png",
    "width": 1024, "height": 1024, "mime_type": "image/png",
    "model_used": "nano-banana-pro",            // may differ from --model
    "brand_applied": false,
    "credits": { "consumed": 1, "available": 412 },
    "persist_error": null } }
```

- **`media_id` is the durable handle; `url` is not.** Use `url` for a preview or as the input to the next tool. Do not store it — a `url` returned alongside a `persist_error` is a temporary provider link.
- **Check `persist_error` (or `media_id !== null`) before calling a 200 done.** The image was generated *and charged* but could not be saved: `media_storage_full` means the workspace is out of media storage (retrying costs another credit and fails again), anything else is worth one retry. Tell the user to download the `url` now.
- **Tools chain.** A media-library `url` from one call is valid input to the next (generate → upscale → remove-background). Each call is charged separately.
- **Every image URL you pass in must be publicly fetchable over http(s)** by the image service — no auth, no expired signed URL, no private bucket, no local path. Upload a local file with `media:upload --file` first and pass the returned URL. A URL the service cannot download is `ValidationError` (`IMAGE_INPUT_REJECTED`), not a service outage.
- **Generation is slow and billable.** The server's deadline is 120s; the CLI waits 150s (`--timeout <seconds>` to change it). These calls are **not retried** — the built-in 429/5xx retry is off for them, because re-running a generation can consume a second image credit. Retry deliberately, not in a loop.
- **`--model` is optional.** Omit it for the service default. Costs differ (most models 1 image credit, `gpt-image-2` 5), so read `credits.consumed` rather than assuming.
- **`model_used` is not one of the `images:models` values** — it comes back provider-prefixed (`fal-ai/nano-banana-pro`, `pixelcut/background-removal`) and names the model that actually ran after any fallback. Report it; never compare it for equality with `--model`.
- **`images:tools` `controls` describe the underlying tool, not the public payload.** Take `--resolution` / `--aspect-ratio` values from there, but a control with no matching flag cannot be sent at all — `upscale` lists `model` and `upscale_factor`, and neither is in the API's tool payload. Likewise `accepts_instructions: true` on `headshot` and `face-swap` is not reachable: only `images:product-image` has `--instructions`. Sending an unsupported field is dropped in silence, so it will look like it worked.
- **`--dimensions`** is `square`, `square_hd`, `portrait_4_5` or `landscape_16_9`, text→image only. Exact pixels are the model's choice — read `width`/`height` back. Anything else is rejected by the CLI before the call.
- **Brand knowledge is a boolean, read-only.** `--use-brand` on `images:generate` only; it is resolved server-side and no brand ID or brand content is ever accepted or returned. `--use-brand` with no brand profile is `brand_applied: false`, not an error — `images:brand` tells you in advance. **The tool commands and `images:generate --image-url` always report `brand_applied: false`** — edits and tools do not apply brand knowledge.
- **`--dry-run` on every generating command** prints the endpoint and body and calls nothing. Use it to show the user the prompt before spending a credit. The three discovery commands are reads and need no `--dry-run`.
- **Rate limit: 30 requests/minute**, shared with the ContentStudio app's own AI usage on the same account. A `RateLimitError` here needs the full minute.
- Video tools (`image-to-video`, `motion-control`, `lip-sync`, `talking-avatar`) are **not** on this API; asking for one is `NotFoundError` (`TOOL_NOT_FOUND`), same as an unknown key.
- `images:tools` answering with an empty list means the catalogue is temporarily unreachable, not that the workspace has no tools. Retry rather than telling the user there are none.
- Sample workspaces are read-only: the three discovery commands work, both generating paths return 403.

### Lookup tables (read)

| Command | Purpose |
|---------|---------|
| `campaigns:list` | List campaigns (folders) |
| `categories:list` | List content categories |
| `labels:list` | List labels |
| `team:list` | List workspace team members |
| `approval-workflows:list` | List approval workflows (use an item's `id` as `--approval-workflow-id`) |

Each `approval-workflows:list` item is `{ id, name, is_default, levels: [{ level_number, title, rule, members: [{ user_id }] }] }`. Use `id` as `posts:create` / `posts:update`'s `--approval-workflow-id`.

### Labels (write)

| Command | Purpose |
|---------|---------|
| `labels:create --name <n> --color <color_N>` | Create a label |
| `labels:update <label_id> [--name] [--color]` | Update a label |
| `labels:delete <label_id>` | Delete a label |

### Campaigns (write)

| Command | Purpose |
|---------|---------|
| `campaigns:create --name <n> --color <color_N>` | Create a campaign |
| `campaigns:update <campaign_id> [--name] [--color]` | Update a campaign |
| `campaigns:delete <campaign_id>` | Delete a campaign |

For labels and campaigns: `--name` ≤100 chars; `--color` is one of the enum values `color_1` … `color_20`. On update, pass `--name` and/or `--color` (each is required-if-present).

### Team members (write)

| Command | Purpose |
|---------|---------|
| `team:add --email <e> --role <r> [--membership team\|client] [--permissions '<json>']` | Invite a member |
| `team:update <member_id> --role <r> --permissions '<json>' [--membership]` | Update a member's role/permissions |
| `team:remove <member_id> [--confirmed]` | Remove a member |

- `member_id` is the **membership id** — the `member_id` field from `team:list` (not the user's `id`, a distinct field).
- `--role` (required): `admin`, `approver`, or `collaborator`.
- `--email` (required for `team:add`): a single email address.
- `--membership` (optional): `team` (internal) or `client` (external; hidden from internal notes). Default `team`.
- `--permissions` (optional for `team:add`, **required for `team:update`**): a **role-aware** JSON object passed as a string (e.g. `--permissions '{"addSocial":true}'`). Invalid JSON → local `ConfigError`; invalid role/key combinations → backend 422. `team:update` is a partial merge — only the keys you send change; a role change drops boolean keys not valid for the new role.
  - **Shared booleans** (any role): `accessSharedFolder`, `allow_workflow_management`.
  - **admin**: full access — only the `hasBillingAccess` boolean applies.
  - **collaborator** booleans: `addBlog`, `addSocial`, `addSource`, `addTopic`, `viewTeam`, `rescheduleQueue`, `postsReview`, `changeFBGroupPublishAs`, `hasListeningAccess`.
  - **approver** booleans: `approverCanEditPost`, `approverCanAddNotes`, `approverCanCreatePost` (approvers can only approve/reject otherwise).
  - **Account-access arrays** (any role; must be real connected account IDs in the workspace, else 422): `facebook`, `instagram`, `threads`, `twitter`, `linkedin`, `pinterest`, `telegram`, `youtube`, `tiktok`, `tumblr`, `tumblr_blogs`, `tumblr_profiles`, `bluesky`, `gmb`.
  - **Blog arrays** (any role; not existence-validated): `wordpress`, `medium`, `shopify`, `webflow`.
  - **content_categories** (any role; must be real category IDs in the workspace, else 422): array of content-category IDs.
- `team:remove`: if the member is in approval workflows / in-flight posts, the backend returns error_code `REQUIRES_REMOVAL_CONFIRMATION` (422) — re-run with `--confirmed` (sends `?confirmed=true`) to proceed. 404 = `TEAM_MEMBER_NOT_FOUND`.

### Social accounts (write)

| Command | Purpose |
|---------|---------|
| `accounts:remove <account_id> [--dry-run]` | Remove (disconnect) a social account (`DELETE /workspaces/{w}/accounts/{account_id}`) |

- `account_id` is the account's `id` from `accounts:list`.
- Requires the `save_social` permission — callers without it get 403.
- Errors: 401 (bad/missing API key), 403 (missing `save_social`), 404 (account not found in the workspace), 422 (removal failed). Success is 200 with an empty `data` array.
- Mutating command — preview with `--dry-run` and confirm the workspace first.

### Facebook helpers

| Command | Purpose |
|---------|---------|
| `facebook:text-backgrounds` | List Facebook colored-background presets (use `id` as `facebook_options.facebook_background_id` on plain-text posts) |

### Social Inbox

The inbox unifies three kinds of item into **elements**: `conversation` (DMs),
`post` (a post with comments), and `review`. `inbox:list` is the entry point —
everything else takes an id it returned.

### Which id to pass

Inbox commands take their id from the `element_details` object on each
`inbox:list` row. Use **`element_details.element_id`** — it is accepted by
every element-scoped command.

| Command | Id to pass |
|---------|------------|
| `inbox:update` (`--element`) | `element_details.element_id` |
| `inbox:tag-attach` / `inbox:tag-detach` | `element_details.element_id` |
| `inbox:mark-read` | `element_details.element_id` |
| `inbox:contact` / `inbox:contact-update` | `element_details.element_id` |
| `inbox:messages` / `send` / `notes` / `note-add` / `bookmarks` | `element_details.element_id` (`t_…` form) |
| `inbox:comments` / `inbox:comment-add` | `element_details.post_id` |

Values look like:

- `element_details.element_id` — `t_10000000000000001` (conversation) or
  `100000000000000001_200000000000000002` (post)
- `element_details.post_id` — `900000000000001_100000000000000001`

The row's top-level `element_ref` is an internal reference, not a command
argument — always take the id from `element_details`.

If a command returns an empty list or reports the item as not found, confirm
the id against this table before describing the result to the user.

Also needed for most writes:

- **`platform_id`** — the connected social account the item belongs to. The
  backend replies through that account's token. It is on every `inbox:list`
  row as `platform_id`, or from `accounts:list`.
- The platform field on a list row is **`platform`** (not `platform_type`),
  but the write commands take `--platform-type`.

**Reading**

| Command | Purpose |
|---------|---------|
| `inbox:list` | Search the inbox. `--type conversation\|post\|review` (repeatable), `--action all\|marked_done\|archived\|assigned`, `--search`, `--tag`, `--channels '{"facebook":["<acct>"]}'`, `--page`, `--limit` |
| `inbox:summary` | Counts per bucket — cheap way to answer "anything unread?" |
| `inbox:messages <conversation_id>` | Messages in a DM thread. Id = `element_details.element_id`. `--sort-order asc\|desc` |
| `inbox:comments <post_id>` | A post's comments (threaded). Id = `element_details.post_id` |
| `inbox:notes <conversation_id>` | Internal notes (team-only). Id = `element_details.element_id`. Paginated |
| `inbox:bookmarks <conversation_id>` | Starred messages. Id = `element_details.element_id`. Paginated |
| `inbox:contact <element_ref>` | Contact profile behind an element |
| `inbox:tags` | The workspace's inbox tag catalogue |

**Replying — customer-facing, confirm before sending**

| Command | Purpose |
|---------|---------|
| `inbox:send <conversation_id>` | Send a DM (id = `element_details.element_id`). Needs `--platform-type facebook\|instagram`, `--platform-id`, and `--message` and/or `--file`. `--idempotency-key` de-dupes a retry |
| `inbox:comment-add <post_id>` | Comment on a post. `--comment-id` makes it a threaded reply; `--private-reply` sends a Facebook DM instead; `--attachment <path>` attaches a file |
| `inbox:review-reply <review_id>` | Add or replace a review reply (upsert). `--platform-id`, `--reply` |
| `inbox:note-add <conversation_id>` | Add an internal note. `--mention <user_id>` (repeatable). Not customer-visible |

**Triage and moderation**

| Command | Purpose |
|---------|---------|
| `inbox:mark-read <element_ref>` | Mark read (idempotent) |
| `inbox:update` | Bulk state change. `--element` (repeatable, **max 100**) plus **exactly one** of `--status done\|pending`, `--archived`, `--assigned` (pair with `--assigned-to '{"id":"<user>"}'`) |
| `inbox:comment-hide` / `inbox:comment-unhide <comment_id>` | Hide/unhide. Unhide needs `--platform-type` + `--platform-id` |
| `inbox:comment-like` / `inbox:comment-unlike <comment_id>` | Facebook only |
| `inbox:comment-delete <comment_id>` | Delete. Needs `--platform-type` + `--platform-id`; LinkedIn also needs `--comment-urn` |
| `inbox:star` / `inbox:unstar <message_id>` | Star a message |
| `inbox:message-delete <message_id>` | Soft-delete a message. `--platform-id` |
| `inbox:review-reply-delete <review_id>` | Remove a review reply. `--platform-id` |
| `inbox:contact-update <element_ref>` | `--platform-id` plus any of `--name`, `--email`, `--phone`, `--company` |

**Tags**

| Command | Purpose |
|---------|---------|
| `inbox:tag-create` | `--name` (≤50), `--color` — a **hex** value like `#33aa55`. (Older tags may display `color_1`, but the API now rejects that format.) |
| `inbox:tag-update <tag_id>` | `--name` and/or `--color` |
| `inbox:tag-delete` | `--tag <id>` (repeatable, bulk) |
| `inbox:tag-merge` | Fold tags into a new one: `--name`, `--color`, `--tag` (repeatable) |
| `inbox:tag-attach <element_ref>` | `--tag` (repeatable), `--platform-id`, `--inbox-type` |
| `inbox:tag-detach <element_ref> <tag_id>` | `--platform-id`, `--inbox-type` |

**Inbox pagination note.** Inbox list commands use `--limit` rather than
`--per-page` (`--per-page` is accepted as an alias). The pagination rules in
the section above apply unchanged: if `pagination.has_more` is true, do not
report the first page as the whole inbox.

> **Inbox page size is 200.** For inboxes larger than that, page through with
> `--page 1`, `--page 2`, … up to `pagination.last_page` rather than raising
> `--limit` past 200.

**Inbox limits.** The CLI validates these locally, so they surface as a
`ConfigError` before any request is sent:

| Limit | Where |
|-------|-------|
| `--limit` ≤ 200 | `inbox:list`, `inbox:messages`, `inbox:comments` |
| ≤ 100 `--element` refs per call | `inbox:update` |
| Exactly **one** operation per call | `inbox:update` — `--status`, `--archived`, and `--assigned` are mutually exclusive; run separate commands |
| Tag name ≤ 50 chars | `inbox:tag-create` |

**Partial success on bulk updates.** `inbox:update` returns HTTP `207` when
some elements were updated and others were not, listing the remainder in
`missing_ids`. The CLI reports this as a warning. When `missing_ids` is
non-empty, tell the user which elements did not change rather than reporting
the batch as fully applied.

**`inbox:contact-update` updates the whole contact.** A contact is a person,
not a per-element attribute, so the change applies to every element for that
contact on that account in the workspace. The response's `updated_count` says
how many were updated. Mention this scope to the user before running it.

**`inbox:contact` returns personal data.** Email and phone of an end customer.
Return only the fields the user actually asked for; don't dump the whole record
into a summary or paste it somewhere persistent without being asked.

**`inbox:messages` includes activity events.** A thread contains both messages
and a record of team activity. Activity entries have `message: null` and an
`action` block (`MARKED_AS_DONE`, `PENDING`, `ARCHIVED`, …) naming the teammate
who performed it, and they count toward `total_messages` and pagination. Filter
on `action == null` when you mean customer messages — don't count activity
entries as messages, quote them as customer text, or treat one as the latest
reply. The CLI renders them as `— marked as done —` rows in human mode.

**Replies are nested, not paginated.** In `inbox:comments`, replies live under
each thread's `children` — they are not separate top-level rows. Paging counts
threads (`total_threads`), not individual comments, so "12 comments" from the
pagination block means 12 *threads* and there may be many more replies inside.

**Handling a `409` on a send.** For `inbox:send` and `inbox:comment-add`, a
`409` means the delivery outcome is undetermined — the message may or may not
have reached the customer. The CLI surfaces it as `ConflictError`. Do not retry
automatically: read the conversation back with `inbox:messages` to check
whether it landed, and tell the user what you found before sending again.

**Confirming a send.** `inbox:send` returns `sent_message.id_status`. When it
is `unavailable`, the platform accepted the message without returning an id, so
there is no id to reconcile against later — report it as sent, with delivery
unconfirmed.

**Inbox-specific responses.** A `502` from an `inbox:*` command indicates the
inbox service is temporarily unreachable rather than a missing item — retry
after a short backoff. An empty `inbox:list` result is a successful empty
read: report it as "no matching conversations", not "not found".

### Analytics

Read-only performance reports across Facebook, Instagram, YouTube, Pinterest,
LinkedIn, Google Business Profile, TikTok, Twitter/X, **Meta Ads** and
**Google Ads**, plus cross-network Campaigns & Labels reports (133 commands
total, one per backend endpoint — no generic passthrough).

Most commands need `--platform-id` (the connected account, from
`accounts:list`) plus either a date range or a native post id. The ads and
campaign/label families are the exceptions — see below:

- **Date-range reports** — `--start-date` / `--end-date` (`YYYY-MM-DD`,
  both required). Optional on most: `--timezone` (IANA name, default UTC),
  `--date` (alternative `'YYYY-MM-DD - YYYY-MM-DD'` form that overrides the
  range), `--limit` / `--offset`, `--order-by` (choices vary per command —
  check `--help`), and array filters like `--media-type`, `--hashtags`,
  `--entity-type` (repeat the flag for multiple values).
- **Single-item lookups** (`*-single-post`, `*-single-pin`, `*-single-tweet`,
  `*-single-video`) — `--platform-id` + `--post-id` (the platform-native id,
  not a ContentStudio internal id). No date range.
- **AI insights** commands (`*-ai-insights`) additionally take `--type`
  (`aiInsightsSummary` for the compact card, `aiInsightsDetailed` for the full
  report) and `--language` (ISO 639-1, default `en`). Both ads platforms have
  one too.
- **Ads reports** (`analytics:meta-ads-*`, `analytics:google-ads-*`) take
  `--account-id` — an *ad* account (`act_…` on Meta, a customer id on Google,
  from `analytics:meta-ads-accounts` / `analytics:google-ads-accounts`) — not
  `--platform-id`. Table commands add `--limit`/`--offset`, `--search`,
  `--order-by`/`--order-dir` and id filters (`--campaign-id`, `--ad-set-id`,
  `--ad-group-id`); chart commands add `--metric` and `--level`.
  `analytics:*-ads-accounts` needs no account at all — it is how you find one.
- **Campaigns & Labels** (`analytics:campaigns-labels-*`) are the only POST
  reports: the filters are lists, so repeat the flag —
  `--campaigns <id> --campaigns <id>`, `--labels <id>`, and one account list
  per network (`--facebook-accounts`, `--instagram-accounts`, …). Only
  `--start-date`/`--end-date` are required.

Run `contentstudio analytics:<command> --help` to see the exact options for
any one command — required vs. optional and enum choices differ per endpoint.

Every analytics command is read-only — the campaign/label ones are POSTs only
because their filters are arrays — so none of them take `--dry-run` (that flag
only exists on mutating commands elsewhere in this CLI).

**If a command returns `ANALYTICS_UPSTREAM_ERROR`** (HTTP 200 with
`status: false`, often `upstream_status: 401`), that is the ContentStudio
backend's own analytics pipeline failing upstream — not a bad request. Report
it as "the analytics service is temporarily unavailable," don't retry the
exact same call in a loop, and don't treat it as evidence the account/workspace
is wrong.

**Facebook (15)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:facebook-active-users` | Facebook active users by hour and day of week | --platform-id, --start-date, --end-date |
| `analytics:facebook-ai-insights` | Facebook AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:facebook-audience-growth` | Facebook fan / follower growth over time | --platform-id, --start-date, --end-date |
| `analytics:facebook-audience-location` | Facebook audience location (country/city breakdown) | --platform-id, --start-date, --end-date |
| `analytics:facebook-demographics` | Facebook audience age / gender / country / city demographics | --platform-id, --start-date, --end-date |
| `analytics:facebook-demographics-overview` | Facebook demographics overview widget | --platform-id, --start-date, --end-date |
| `analytics:facebook-engagement` | Facebook page engagements over time | --platform-id, --start-date, --end-date |
| `analytics:facebook-get-top-posts` | Facebook top posts with media_type filter | --platform-id, --start-date, --end-date |
| `analytics:facebook-impressions` | Facebook page impressions over time | --platform-id, --start-date, --end-date |
| `analytics:facebook-overview-top-posts` | Facebook top posts (overview widget) | --platform-id, --start-date, --end-date |
| `analytics:facebook-publishing-behaviour` | Facebook engagement by impression type over time | --platform-id, --start-date, --end-date |
| `analytics:facebook-reels` | Facebook Reels performance over time | --platform-id, --start-date, --end-date |
| `analytics:facebook-single-post` | Get a single Facebook post by ID | --platform-id, --post-id |
| `analytics:facebook-summary` | Facebook summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:facebook-video-insights` | Facebook video view time and plays over time | --platform-id, --start-date, --end-date |

**Instagram (15)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:instagram-active-users` | Instagram active users by hour and day of week | --platform-id, --start-date, --end-date |
| `analytics:instagram-ai-insights` | Instagram AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:instagram-audience-growth` | Instagram follower growth over time | --platform-id, --start-date, --end-date |
| `analytics:instagram-country-city` | Instagram audience country / city breakdown | --platform-id, --start-date, --end-date |
| `analytics:instagram-demographics-age` | Instagram audience age / gender breakdown | --platform-id, --start-date, --end-date |
| `analytics:instagram-engagement` | Instagram post engagement over time | --platform-id, --start-date, --end-date |
| `analytics:instagram-get-top-posts` | Instagram top posts with hashtag filter | --platform-id, --start-date, --end-date |
| `analytics:instagram-hashtags` | Instagram top hashtags by engagement | --platform-id, --start-date, --end-date |
| `analytics:instagram-impressions` | Instagram post impressions over time | --platform-id, --start-date, --end-date |
| `analytics:instagram-publishing-behaviour` | Instagram post engagement by media type over time | --platform-id, --start-date, --end-date |
| `analytics:instagram-reels-performance` | Instagram Reels engagement and watch time over time | --platform-id, --start-date, --end-date |
| `analytics:instagram-single-post` | Get a single Instagram post by ID | --platform-id, --post-id |
| `analytics:instagram-stories-performance` | Instagram stories impressions, reach, and interactions over time | --platform-id, --start-date, --end-date |
| `analytics:instagram-summary` | Instagram summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:instagram-top-posts` | Instagram top-performing posts | --platform-id, --start-date, --end-date |

**YouTube (20)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:youtube-ai-insights` | YouTube AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:youtube-demographics` | YouTube audience demographics — age & gender, device type, subscriber change | --platform-id, --start-date, --end-date |
| `analytics:youtube-engagement-trend` | YouTube cumulative engagement trend over time | --platform-id, --start-date, --end-date |
| `analytics:youtube-engagement-trend-daily` | YouTube daily-delta engagement trend | --platform-id, --start-date, --end-date |
| `analytics:youtube-find-video` | YouTube traffic source breakdown (how viewers found videos) | --platform-id, --start-date, --end-date |
| `analytics:youtube-least-posts` | YouTube least-performing videos ordered by views and engagement | --platform-id, --start-date, --end-date |
| `analytics:youtube-performance-schedule` | YouTube video performance metrics grouped by publish date | --platform-id, --start-date, --end-date |
| `analytics:youtube-publishing-behaviour` | YouTube posts published over time and content-type breakdown | --platform-id, --start-date, --end-date |
| `analytics:youtube-single-video` | Get a single YouTube video by ID | --platform-id, --post-id |
| `analytics:youtube-sorted-top-posts` | YouTube videos sorted by a configurable metric | --platform-id, --start-date, --end-date |
| `analytics:youtube-subscriber-trend` | YouTube cumulative subscriber trend over time | --platform-id, --start-date, --end-date |
| `analytics:youtube-subscriber-trend-daily` | YouTube daily-delta subscriber trend | --platform-id, --start-date, --end-date |
| `analytics:youtube-summary` | YouTube summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:youtube-top-geographies` | YouTube top geographies — countries pre-sorted by views, watch time, view duration and view percentage | --platform-id, --start-date, --end-date |
| `analytics:youtube-top-posts` | YouTube top videos ordered by views and engagement | --platform-id, --start-date, --end-date |
| `analytics:youtube-video-sharing` | YouTube sharing platform breakdown | --platform-id, --start-date, --end-date |
| `analytics:youtube-views-trend` | YouTube cumulative views split by subscriber / non-subscriber | --platform-id, --start-date, --end-date |
| `analytics:youtube-views-trend-daily` | YouTube daily-delta views trend | --platform-id, --start-date, --end-date |
| `analytics:youtube-watch-time-trend` | YouTube cumulative watch time split by subscriber / non-subscriber | --platform-id, --start-date, --end-date |
| `analytics:youtube-watch-time-trend-daily` | YouTube daily-delta watch time trend | --platform-id, --start-date, --end-date |

**Pinterest (14)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:pinterest-ai-insights` | Pinterest AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:pinterest-engagement-trend` | Pinterest cumulative engagement trend over time | --platform-id, --start-date, --end-date |
| `analytics:pinterest-engagement-trend-daily` | Pinterest daily-delta engagement trend | --platform-id, --start-date, --end-date |
| `analytics:pinterest-follower-trend` | Pinterest cumulative follower trend over time | --platform-id, --start-date, --end-date |
| `analytics:pinterest-follower-trend-daily` | Pinterest daily-delta follower trend | --platform-id, --start-date, --end-date |
| `analytics:pinterest-impressions-trend` | Pinterest cumulative impressions trend over time | --platform-id, --start-date, --end-date |
| `analytics:pinterest-impressions-trend-daily` | Pinterest daily-delta impressions trend | --platform-id, --start-date, --end-date |
| `analytics:pinterest-pin-performance` | Pinterest pin performance metrics over time | --platform-id, --start-date, --end-date |
| `analytics:pinterest-pin-posting` | Pinterest cumulative pin posting activity over time | --platform-id, --start-date, --end-date |
| `analytics:pinterest-pin-posting-daily` | Pinterest daily-delta pin posting activity | --platform-id, --start-date, --end-date |
| `analytics:pinterest-pin-rollup` | Pinterest pin performance rollup — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:pinterest-single-pin` | Get a single Pinterest pin by ID | --platform-id, --post-id |
| `analytics:pinterest-summary` | Pinterest summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:pinterest-top-pins` | Pinterest top-performing and least-performing pins | --platform-id, --start-date, --end-date |

**LinkedIn (11)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:linkedin-ai-insights` | LinkedIn AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:linkedin-audience-growth` | LinkedIn follower growth over time | --platform-id, --start-date, --end-date |
| `analytics:linkedin-followers-demographics` | LinkedIn follower demographics by industry, country, and other dimensions | --platform-id, --start-date, --end-date |
| `analytics:linkedin-get-top-posts` | LinkedIn top posts with hashtag and media type filter | --platform-id, --start-date, --end-date |
| `analytics:linkedin-hashtags` | LinkedIn top hashtags by engagement | --platform-id, --start-date, --end-date |
| `analytics:linkedin-page-views` | LinkedIn page views over time (desktop vs mobile) | --platform-id, --start-date, --end-date |
| `analytics:linkedin-posts-per-days` | LinkedIn post count distribution by day of week | --platform-id, --start-date, --end-date |
| `analytics:linkedin-publishing-behaviour` | LinkedIn post engagement by media type over time | --platform-id, --start-date, --end-date |
| `analytics:linkedin-single-post` | Get a single LinkedIn post by ID | --platform-id, --post-id |
| `analytics:linkedin-summary` | LinkedIn summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:linkedin-top-posts` | LinkedIn top-performing posts | --platform-id, --start-date, --end-date |

**Google Business Profile (GMB) (10)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:gmb-actions` | GMB customer actions (clicks, calls, directions) over time | --platform-id, --start-date, --end-date |
| `analytics:gmb-ai-insights` | GMB AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:gmb-impressions` | GMB impressions breakdown by channel and device over time | --platform-id, --start-date, --end-date |
| `analytics:gmb-media-activity` | GMB media (photo/video) activity over time | --platform-id, --start-date, --end-date |
| `analytics:gmb-publishing-behavior` | GMB posts published over time and topic-type breakdown | --platform-id, --start-date, --end-date |
| `analytics:gmb-reviews` | GMB reviews — ratings, distribution, and daily activity | --platform-id, --start-date, --end-date |
| `analytics:gmb-search-keywords` | GMB top search keywords that surfaced the listing | --platform-id, --start-date, --end-date |
| `analytics:gmb-single-post` | Get a single GMB post by ID | --platform-id, --post-id |
| `analytics:gmb-summary` | GMB summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:gmb-top-posts` | GMB top-performing posts | --platform-id, --start-date, --end-date |

**TikTok (8)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:tiktok-ai-insights` | TikTok AI-generated insights | --platform-id, --start-date, --end-date |
| `analytics:tiktok-engagement-trend` | TikTok daily engagement trend over time | --platform-id, --start-date, --end-date |
| `analytics:tiktok-follower-trend` | TikTok follower and views trend over time | --platform-id, --start-date, --end-date |
| `analytics:tiktok-publishing-behaviour` | TikTok daily post volume and engagement breakdown over time | --platform-id, --start-date, --end-date |
| `analytics:tiktok-single-post` | Get a single TikTok post by ID | --platform-id, --post-id |
| `analytics:tiktok-sorted-top-posts` | TikTok posts sorted by a configurable metric | --platform-id, --start-date, --end-date |
| `analytics:tiktok-summary` | TikTok summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:tiktok-top-posts` | TikTok top and least performing posts | --platform-id, --start-date, --end-date |

**Twitter/X (7)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:twitter-credits-used` | Twitter API credits usage for the workspace | --platform-id, --start-date, --end-date |
| `analytics:twitter-engagement-impression` | Twitter engagement and impression trend over time | --platform-id, --start-date, --end-date |
| `analytics:twitter-followers-trend` | Twitter follower trend over time | --platform-id, --start-date, --end-date |
| `analytics:twitter-least-tweets` | Twitter least-performing tweets | --platform-id, --start-date, --end-date |
| `analytics:twitter-single-tweet` | Get a single Twitter/X tweet by ID | --platform-id, --post-id |
| `analytics:twitter-summary` | Twitter summary KPIs — current vs previous period | --platform-id, --start-date, --end-date |
| `analytics:twitter-top-tweets` | Twitter top-performing tweets | --platform-id, --start-date, --end-date |

**Meta Ads (11)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:meta-ads-accounts` | List connected Meta ad accounts | — |
| `analytics:meta-ads-ad-sets` | Ad sets with per-ad-set metrics | --account-id, --start-date, --end-date |
| `analytics:meta-ads-ads` | Ads with per-ad metrics and creative details | --account-id, --start-date, --end-date |
| `analytics:meta-ads-ai-insights` | AI-generated insights for an ad account | --account-id, --start-date, --end-date, --type |
| `analytics:meta-ads-campaigns` | Campaigns with per-campaign metrics | --account-id, --start-date, --end-date |
| `analytics:meta-ads-demographics` | Audience breakdown by age and gender, region or country | --account-id, --start-date, --end-date |
| `analytics:meta-ads-performance-by-level` | One metric broken down by campaign, ad set or ad | --account-id, --start-date, --end-date |
| `analytics:meta-ads-performance-by-placement` | One metric broken down by publisher platform and placement | --account-id, --start-date, --end-date |
| `analytics:meta-ads-performance-over-time` | Daily time series for one or more metrics | --account-id, --start-date, --end-date |
| `analytics:meta-ads-results-by-objective` | Results and spend grouped by campaign objective | --account-id, --start-date, --end-date |
| `analytics:meta-ads-summary` | Meta Ads headline KPIs — current vs previous period | --account-id, --start-date, --end-date |

**Google Ads (17)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:google-ads-accounts` | List connected Google Ads accounts | — |
| `analytics:google-ads-ad-groups` | Ad groups with per-ad-group metrics | --account-id, --start-date, --end-date |
| `analytics:google-ads-ads` | Ads with per-ad metrics | --account-id, --start-date, --end-date |
| `analytics:google-ads-ai-insights` | AI-generated insights for an ad account | --account-id, --start-date, --end-date, --type |
| `analytics:google-ads-campaigns` | Campaigns with per-campaign metrics | --account-id, --start-date, --end-date |
| `analytics:google-ads-conversion-actions` | Conversion actions configured on the account | --account-id, --start-date, --end-date |
| `analytics:google-ads-conversion-funnel` | Conversion funnel — impressions through to conversions | --account-id, --start-date, --end-date |
| `analytics:google-ads-conversions-by-action` | Conversions grouped by conversion action | --account-id, --start-date, --end-date |
| `analytics:google-ads-conversions-over-time` | Conversions over time | --account-id, --start-date, --end-date |
| `analytics:google-ads-demographics` | Audience breakdown by age, gender and location | --account-id, --start-date, --end-date |
| `analytics:google-ads-keywords` | Keywords with per-keyword metrics | --account-id, --start-date, --end-date |
| `analytics:google-ads-performance-by-level` | One metric broken down by campaign, ad group or ad | --account-id, --start-date, --end-date |
| `analytics:google-ads-performance-by-type` | One metric broken down by campaign type | --account-id, --start-date, --end-date |
| `analytics:google-ads-performance-over-time` | Daily time series for one or more metrics | --account-id, --start-date, --end-date |
| `analytics:google-ads-search-terms` | Search terms with per-term metrics | --account-id, --start-date, --end-date |
| `analytics:google-ads-shopping` | Shopping campaign product performance | --account-id, --start-date, --end-date |
| `analytics:google-ads-summary` | Google Ads headline KPIs — current vs previous period | --account-id, --start-date, --end-date |

**Campaigns & Labels (5)**

| Command | Purpose | Required |
|---------|---------|----------|
| `analytics:campaigns-labels-breakdown` | Per-campaign and per-label totals, current vs previous period | --start-date, --end-date |
| `analytics:campaigns-labels-insights-breakdown` | Daily time series per campaign and per label | --start-date, --end-date |
| `analytics:campaigns-labels-posts` | Per-post table for the selected campaigns & labels | --start-date, --end-date |
| `analytics:campaigns-labels-summary` | Campaign & label summary KPIs — current vs previous period | --start-date, --end-date |
| `analytics:campaigns-labels-top-posts` | Top 5 posts per network for the selected campaigns & labels | --start-date, --end-date |

### Analytics: reports, schedules, share links

Reporting is asynchronous. `reports:generate` returns an id straight away and
the work happens elsewhere, so never treat the create response as a finished
report — poll `reports:get <id> --wait`, or pass `--callback-url` to be told
instead of asking. A report is done when `status` is `completed` and
`export_url` is populated; `failed` is terminal too, and `reports:retry` re-runs
it from the stored definition without rebuilding the request.

Start from `reports:options` rather than guessing: it returns the report types
this workspace can build and the sections each one accepts, and it is the same
catalogue the product's own section selector reads.

**The two competitor types take a competitor set, not accounts.**
`facebook_competitor` and `instagram_competitor` are built from a saved set, so
they need `--competitor-report-id` (from `competitor-reports:list`) and ignore
`--accounts`. Putting the set id in `--accounts` is the natural mistake and is
refused before the call goes out — it used to be accepted, dropped, and surface
minutes later as "Combined report generation failed".

**Share links are how a client sees a report without an account.** Create one
with `share-links:create`; `--password` protects it, `--date-range` pins the
period so the numbers stop moving, and omitting the range leaves it rolling.
There is no expiry — a link lives until you disable or delete it, so prefer
`share-links:disable` (reversible) over `share-links:delete` when a client
engagement pauses. A share link is independent of any generated report: it shows
the live dashboard, not a PDF.

`report-schedules:run` asks for an immediate send, but the API acknowledges the
request without returning a report id. Confirm with `report-schedules:get` and
check `last_run_at` moved before telling the user the report went out.

### Analytics: competitors

Two different things share the word "report". A **competitor report** is a saved
*set* of competitors to benchmark against — it has no status and produces no
file. The comparison numbers are read separately, with `competitors:compare`.

Provisioning order matters: `competitors:search` first, because a competitor is
an object (`competitor_id` plus `name`), not a bare id. `competitor-reports:create`
accepts the shorthand `--competitors 'id:Name,id:Name'` or a JSON array, and
expands it for you.

A page that cannot be tracked comes back as an empty result with a `reason` —
that is a successful read, not an error. Tell the user which page could not be
tracked and why, rather than reporting a failure.

`competitor-reports:update` **replaces** the set, so send every competitor you
want to keep, not just the new one.

When reading comparisons, respect each row's `state`. Only `Processed` means a
complete measurement for the period — a competitor in any other state has zeros
that mean *not measured*, not *zero engagement*. Never present those as a result.

---

## Examples

### Verify the stored key is valid

```bash
contentstudio --json auth:whoami
# → {"ok": true, "data": {"id": "...", "email": "...", "full_name": "..."}}
```

### Find a Facebook account to post to

```bash
contentstudio --json accounts:list --platform facebook --per-page 10
# Pick an _id, e.g. <account_id>
```

### Post-creation examples

Always preview a mutating post with `--dry-run` first — it returns `{"ok": true, "data": {"dry_run": true, "endpoint": "...", "body": {...}}}` and never touches the API. Drop `--dry-run` to actually create.

**1. Plain text draft**

```bash
contentstudio --json posts:create \
  -c "Our new blog is live!" \
  -i <account_id> \
  -t draft
```

**2. Text + single image, scheduled with a date**

```bash
contentstudio --json posts:create \
  -c "Our new blog is live! https://example.com/post" \
  -i <account_id> \
  -t scheduled \
  -s "2026-05-01 10:00:00" \
  -m https://example.com/hero.jpg
```

**3. Text + multiple images** (repeat `-m`)

```bash
contentstudio --json posts:create \
  -c "Gallery drop 📸" \
  -i <account_id> \
  -t scheduled \
  -s "2026-05-02 09:00:00" \
  -m https://example.com/1.jpg \
  -m https://example.com/2.jpg \
  -m https://example.com/3.jpg
```

**4. Text + video**

```bash
contentstudio --json posts:create \
  -c "Watch our launch reel 🎬" \
  -i <account_id> \
  -t scheduled \
  -s "2026-05-03 12:00:00" \
  --video-url https://example.com/launch.mp4
```

**5. Queued post** (goes into the publishing queue; no explicit time)

```bash
contentstudio --json posts:create \
  -c "Filler post for the queue" \
  -i <account_id> \
  -t queued
```

**6. Content-category post** (accounts come from the category — NO `--account`)

```bash
# Find a category id first:
contentstudio --json categories:list
# --content-category-id is required for -t content_category:
contentstudio --json posts:create \
  -c "Evergreen tip of the day" \
  -t content_category \
  --content-category-id <category_id>
```

**7. Post with an approval workflow** (two approvers, all must approve)

```bash
contentstudio --json posts:create \
  -c "Quarterly results announcement" \
  -i <account_id> \
  -t scheduled \
  -s "2026-05-05 08:00:00" \
  --approver <user_id_1> \
  --approver <user_id_2> \
  --approve-option everyone \
  --approval-notes "Legal + comms must both sign off"
```

**8. Post with labels and a campaign** (repeat `--label`)

```bash
contentstudio --json posts:create \
  -c "Spring sale kickoff" \
  -i <account_id> \
  -t scheduled \
  -s "2026-05-06 10:00:00" \
  --label <label_id_1> \
  --label <label_id_2> \
  --campaign-id <campaign_id>
```

**9. Facebook colored-background text post** (plain text, no media)

```bash
# Get a valid background id first:
contentstudio --json facebook:text-backgrounds
contentstudio --json posts:create \
  -c "Big news coming soon!" \
  -i <facebook_account_id> \
  -t draft \
  --facebook-background-id <background_id>
```

**10. Facebook CAROUSEL** (Facebook only; 2–10 cards) — preview then create

```bash
# Preview:
contentstudio --json posts:create --dry-run \
  -c "Shop the new collection" \
  -i <facebook_account_id> \
  -t scheduled \
  -s "2026-07-01 10:00:00" \
  --facebook-carousel '{"cards":[{"image":"https://e.com/1.jpg","link":"https://e.com/p1","title":"Tee","description":"100% cotton"},{"image":"https://e.com/2.jpg","link":"https://e.com/p2","title":"Hoodie"},{"image":"https://e.com/3.jpg","link":"https://e.com/p3","title":"Cap"}],"call_to_action":"SHOP_NOW","end_card":true,"end_card_url":"https://e.com/shop"}'
# Drop --dry-run to create. The CLI adds "is_carousel_post": true.
```

A carousel and a colored-background text post (`--facebook-background-id`, example 9) are two different Facebook formats — use one or the other, not both in the same post. The FB account ID goes in `-i / --account`.

**11. Threads multi-thread** (Threads only; max 10 chained items) — preview then create

```bash
contentstudio --json posts:create --dry-run \
  -c "🧵 A thread on shipping CLIs" \
  -i <threads_account_id> \
  -t draft \
  --threads '[{"message":"1/ Start small."},{"message":"2/ Ship a demo.","media":["https://e.com/demo.mp4"]},{"message":"3/ Iterate in public."}]'
# Drop --dry-run to create. The CLI adds "has_multi_threads": true.
```

The top-level `-c / --content` is the lead post; each `--threads` item is a chained reply, in order. Don't repeat the lead text in the items (number them `1/`, `2/`, … as the continuation). Each item needs `message` or `media`.

**12. Post with a first comment** (auto-posted comment after publish; e.g. "link in bio") — preview then create

```bash
contentstudio --json posts:create --dry-run \
  -c "New drop is live 🎉" \
  -i <account_id> \
  -t draft \
  --first-comment "🔗 link in bio" \
  --first-comment-account <account_id>
# Drop --dry-run to create. --first-comment-account is REQUIRED by the backend
# and must be a subset of the -i / --account IDs, else the API returns a 422.
```

**13. Twitter/X threaded tweets** (Twitter only; max 10 tweets) — preview then create

```bash
contentstudio --json posts:create --dry-run \
  -c "Why we built a CLI 🧵" \
  -i <twitter_account_id> \
  -t draft \
  --twitter '[{"message":"1/ Start with the contract."},{"message":"2/ Show, don'\''t tell.","media":["https://e.com/x.jpg"]},{"message":"3/ Ship it."}]'
# Drop --dry-run to create. The CLI adds "has_threaded_tweets": true.
# Twitter rule: no mixed media in one tweet (no images+video together), max 1 video per tweet.
```

The top-level `-c / --content` is the lead tweet; each `--twitter` item is a follow-up tweet in the chain, in order. Don't repeat the lead text in the items (number the items `1/`, `2/`, … as the continuation). Each item needs `message` or `media`. The Twitter account ID goes in `-i / --account`.

**14. Full-control body via `--body <file.json>`** (any field the shortcut flags don't cover)

Use `--body` when you need fields beyond the shortcut flags (per-platform `platform_overrides`, `twitter_options`/`threads_options`, `timezone`, `hide_client`, etc.). The JSON is sent verbatim, so build it for the platform(s) your `accounts` belong to — a Facebook-carousel body, a Threads body, and a Twitter body are separate posts, not one combined payload.

```jsonc
// /tmp/post.json — a Facebook carousel via the full body schema
{
  "content": { "text": "Shop the collection" },
  "accounts": ["<facebook_account_id>"],
  "scheduling": { "publish_type": "scheduled", "scheduled_at": "2026-07-01 10:00:00" },
  "facebook_options": {
    "carousel": {
      "is_carousel_post": true,
      "cards": [
        { "image": "https://e.com/1.jpg", "link": "https://e.com/p1", "title": "Tee" },
        { "image": "https://e.com/2.jpg", "link": "https://e.com/p2", "title": "Hoodie" }
      ],
      "call_to_action": "SHOP_NOW",
      "end_card": true,
      "end_card_url": "https://e.com/shop"
    }
  },
  "labels": ["<label_id>"],
  "campaign_id": "<campaign_id>",
  "approval": { "approvers": ["<user_id>"], "approve_option": "anyone", "notes": "please review" }
}
```

```bash
contentstudio --json posts:create --body /tmp/post.json
```

For a Threads or Twitter/X thread, use a body with that account and the matching block instead — e.g. `{ "content": {...}, "accounts": ["<threads_account_id>"], "scheduling": {...}, "threads_options": { "has_multi_threads": true, "multi_threads": [...] } }` (or `twitter_options.threaded_tweets` for Twitter/X).

### Schedule a post at the best time

```bash
# 1. Ask for the best slots. Omit --account for every connected account.
contentstudio --json scheduling:best-times --global-slots 3
# → data.meta.timezone            e.g. "Asia/Karachi"
#   data.global.top_recommendations[0]  {rank: 1, day: "Wednesday",
#                                        date: "2026-08-19", time: "14", score: 100}
#   data.meta.missing_entities     accounts with too little history (skipped)

# 2. Narrow it to the account you're actually posting to.
#    <platform>:<account_id> — both from one accounts:list row.
contentstudio --json scheduling:best-times \
  --account facebook:<account_id> --per-account-slots 3

# 3. Show the user the ranked slots and let them pick. Then schedule at that
#    slot's date + hour AS-IS — the times are already workspace-local, so
#    converting to UTC would move the post.
contentstudio --json posts:create \
  -c "Launch day is here." \
  -i <account_id> \
  -t scheduled \
  -s "2026-08-19 14:00:00" \
  --dry-run

# 4. Drop --dry-run once the user approves the time and the text.
```

If `data.global` is `null`, the workspace has too little history — don't report an
error. Say which accounts were skipped (`meta.missing_entities`) and offer to
schedule at a time the user chooses instead.

### Generate an image and publish it (two steps)

```bash
# 0. Optional: see what is available. Both are configuration, so cache them.
contentstudio --json images:models
contentstudio --json images:tools

# 1. Show the user the prompt first — generating costs an image credit.
contentstudio --json images:generate \
  -p "Flat-lay of autumn coffee beans on linen, warm daylight" \
  --dimensions square_hd --dry-run

# 2. Generate. Takes seconds; --json gives you data.media_id.
MEDIA_ID=$(contentstudio --json images:generate \
  -p "Flat-lay of autumn coffee beans on linen, warm daylight" \
  --dimensions square_hd | jq -r '.data.media_id')

# 3. Attach it. media_id goes in as --media-id, unchanged.
contentstudio --json posts:create \
  -c "Autumn blend is back." -i <account_id> -t draft \
  --media-id "$MEDIA_ID" --dry-run

# 4. Drop --dry-run once the user approves the image and the text. That creates a
#    draft; to send it instead, swap `-t draft` for
#    `-t scheduled -s "YYYY-MM-DD HH:MM:SS"`. There is no publish-now type —
#    --publish-type takes scheduled|draft|queued|content_category.
```

If `media_id` comes back `null`, read `persist_error`: the image exists at `data.url`
but is not in the media library, so `posts:create --media-id` has nothing to take.
Either fix the cause (`media_storage_full` → free up storage) or use the URL now,
before the provider link expires.

Editing and chaining work the same way — the `url` of one result is the input to the next:

```bash
# Edit an existing image (the prompt describes the change, not the whole picture)
contentstudio --json images:generate \
  -p "Make the background a snowy street at dusk" \
  --image-url https://example.com/base.png

# Clean up a product shot, then restage it
URL=$(contentstudio --json images:remove-background \
        --image-url https://example.com/mug.png | jq -r '.data.url')
contentstudio --json images:product-image --product-image-url "$URL" \
  --instructions "on a marble kitchen counter, morning light"

# A tool's own controls — the escape hatch reaches every field the API declares
contentstudio --json images:tool image-to-image --body '{
  "prompt": "same mug, editorial magazine styling",
  "attachments": ["https://example.com/mug.png"],
  "aspect_ratio": "4:5"
}' --dry-run
```

Only ever pass URLs the image service can download. To use a local file, upload it first:

```bash
URL=$(contentstudio --json media:upload --file ./mug.png | jq -r '.data.url')
contentstudio --json images:upscale --image-url "$URL"
```

### List recent draft posts

```bash
contentstudio --json posts:list --status draft --per-page 5
```

### Delete a post (and from social)

```bash
contentstudio --json posts:delete <post_id> --delete-from-social
```

### Add an internal note on a post (private)

```bash
contentstudio --json comments:add <post_id> "Double-check the link" --note
```

### Override workspace for a single call

```bash
contentstudio --json --workspace <other_ws_id> posts:list --per-page 3
```

### Triage the inbox: find unanswered DMs and reply to one

```bash
# 1. Cheap check first — is there anything to do?
contentstudio --json inbox:summary

# 2. List open conversations
contentstudio --json inbox:list --type conversation --action all --limit 20
# → per row: element_ref, platform, platform_id,
#            element_details.element_id  ← THIS is the conversation id

# 3. Read the thread. Use element_details.element_id (looks like t_1234...),
#    NOT element_ref — element_ref here returns an empty list.
contentstudio --json inbox:messages t_10000000000000001 --sort-order desc --limit 10

# 4. Find the account that owns the thread (gives you --platform-id)
contentstudio --json accounts:list --platform facebook

# 5. Preview the reply — ALWAYS do this, and show the text to the user
contentstudio --json inbox:send <conversation_id> \
  --platform-type facebook \
  --platform-id <account_id> \
  --message "Hi! Your order shipped this morning — tracking is on the way." \
  --dry-run

# 6. Only after the user approves, drop --dry-run
```

### Reply to a comment, then hide a spam one

```bash
# Threaded reply. <post_id> is element_details.post_id, not element_ref.
contentstudio --json inbox:comment-add <post_id> \
  --platform-type facebook --platform-id <account_id> \
  --comment-id <comment_id> \
  --message "Thanks for the kind words!" --dry-run

# Hide spam rather than deleting it (reversible)
contentstudio --json inbox:comment-hide <comment_id> --dry-run
```

### Clear a batch of conversations

```bash
contentstudio --json inbox:update \
  --element <element_ref_1> --element <element_ref_2> \
  --status done --dry-run
```

### Tag a conversation for follow-up

```bash
contentstudio --json inbox:tags                       # find or create a tag id
contentstudio --json inbox:tag-attach <element_ref> \
  --tag <tag_id> --platform-id <account_id> --inbox-type conversation --dry-run
```

---

## Error handling

| `error.type` | `http_status` | Typical hint |
|--------------|---------------|--------------|
| `AuthError` | 401, 403 | Run `auth:login` with a valid key. |
| `NotFoundError` | 404 | The resource doesn't exist or isn't in this workspace. |
| `ValidationError` | 422 | Flattened Laravel-style field errors from the API. |
| `ConflictError` | 409 | Resource already exists, or a send's delivery outcome is undetermined. Verify before retrying a send. |
| `RateLimitError` | 429 | Wait a moment and retry. On the AI image commands the bucket is 30/min and needs the full minute. |
| `CreditLimitError` | 403 | Out of AI image credits (`images:*`). Top up or wait for the cycle; nothing was charged. Re-running `auth:login` cannot fix it. |
| `BackendError` | 5xx or network | Retry after a short backoff. |
| `ConfigError` | — (local) | Missing API key / workspace; run `auth:login` or pass flags. |

---

## When NOT to use this skill

- The user is asking about running their own ContentStudio backend (Laravel source); this CLI only talks to the deployed API.
- Tasks not exposed by the v1 API (e.g., billing changes, first-time social account connection — those happen in the ContentStudio web UI).

---

The authoritative version for this skill is the `version:` field in the
frontmatter at the top of this file.