Bundle

intent

so-me.studio is a unified CLI for scheduling posts, managing inbox conversations, generating AI-driven captions and images, querying analytics, and managing media across 10+ social platforms (twitter/x, linkedin, instagram, facebook, tiktok, youtube, threads, whatsapp, pinterest, dribbble). use this skill when you need to automate social content workflows, batch-schedule across platforms, triage inbound messages with templates, or pull engagement metrics. the skill is built on the so-me CLI tool and requires valid api authentication before any command runs.

inputs

required environment / auth:

• SOMESTUDIO_API_KEY: api key from https://app.so-me.studio/settings/api-keys. export as env var or authenticate via so-me auth:login (browser oauth or explicit key). all commands return 401 without valid credentials.

required external connection:

• so-me.studio app account (sign up at https://so-me.studio) with at least one connected social account (twitter, linkedin, instagram, facebook, tiktok, youtube, threads, whatsapp, pinterest, or dribbble).

cli prerequisite:

• @so-me/cli installed globally: npm install -g @so-me/cli or pnpm install -g @so-me/cli (https://www.npmjs.com/package/@so-me/cli).

data inputs (vary by command):

• post text, platform enum (uppercase: TWITTER, LINKEDIN, INSTAGRAM, FACEBOOK, TIKTOK, YOUTUBE, THREADS, WHATSAPP, PINTEREST, DRIBBBLE).
• scheduled-at: iso 8601 utc timestamp, strictly in the future.
• account ids, post ids, conversation ids, draft ids (obtained from prior list/get calls, never invented).
• file paths for media upload (image, video).
• whatsapp requires pre-approved template names.

procedure

step 1: verify authentication and list connected accounts

• input: none (env var SOMESTUDIO_API_KEY already set or browser oauth session active).
• command: so-me auth:status (returns current auth state).
• output: json object with user id, org id, auth method.
• next: if 401, stop and direct user to regenerate key at app.so-me.studio/settings/api-keys or run so-me auth:login.
• command: so-me accounts:list (always list before posting to avoid invented ids).
• output: json array of connected accounts with platform, account-id, handle, name.
• decision: if no accounts connected, stop; user must connect accounts at app.so-me.studio first.

step 2: determine intent and select command family

• input: user's request (e.g. "schedule a post", "reply to that dm", "generate a caption").
• process: match request against decision tree in "decision points" section below.
• output: identified command family and required parameters.

step 3: for text/caption generation (ai:generate-text)

• input: prompt string, optional platform (e.g. TWITTER, LINKEDIN).
• command: so-me ai:generate-text --prompt "<prompt>" --platform <PLATFORM>.
• output: json object { "text": "...", "tokens_used": N }.
• edge case: if user has no remaining ai credits, response is 402 with { "error": "quota_exceeded", "type": "ai_credits" }. surface remaining balance from so-me settings:usage.

step 4: for image generation (ai:generate-image)

• input: prompt string, optional style keywords.
• command: so-me ai:generate-image --prompt "<prompt>".
• output: json object { "image_url": "...", "s3_prefix": "...", "file_src": "...", "tokens_used": N }.
• edge case: 402 if credits exhausted. no retry without purchasing credits.

step 5: for video generation (ai:generate-video)

• input: prompt string (e.g. "avatar speaks product announcement").
• command: so-me ai:generate-and-schedule --prompt "<prompt>" --platform <P> --scheduled-at <ISO> or standalone so-me ai:generate-video --prompt "<prompt>".
• output: json video metadata with s3_prefix, file_src, duration.
• edge case: video generation typically consumes more credits; check so-me settings:usage first.

step 6: for posting / scheduling (posts:create or posts:schedule)

• input: text (string), platform enum, optional media file ids (from prior media:upload), optional scheduled-at (iso 8601 utc timestamp in future), optional account-id (if multiple same-platform accounts).
• command (immediate publish): so-me posts:create --text "<text>" --platform <PLATFORM> --account-id <ID> (publishes now).
• command (scheduled): so-me posts:create --text "<text>" --platform <PLATFORM> --scheduled-at <ISO> --account-id <ID>.
• output: json post object { "id": "...", "status": "POSTED" or "SCHEDULED", "scheduled_at": "...", ... }.
• pre-check: confirm iso timestamp is in the future. if past, command returns 422 "scheduledAt must be in the future".
• edge case: if workspace requires approval, status is "PENDING_APPROVAL" not "SCHEDULED". do not override; inform user approval is pending.
• edge case: 429 rate limit (too many posts in short window). back off 30s and retry once.

step 7: for drafts (drafts:create, drafts:convert)

• input: text, platform, optional media, optional account-id.
• command (create): so-me drafts:create --text "<text>" --platform <PLATFORM> --account-id <ID>.
• output: json draft object { "id": "...", "status": "DRAFT", ... }.
• command (convert to scheduled): so-me drafts:convert <draftId> --scheduled-at <ISO>.
• output: json post object { "id": "...", "status": "SCHEDULED", ... }.
• use drafts when user is uncertain; drafts are reversible.

step 8: for inbox / dm management (inbox:list-conversations, inbox:reply, inbox:list-saved-replies)

• input: optional status filter (open, closed), optional conversation-id, optional reply message text.
• command (list): so-me inbox:list-conversations --status open.
• output: json array { "id": "...", "platform": "...", "handle": "...", "last_message": "...", ... }.
• command (get messages): so-me inbox:get-messages <conversationId> --limit 5.
• output: json array of messages with timestamps, sender, content.
• command (reply): so-me inbox:reply <conversationId> --message "<text>".
• output: json reply object { "id": "...", "status": "SENT", ... }.
• command (list saved replies): so-me inbox:list-saved-replies.
• output: json array { "id": "...", "title": "...", "content": "...", ... }.
• edge case: whatsapp conversations outside 24-hour customer-service window require pre-approved templates; check so-me whatsapp:list-templates first.

step 9: for comments (comments:list, comments:add)

• input: post-id, optional limit, optional reply text.
• command (list): so-me comments:list <postId> --limit 10.
• output: json array of comment objects { "id": "...", "author": "...", "content": "...", "timestamp": "...", ... }.
• command (add): so-me comments:add <postId> --content "<text>".
• output: json comment object { "id": "...", "status": "POSTED", ... }.

step 10: for media (media:upload)

• input: file path (image or video).
• command: so-me media:upload ./path/to/file.png.
• output: json object { "s3_prefix": "...", "file_src": "...", "mime_type": "...", ... }.
• use returned file_src in subsequent posts:create or ai:generate-and-schedule commands.
• edge case: file size limits vary by platform; large video files may timeout. if upload hangs, check network or try smaller file.

step 11: for analytics (analytics:platform, analytics:post)

• input: account-id, optional days (default 7), or post-id.
• command: so-me analytics:platform <accountId> --days 7.
• output: json analytics object { "impressions": N, "engagements": N, "followers_gained": N, ... }.
• command: so-me analytics:post <postId>.
• output: json post-level metrics { "impressions": N, "likes": N, "comments": N, "shares": N, ... }.
• edge case: some platforms (e.g. whatsapp) have limited analytics; response may be sparse.

step 12: for approvals (approvals:list, approvals:approve, approvals:reject)

• input: optional approval-id.
• command: so-me approvals:list.
• output: json array { "id": "...", "post_id": "...", "status": "PENDING", "requested_by": "...", ... }.
• command (approve): so-me approvals:approve <approvalId>.
• output: json approval object { "status": "APPROVED", ... }.
• command (reject): so-me approvals:reject <approvalId>.
• output: json approval object { "status": "REJECTED", ... }.

step 13: for whatsapp (whatsapp:send-template)

• input: phone number, template name (pre-approved in workspace), optional template variables.
• command: so-me whatsapp:list-templates (list available templates first).
• output: json array { "name": "...", "status": "APPROVED", "variables": [...], ... }.
• command: so-me whatsapp:send-template --phone <number> --template-name "<name>" --variables <var1>,<var2>,....
• output: json message object { "id": "...", "status": "SENT", ... }.
• edge case: only approved templates work; custom text requires pre-approval from whatsapp.

step 14: for usage / settings (settings:usage)

• input: none.
• command: so-me settings:usage.
• output: json object { "ai_credits_remaining": N, "api_quota_remaining": N, "workspace": "...", ... }.
• use this to diagnose 402 quota exhaustion errors.

step 15: chain multi-step workflows

• pattern: ai:generate-text → posts:create, or media:upload → posts:create, or ai:generate-image → media:upload → posts:create.
• method: pipe json output through jq to extract ids for the next call.
• example: img_src=$(so-me ai:generate-image --prompt "..." | jq -r .file_src); so-me posts:create --text "..." --platform TWITTER --media-file-src "$img_src" --scheduled-at <ISO>.
• each command emits structured json; inspect exit code. non-zero = failure (surface error detail).

decision points

if user says "schedule a post" / "publish at" / "queue for X":

• use so-me posts:create --text "<text>" --platform <P> --scheduled-at <ISO> --account-id <ID>.
• confirm iso timestamp is in the future before running.
• if workspace enforces approval, post will enter PENDING_APPROVAL status. inform user.

if user says "draft" / "save for later":

• use so-me drafts:create --text "<text>" --platform <P> --account-id <ID>.
• drafts are editable and reversible. convert to scheduled post later with so-me drafts:convert <draftId> --scheduled-at <ISO>.

if user says "post failed" / "retry":

• use so-me posts:retry <postId>.
• only works if post status is FAILED. if status is already POSTED or SCHEDULED, use posts:schedule or posts:unschedule instead.

if user says "approval pending" / "approve" / "reject":

• use so-me approvals:list to find pending posts.
• use so-me approvals:approve <approvalId> or so-me approvals:reject <approvalId>.
• only workspace admins can approve; inform user if they lack permission.

if user says "reply to that DM" / "message that person":

• use so-me inbox:list-conversations --status open to find conversation.
• extract conversation-id using jq.
• use so-me inbox:reply <conversationId> --message "<text>".
• if whatsapp and outside 24-hour window, first check so-me whatsapp:list-templates and use pre-approved template.

if user says "what comments are on..." / "show me replies":

• use so-me comments:list <postId>.
• optionally filter by limit: --limit 10.
• to add a reply, use so-me comments:add <postId> --content "<text>".

if user says "write me a caption" / "give me a hook" / "generate text":

• use so-me ai:generate-text --prompt "<prompt>" --platform <P>.
• if no platform specified, omit --platform flag.
• output is { "text": "...", "tokens_used": N }.
• if 402 response, user is out of ai credits. check so-me settings:usage.

if user says "make me an image" / "create a graphic":

• use so-me ai:generate-image --prompt "<prompt>".
• output includes s3_prefix and file_src; use file_src in subsequent posts:create.
• if 402, credits exhausted.

if user says "make a ugc video" / "avatar speaks..." / "generate video":

• use so-me ai:generate-and-schedule --prompt "<prompt>" --platform <P> --scheduled-at <ISO>, which generates and schedules in one call.
• or use standalone so-me ai:generate-video --prompt "<prompt>" to generate without scheduling (then reference file_src later).
• video generation is credit-intensive. check so-me settings:usage before running.

if user says "metrics" / "engagement" / "analytics":

• use so-me analytics:platform <accountId> --days 7 for account-level metrics.
• use so-me analytics:post <postId> for individual post performance.
• if multi-account setup, specify account-id explicitly; omit to aggregate (if supported by api).

if user says "save this reply for next time" / "create template":

• use so-me inbox:create-saved-reply --title "<title>" --content "<text>".
• retrieve later with so-me inbox:list-saved-replies.

if user says "list connected accounts" / "what platforms am i on":

• use so-me accounts:list.
• output: json array with account-id, platform, handle, name.
• always run this before posting to avoid invented ids.

if user says "whatsapp template message":

• first run so-me whatsapp:list-templates to confirm template exists and is approved.
• use so-me whatsapp:send-template --phone <number> --template-name "<name>".
• if no approved templates, inform user whatsapp only allows templated messages outside 24-hour customer-service window.

if api returns 401 (unauthorized):

• api key is invalid, expired, or not exported.
• action: regenerate key at app.so-me.studio/settings/api-keys. export: export SOMESTUDIO_API_KEY=sk_live_.... or run so-me auth:login.

if api returns 402 (quota exceeded):

• user has exhausted ai credits or api request quota.
• action: run so-me settings:usage to surface remaining balance. suggest workspace upgrade.

if api returns 422 (validation error):

• request body has invalid fields (e.g. scheduled-at in past, wrong platform enum, missing required field).
• action: surface the specific field error from response body. re-run with corrected inputs.

if api returns 429 (rate limit):

• user is posting / requesting too frequently.
• action: back off 30 seconds. retry once. if persistent, inform user to slow request rate.

if api returns 5xx (backend error):

• so-me.studio backend is experiencing issues.
• action: retry once after 5s. if persistent, surface error to user and suggest checking https://status.so-me.studio or contacting support.

if network timeout during long-running operation (e.g. video generation):

• increase timeout or restart command. do not blindly retry; check if prior command actually succeeded by querying list endpoint (e.g. so-me posts:list).

if multi-account same-platform (e.g. 2 linkedin pages):

• pass --account-id <ID> to all commands to avoid ambiguity.
• omit --account-id only if user explicitly says "all accounts" (then loop via bash: for id in $(so-me accounts:list | jq -r '.data[] | select(.platform=="LINKEDIN") | .id'); do ...).

if user wants immediate publish vs. draft vs. scheduled:

• posts:create without --scheduled-at flag publishes immediately (risky; prefer drafts if unsure).
• drafts:create is safe; convert later with drafts:convert.
• posts:create --scheduled-at <future ISO> schedules safely.

output contract

successful command execution:

• all commands emit json on stdout (default --json flag).
• example post:create success: { "id": "post_abc123", "status": "SCHEDULED", "platform": "TWITTER", "scheduled_at": "2026-04-26T17:00:00Z", "text": "...", "created_at": "2026-04-25T10:30:00Z" }.
• example ai:generate-text success: { "text": "caption here", "tokens_used": 45 }.
• example accounts:list success: { "data": [ { "id": "acct_xyz", "platform": "TWITTER", "handle": "@myhandle", "name": "My Twitter" }, ... ], "total": 2 }.

file output (if applicable):

• media:upload returns s3_prefix and file_src; no local file written.
• no skill output is written to disk; all results are json stdout.

error responses:

• http errors return json: { "error": "<message>", "code": "<code>", "status": <http_code> }.
• example 401: { "error": "Invalid API key", "code": "UNAUTHORIZED", "status": 401 }.
• example 422: { "error": "scheduledAt must be in the future", "code": "VALIDATION_ERROR", "status": 422 }.
• example 429: { "error": "Rate limit exceeded. Retry after 30s", "code": "RATE_LIMITED", "status": 429 }.

data persistence:

• scheduled posts, drafts, sent messages, and saved replies persist in so-me.studio workspace.
• api credits and quota limits are workspace-level and persistent.
• no local caching or state file.

outcome signal

user knows the skill worked when:

• auth: so-me auth:status returns user id and org id (not 401).
• account listing: so-me accounts:list returns array of >= 1 connected account with platform, handle, id.
• post scheduled: posts:create --scheduled-at <ISO> returns json post object with status="SCHEDULED" and scheduled_at matching the input timestamp. post appears in "scheduled" tab of so-me.studio app.
• post published immediately: posts:create (no --scheduled-at) returns status="POSTED" and post is live on target platform within 5s.
• draft saved: drafts:create returns status="DRAFT" and draft appears in drafts list at app.so-me.studio/drafts.
• ai caption generated: ai:generate-text returns json with .text field populated (not empty string).
• ai image generated: ai:generate-image returns json with .file_src field (url to generated image).
• dm reply sent: inbox:reply <conversationId> returns status="SENT" and reply appears in conversation thread within 5s.
• analytics fetched: analytics:platform <accountId> returns json object with impressions, engagements, and other metrics (non-null, non-zero for active accounts).
• media uploaded: media:upload ./file.png returns json with s3_prefix and file_src (url to uploaded file on s3).
• approval action: approvals:approve <approvalId> or :reject returns status="APPROVED" or "REJECTED" and post status transitions accordingly.
• whatsapp template sent: whatsapp:send-template returns status="SENT" and message is received on target phone within 10s (in active customer-service window).
• quota check: settings:usage returns object with ai_credits_remaining >= 0 and api_quota_remaining >= 0 (or null if unlimited).

failure signals:

• any http error code (401, 402, 422, 429, 5xx) indicates skill did not complete. surface the error message to user.
• 401 = re-authenticate. 402 = upgrade workspace. 422 = fix input. 429 = retry after delay. 5xx = backend outage.
• cli exit code != 0 always means failure; stderr contains json error object.

---

credits: original so-me.studio cli documentation and api reference. enriched for implexa skill standard (intent, inputs, procedure, decision points, output contract, outcome signal) with explicit edge cases (rate limits, approval workflows, whatsapp templates, multi-account handling, quota exhaustion) and common gotchas.