ContentStudio's CLI

1. Installation

Install the CLI globally using npm or pnpm — whichever you already use.

npm install -g contentstudio-cli
# or if you prefer pnpm
pnpm install -g contentstudio-cli

contentstudio --version
contentstudio --help

npx skills add d4interactive/contentstudio-agent

2. Authentication

Before running any commands, you need to authenticate with your ContentStudio API key.

Persist your key (recommended for local use)

contentstudio auth:login --api-key cs_xxxxxxxxxxxxxxxx

contentstudio auth:status         # shows stored config (key is redacted)
contentstudio --json auth:whoami  # validates key against the API

3. Selecting a Workspace

Most commands are scoped to a workspace. Set your active workspace once and the CLI remembers it for all future commands.

contentstudio --json workspaces:list

contentstudio workspaces:use <workspace_id>

contentstudio workspaces:current

Need to switch workspace for just one command? Use the --workspace flag inline — it won't change your saved default:

contentstudio --workspace <other_workspace_id> accounts:list

4. Exploring Your Workspace

Before creating posts, you'll want to know which accounts, campaigns, labels, and team members are available in your workspace.

Connected social accounts

contentstudio --json accounts:list                       # all accounts
contentstudio --json accounts:list --platform facebook   # filter by platform
contentstudio --json accounts:list --search "barcelona"  # search by name

Valid --platform values: facebook, linkedin, twitter, instagram, youtube, tiktok, pinterest, gmb.

Campaigns, labels, categories, team members

contentstudio --json campaigns:list    # folders / campaigns
contentstudio --json categories:list   # content categories
contentstudio --json labels:list       # labels
contentstudio --json team:list         # team members

All of these support --page, --per-page, and --search filters.

5. Connecting Social Accounts

There are three ways to connect new accounts, depending on the platform.

OAuth platforms (Facebook, LinkedIn, Twitter, Instagram, YouTube, TikTok, Pinterest, GMB, Threads, Tumblr)

contentstudio --json accounts:connect facebook

To reconnect an account that has expired or gone invalid:

contentstudio --json accounts:connect facebook --reconnect --account-id <existing_account_id>

Available platform values: facebook, facebook-profile, instagram, instagram-via-facebook, twitter, linkedin, pinterest, tiktok, youtube, threads, gmb, tumblr.

Bluesky (no browser needed)

contentstudio --json accounts:add-bluesky \
  --handle yourname.bsky.social \
  --app-password xxxx-xxxx-xxxx-xxxx

Facebook Groups (manual)

contentstudio --json accounts:add-facebook-group \
  --name "My Community Group" \
  --image https://example.com/group-cover.jpg   # image URL is optional

All three connect methods support --dry-run to preview the payload without calling the API.

6. Creating Posts

There are two ways to create a post — shortcut flags for simple cases, or a full JSON body for platform-specific options.

Shortcut flags (simple posts)

# Scheduled post to a Facebook page with one image
contentstudio posts:create \
  -c "Our latest blog post is live!" \
  -i <account_id> \
  -t scheduled \
  -s "2026-05-01 10:00:00" \
  -m https://example.com/hero.jpg

Posting to multiple accounts at once

Repeat the -i flag for each account:

contentstudio posts:create \
  -c "Cross-platform announcement 🚀" \
  -i <facebook_id> \
  -i <linkedin_id> \
  -i <twitter_id> \
  -t scheduled \
  -s "2026-05-01 09:00:00"

Using media from your library

# Find a media ID
contentstudio --json media:list --type images

# Reference it by ID in your post
contentstudio posts:create \
  -c "Post with library asset" \
  -i <account_id> \
  -t draft \
  --media-id <media_library_id>

Full body via JSON file (for advanced / platform-specific options)

For TikTok privacy settings, YouTube categories, GMB topic types, approval workflows, first comments, labels, and campaigns — write a JSON body file and pass it with --body:

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

Full JSON schema:

{
  "content": {
    "text": "Hello world",
    "media": {
      "images": ["https://example.com/img.jpg"],
      "video": "https://example.com/clip.mp4",
      "media_ids": ["<media_library_id>"]
    }
  },
  "accounts": ["<account_id>"],
  "post_type": "reel+story",
  "post_video_title": "My Video Title",
  "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"
  },
  "youtube_options":   { "title": "...", "privacy_status": "public", "category": "EDUCATION", "tags": ["tag1"], "license": "youtube", "made_for_kids": false },
  "tiktok_options":    { "privacy_level": "PUBLIC_TO_EVERYONE", "disable_comment": false, "disable_duet": false, "disable_stitch": false, "auto_add_music": false },
  "pinterest_options": { "title": "...", "link": "https://..." },
  "gmb_options":       { "topic_type": "EVENT", "start_date": "2026-05-01", "end_date": "2026-05-02", "title": "...", "action_type": "BOOK", "cta_link": "https://..." }
}

contentstudio --json posts:create --dry-run \
  -c "Test" -i <account_id> -t scheduled -s "2026-05-01 10:00"

7. Platform-Specific Examples

Facebook

contentstudio --json posts:create \
  -c "Big news for our community 🎉" \
  -i <facebook_page_id> \
  -t scheduled \
  -s "2026-05-01 10:00:00" \
  -m https://example.com/announcement.jpg

# Facebook Reels or Stories — add --post-type
contentstudio posts:create \
  -c "Behind-the-scenes" \
  -i <facebook_id> \
  -t scheduled \
  -s "2026-05-01 10:00:00" \
  --video-url https://example.com/clip.mp4 \
  --post-type reel+story

LinkedIn

contentstudio --json posts:create \
  -c "Excited to share our Q2 roadmap" \
  -i <linkedin_id> \
  -t scheduled \
  -s "2026-05-01 09:00:00" \
  -m https://example.com/roadmap.png

Twitter / X

contentstudio --json posts:create \
  -c "New release shipped 🚀" \
  -i <twitter_id> \
  -t scheduled \
  -s "2026-05-01 10:00:00" \
  -m https://example.com/preview.png

Instagram (feed, reel, story)

# Feed post
contentstudio posts:create \
  -c "Caption with #hashtags" \
  -i <instagram_id> \
  -t scheduled -s "2026-05-01 10:00:00" \
  -m https://example.com/photo.jpg \
  --post-type feed

# Reel
contentstudio posts:create \
  -c "" \
  -i <instagram_id> \
  -t scheduled -s "2026-05-01 10:00:00" \
  --video-url https://example.com/reel.mp4 \
  --post-type reel

# Story
contentstudio posts:create \
  -c "" \
  -i <instagram_id> \
  -t scheduled -s "2026-05-01 10:00:00" \
  -m https://example.com/story.jpg \
  --post-type story

YouTube (Videos & Shorts)

YouTube requires youtube_options — use a JSON body file:

cat > /tmp/yt-post.json <<'JSON'
{
  "content": {
    "text": "Description shown under the video",
    "media": {"video": "https://example.com/clip.mp4"}
  },
  "accounts": ["<youtube_id>"],
  "post_type": "shorts",
  "post_video_title": "How we built ContentStudio CLI",
  "scheduling": {"publish_type": "scheduled", "scheduled_at": "2026-05-01 10:00:00"},
  "youtube_options": {
    "title": "How we built ContentStudio CLI",
    "privacy_status": "public",
    "category": "EDUCATION",
    "tags": ["cli", "automation", "social-media"],
    "license": "youtube",
    "made_for_kids": false
  }
}
JSON
contentstudio --json posts:create --body /tmp/yt-post.json

TikTok

cat > /tmp/tt-post.json <<'JSON'
{
  "content": {
    "text": "Quick demo #fyp #tutorial",
    "media": {"video": "https://example.com/tiktok.mp4"}
  },
  "accounts": ["<tiktok_id>"],
  "scheduling": {"publish_type": "scheduled", "scheduled_at": "2026-05-01 10:00:00"},
  "tiktok_options": {
    "privacy_level": "PUBLIC_TO_EVERYONE",
    "disable_comment": false,
    "disable_duet": false,
    "disable_stitch": false,
    "auto_add_music": false,
    "brand_content_toggle": false,
    "disclose_commercial_content": false,
    "is_aigc": false
  }
}
JSON
contentstudio --json posts:create --body /tmp/tt-post.json

Pinterest

cat > /tmp/pin-post.json <<'JSON'
{
  "content": {
    "text": "Check out our spring guide",
    "media": {"images": ["https://example.com/pin.jpg"]}
  },
  "accounts": ["<pinterest_id>"],
  "scheduling": {"publish_type": "scheduled", "scheduled_at": "2026-05-01 10:00:00"},
  "pinterest_options": {
    "title": "Spring 2026 Style Guide",
    "link": "https://example.com/spring-guide"
  }
}
JSON
contentstudio --json posts:create --body /tmp/pin-post.json

Google Business Profile

cat > /tmp/gmb-post.json <<'JSON'
{
  "content": {
    "text": "Join our grand opening event",
    "media": {"images": ["https://example.com/event.jpg"]}
  },
  "accounts": ["<gmb_account_id>"],
  "scheduling": {"publish_type": "scheduled", "scheduled_at": "2026-05-01 10:00:00"},
  "gmb_options": {
    "topic_type": "EVENT",
    "start_date": "2026-05-15",
    "end_date": "2026-05-16",
    "title": "Grand Opening",
    "action_type": "BOOK",
    "cta_link": "https://example.com/rsvp"
  }
}
JSON
contentstudio --json posts:create --body /tmp/gmb-post.json

8. Managing Posts

Listing posts

contentstudio --json posts:list                                           # all recent
contentstudio --json posts:list --status draft --per-page 5
contentstudio --json posts:list --status scheduled --status published
contentstudio --json posts:list --date-from 2026-04-01 --date-to 2026-04-30

Deleting a post

# Delete from ContentStudio only
contentstudio --json posts:delete <post_id>

# Also delete from the connected social platforms
contentstudio --json posts:delete <post_id> --delete-from-social

# Limit cross-platform delete to a specific account
contentstudio --json posts:delete <post_id> --account <account_id> --delete-from-social

# Preview without deleting
contentstudio --json posts:delete <post_id> --dry-run

Approving or rejecting posts

contentstudio --json posts:approve <post_id> --comment "LGTM, ship it"
contentstudio --json posts:reject  <post_id> --comment "fix the link first"

# Preview without acting
contentstudio --json posts:approve <post_id> --dry-run

9. Comments & Internal Notes

# List all comments and notes on a post
contentstudio --json comments:list <post_id>

# Add a public comment
contentstudio --json comments:add <post_id> "Great work team!"

# Add an internal note (not visible publicly)
contentstudio --json comments:add <post_id> "Double-check the link before publishing" --note

# Mention team members
contentstudio --json comments:add <post_id> "Heads up" --mention <user_id> --mention <user_id>

# Preview without posting
contentstudio --json comments:add <post_id> "test" --note --dry-run

10. Media Library

Listing assets

contentstudio --json media:list                                           # all assets
contentstudio --json media:list --type images --sort recent --per-page 20
contentstudio --json media:list --type videos
contentstudio --json media:list --search "campaign-2026"

Valid --sort values: recent, oldest, size, a2z, z2a.

Uploading assets

# Upload a local file
contentstudio --json media:upload --file ./hero.jpg

# Import from an external URL
contentstudio --json media:upload --url https://example.com/asset.mp4

# Optionally put it in a specific folder
contentstudio --json media:upload --file ./hero.jpg --folder-id <folder_id>

# Preview without uploading
contentstudio --json media:upload --url https://example.com/img.jpg --dry-run

The upload response includes an _id you can pass as --media-id when creating posts.

11. Automation Workflows

Copy-paste ready scripts for common scenarios.

Schedule a daily post for the next 7 days

#!/bin/bash
ACCOUNT="<facebook_page_id>"
CONTENT=(
  "Monday motivation 💪"
  "Tuesday tips: keep it simple"
  "Wednesday wisdom from the team"
  "Throwback Thursday"
  "Friday vibes 🎉"
  "Weekend prep — try this"
  "Sunday reflections"
)

for i in "${!CONTENT[@]}"; do
  DATE=$(date -d "+$((i+1)) day 09:00" '+%F %T')
  contentstudio --json posts:create \
    -c "${CONTENT[$i]}" \
    -i "$ACCOUNT" \
    -t scheduled \
    -s "$DATE"
done

Cross-platform campaign (same post, multiple platforms)

#!/bin/bash
TIME="2026-05-01 10:00:00"

FB=$(contentstudio --json accounts:list --platform facebook | jq -r '.data[0]._id')
LI=$(contentstudio --json accounts:list --platform linkedin | jq -r '.data[0]._id')
TW=$(contentstudio --json accounts:list --platform twitter  | jq -r '.data[0]._id')

contentstudio --json posts:create \
  -c "Big launch today 🚀" \
  -i "$FB" -i "$LI" -i "$TW" \
  -t scheduled \
  -s "$TIME" \
  -m https://example.com/launch.jpg

Bulk-delete drafts older than 30 days

#!/bin/bash
CUTOFF=$(date -d '-30 days' '+%Y-%m-%d')

contentstudio --json posts:list --status draft --date-to "$CUTOFF" --per-page 100 \
  | jq -r '.data[]._id' \
  | while read id; do
      contentstudio --json posts:delete "$id"
    done

Upload a folder of images, one post per image

#!/bin/bash
ACCOUNT="<instagram_id>"

for img in ./photos/*.jpg; do
  RESP=$(contentstudio --json media:upload --file "$img")
  MEDIA_ID=$(echo "$RESP" | jq -r '.data._id')

  TIME=$(date -d "+1 hour" '+%F %T')
  contentstudio --json posts:create \
    -c "$(basename "$img" .jpg)" \
    -i "$ACCOUNT" \
    -t scheduled \
    -s "$TIME" \
    --media-id "$MEDIA_ID" \
    --post-type feed
done

Auto-approve posts from a trusted creator

#!/bin/bash
TRUSTED_USER_ID="<user_id>"

contentstudio --json posts:list --status pending_approval --per-page 50 \
  | jq -r --arg u "$TRUSTED_USER_ID" '.data[] | select(.created_by == $u) | ._id' \
  | while read id; do
      contentstudio --json posts:approve "$id" --comment "auto-approved (trusted creator)"
    done

12. JSON Output (for scripts & agents)

Every command supports --json. The response always has the same shape, making it easy to pipe into jq or handle in scripts.

// Success
{ "ok": true, "data": <payload> }

// Error
{
  "ok": false,
  "error": {
    "type": "AuthError",
    "message": "Invalid or revoked API key",
    "http_status": 401,
    "hint": "Run `contentstudio auth:login --api-key cs_...` to set a valid API key."
  }
}

Always check both ok and the process exit code (non-zero on error).

13. Error Reference

The CLI uses typed errors with specific exit codes so your scripts can handle failures cleanly.

14. Quick Reference

# ── Authentication ─────────────────────────────────────────────────────
contentstudio auth:login --api-key cs_...        # Persist key + verify
contentstudio auth:status                        # Show local config
contentstudio --json auth:whoami                 # Validate against API
contentstudio auth:logout                        # Forget credentials

# ── Workspaces ──────────────────────────────────────────────────────────
contentstudio --json workspaces:list             # List all workspaces
contentstudio workspaces:use <workspace_id>      # Set active workspace
contentstudio workspaces:current                 # Show active workspace

# ── Discovery ───────────────────────────────────────────────────────────
contentstudio --json accounts:list [--platform] [--search]
contentstudio --json campaigns:list
contentstudio --json categories:list
contentstudio --json labels:list
contentstudio --json team:list

# ── Posts ───────────────────────────────────────────────────────────────
contentstudio --json posts:list [--status] [--date-from] [--date-to]
contentstudio --json posts:create -c "text" -i <id> -t draft
contentstudio --json posts:create --body /path/to/post.json
contentstudio --json posts:create [...] --dry-run          # preview only
contentstudio --json posts:delete <post_id> [--delete-from-social]
contentstudio --json posts:approve <post_id> [--comment "..."]
contentstudio --json posts:reject  <post_id> [--comment "..."]

# ── Comments / Notes ────────────────────────────────────────────────────
contentstudio --json comments:list <post_id>
contentstudio --json comments:add  <post_id> "message" [--note] [--mention <id>]

# ── Media ───────────────────────────────────────────────────────────────
contentstudio --json media:list [--type images|videos] [--sort recent]
contentstudio --json media:upload --file <path>
contentstudio --json media:upload --url <url>

# ── Global flags ────────────────────────────────────────────────────────
contentstudio --version
contentstudio --help
contentstudio <command> --help
contentstudio --json ...                         # JSON envelope output
contentstudio --workspace <id> ...              # Per-call workspace override
contentstudio --base-url <url> ...              # Per-call API URL override

15. API Endpoints

The CLI wraps these 20 endpoints from the ContentStudio v1 public API. Base URL: https://api.contentstudio.io/api/v1

Full OpenAPI spec: api.contentstudio.io/api-docs.json  ·  Human-readable docs: api.contentstudio.io/guide  ·  npm: contentstudio-cli  ·  GitHub: d4interactive/contentstudio-agent