contentstudio

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

has_api_key

false

, ask the user for their ContentStudio API key. They can generate one from ContentStudio Dashboard → Settings → API Keys. Then:

bash

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

Then verify a workspace is selected:

bash

contentstudio --json workspaces:current

active_workspace_id

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

posts:create

posts:delete

posts:approve

posts:reject

comments:add

media:upload

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

Pattern:

Run
```
contentstudio --json workspaces:current
```
to see what's active.
Tell the user: "Your active workspace is <name>
(
```
<id>
```
). Do you want to connect/post/delete in this workspace, or a different one?"
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).
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:

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?"
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.
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:

Run

contentstudio --json workspaces:list --per-page 50

(high default to often avoid pagination)

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:

Run

contentstudio --json posts:list --status draft --per-page 1

to peek at

total

Run

contentstudio --json posts:list --status draft --per-page <total>

to get them all

Iterate over
```
data[]
```
and delete each
Never delete just the first page and report "done"

User: "show me my Facebook accounts" Agent should:

Use
```
--platform facebook
```
filter — usually returns 0 or a handful, no pagination concern
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

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

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

--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:

Run
```
platforms:list
```
to see what's supported and which method each uses (
```
oauth
```
/
```
credentials
```
/
```
manual
```
).
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.
For Bluesky, ask the user for their handle + app-password (link them to https://bsky.app/settings/app-passwords) and call
```
accounts:add-bluesky
```
.

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 --body /path/to/body.json`	Create a post with full JSON body
`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:

draft

scheduled

queued

content_category

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

Lookup tables

Command	Purpose
`campaigns:list`	List campaigns (folders)
`categories:list`	List content categories
`labels:list`	List labels
`team:list`	List workspace team members

Facebook helpers

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

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>

Safely preview a post before creating it

bash

contentstudio --json posts:create --dry-run \
  -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
# Returns: {"ok": true, "data": {"dry_run": true, "endpoint": "...", "body": {...}}}

Actually create the post (drop --dry-run)

bash

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

Create a post with a complex body (platform options, approval workflow)

Write a JSON body and pass via

--body

jsonc

{
  "content": {
    "text": "Hello world",
    "media": {"images": ["https://example.com/img.jpg"]}
  },
  "accounts": ["<account_id>"],
  "scheduling": {
    "publish_type": "scheduled",
    "scheduled_at": "2026-05-01 10:00:00"
  },
  "first_comment": {"message": "🔗 link in bio", "accounts": ["<account_id>"]},
  "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

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

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.
`RateLimitError`	429	Wait a moment and retry.
`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).

Version

1.0.0

contentstudio

NPX Install

Tags

SKILL.md Content

Install ContentStudio CLI if it doesn't exist

⚠️ Authentication Required

Invocation rules for agents

Confirm the target workspace before mutating actions

Pagination — be proactive, don't silently truncate

Quick decision tree for the agent

Examples

Endpoints that paginate

Command Reference

Authentication

Workspaces

Social accounts (read + connect)

Posts

Comments / Internal notes

Media library

Lookup tables

Facebook helpers

Examples

Verify the stored key is valid

Find a Facebook account to post to

Safely preview a post before creating it

Actually create the post (drop --dry-run)

Create a post with a complex body (platform options, approval workflow)

List recent draft posts

Delete a post (and from social)

Add an internal note on a post (private)

Override workspace for a single call

Error handling

When NOT to use this skill

Version