Scripting & Automation

The CLI is built for automation: it prints structured JSON by default, accepts credentials from environment variables, and uses standard exit codes. Every command maps 1:1 to a Social media studio REST endpoint, so anything the app can do is scriptable.

The binary is so-me (the development build is so-me-dev). All examples below use so-me. Subcommands use colon syntax — posts:list, media:upload, agent export-tools.

Output Modes

Output formatting is controlled by global flags that apply to every command. They must be placed on the command line alongside the rest of your arguments (Commander treats them as global options).

Flag	Description
`--json`	Output as pretty-printed JSON. This is the default — you rarely need to pass it explicitly.
`--table`	Render results as a human-readable ASCII table instead of JSON.
`--verbose`	On failure, print full error details (including the JS stack trace where available).

# JSON is the default
so-me posts:list

# Explicit JSON (same as above)
so-me posts:list --json

# Human-readable table
so-me posts:list --table

# Verbose error output (useful while debugging)
so-me posts:create -c "test" --platform INVALID --verbose

Use --table for humans, not scripts. The table view truncates long fields and selects a subset of columns, so it is not machine-parseable. Always pipe the default JSON into jq in automation.

The default format can also be persisted in the CLI config (outputFormat), but --table on the command line always wins for that invocation.

JSON Output & jq

Pipe any command into jq for extraction and transformation.

List endpoints return a paginated envelope, not a bare array. The shape is { "data": [ ... ], "meta": { ... } }, so you must index into .data[]. Single-object commands (posts:get, posts:create, posts:update, …) return the object directly, so fields like .id are at the top level.

# Get the text of every scheduled post (note the .data[] — list responses are paginated)
so-me posts:list --status SCHEDULED | jq '.data[].text'

# Grab the first post's ID
so-me posts:list | jq -r '.data[0].id'

# posts:create returns a single object, so .id is top-level
POST_ID=$(so-me posts:create -c "Hello!" --platform TWITTER | jq -r '.id')
echo "Created post: $POST_ID"

# Count posts by platform
so-me posts:list | jq '.data | group_by(.socialMedia)
  | map({platform: .[0].socialMedia, count: length})'

# Read pagination metadata
so-me posts:list --limit 100 | jq '.meta'

Pagination

List commands accept two pagination flags. There is no --cursor or --all flag on list commands — paginate by incrementing --page.

Flag	Default	Notes
`--page <number>`	`1`	1-based page number.
`--limit <number>`	varies by command	Items per page. `posts:list` caps at `100`; defaults differ per command (e.g. `posts:list`/`drafts:list` default to `20`, `accounts:list`/`inbox:list`/`teams:list` default to `50`).

# Second page of 50 posts
so-me posts:list --page 2 --limit 50

# Walk every page until an empty data array comes back
page=1
while :; do
  rows=$(so-me posts:list --page "$page" --limit 100 | jq -c '.data')
  [ "$rows" = "[]" ] && break
  echo "$rows" | jq -r '.[].id'
  page=$((page + 1))
done

The --all flag exists only on agent export-tools, where it means “emit every tool format” — it is unrelated to pagination.

Shell Scripting

Create and Schedule

#!/bin/bash
set -euo pipefail

# Create a post (publishes immediately when no -s/--date is given), then schedule it
POST_ID=$(so-me posts:create \
  -c "Automated post from CI" \
  --platform LINKEDIN \
  | jq -r '.id')

so-me posts:schedule "$POST_ID" \
  -s "$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)"

echo "Post $POST_ID scheduled"

posts:create resolves the social account automatically from --platform when you do not pass -a/--accounts. If multiple accounts match, the command prompts interactively — so in non-interactive CI, pass an explicit account ID with -a or rely on having a single connected account for that platform.

Bulk Delete Failed Posts

#!/bin/bash
set -euo pipefail

# Collect failed post IDs (remember: .data[] for list responses)
FAILED_IDS=$(so-me posts:list --status FAILED --limit 100 | jq -r '.data[].id')

if [ -z "$FAILED_IDS" ]; then
  echo "No failed posts found"
  exit 0
fi

# posts:delete accepts one or many IDs and -y skips the confirmation prompt
echo "$FAILED_IDS" | xargs so-me posts:delete -y

Convert All Drafts

#!/bin/bash
set -euo pipefail

# Convert every draft into a scheduled Twitter post
DRAFT_IDS=$(so-me drafts:list --limit 100 | jq -r '.data[].id')

for id in $DRAFT_IDS; do
  so-me drafts:convert "$id" \
    --platform TWITTER \
    --post-type TEXT \
    -s "$(date -u -d '+2 hours' +%Y-%m-%dT%H:%M:%SZ)"
  echo "Converted draft $id"
done

Authentication for CI

The CLI looks for credentials in this order: the --api-key flag, then the SOME_API_KEY environment variable, then the API key stored by auth:login. For automation, prefer the environment variable so nothing is written to disk.

Variable	Flag equivalent	Description
`SOME_API_KEY`	`--api-key <key>`	API key used to authenticate every request.
`SOME_API_URL`	`--api-url <url>`	API base URL. Defaults to `https://api.so-me.studio` (`so-me-dev` defaults to `http://localhost:8000`).

# Authenticate purely from the environment — no auth:login needed
export SOME_API_KEY="sk_live_xxx"
so-me auth:whoami        # verify the key and show the authenticated user + org
so-me posts:list

# Or pass per-command (overrides stored credentials and the env var)
so-me posts:list --api-key sk_live_xxx --api-url https://api.so-me.studio

GitHub Actions

name: Schedule Weekly Post
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM UTC

jobs:
  post:
    runs-on: ubuntu-latest
    steps:
      - name: Install CLI
        run: npm install -g @social-media-scheduler/cli

      - name: Create and schedule post
        env:
          SOME_API_KEY: ${{ secrets.SOME_API_KEY }}
        run: |
          so-me posts:create \
            -c "Weekly update: check out what's new!" \
            --platform TWITTER \
            -s "$(date -u -d '+1 hour' +%Y-%m-%dT%H:%M:%SZ)"

Store your API key as a repository secret (SOME_API_KEY). The CLI reads it from the environment automatically — never bake the key into a workflow file or commit it to the repo.

Error Handling

Exit Codes

On failure the CLI sets a non-zero exit code (process.exitCode = 1), so &&, set -e, and if guards behave as expected.

Code	Meaning
`0`	Success
`1`	Error — API error, validation failure, network error, missing credentials, etc.

Verbose Errors

Use --verbose to see full error details, including the stack trace where one is available:

so-me posts:create -c "test" --platform INVALID --verbose

Common error conditions surfaced by the API client:

HTTP status	CLI message
`401`	`Invalid API key. Run 'so-me auth:login' or set SOME_API_KEY.` (server-specific messages are preserved when more informative)
`403`	`Insufficient permissions. Your plan may not include this feature.`
`429`	`Rate limit exceeded. Try again later.`
network	`Could not connect to API at <url>. Check your internet connection.`

Rate Limit Handling

A rate-limited request (HTTP 429) exits with code 1. In scripts, add retry-with-backoff logic:

#!/bin/bash
MAX_RETRIES=3
RETRY_DELAY=10

for i in $(seq 1 $MAX_RETRIES); do
  so-me posts:list && break
  echo "Request failed, retrying in ${RETRY_DELAY}s... (attempt $i/$MAX_RETRIES)"
  sleep $RETRY_DELAY
done

Agent Tool Definitions

The CLI can export the Social media studio tool catalog in formats consumable by AI agent frameworks. agent export-tools fetches the canonical tool list live from the MCP server (a tools/list JSON-RPC call to POST /mcp) and emits it in the format you choose. The MCP server is the single source of truth, so exported definitions always match the live catalog.

so-me agent export-tools --format <format> [options]

string

One of mcp, openai, anthropic, hermes, openclaw. Required unless --all is passed.

string

Write the output to a file (and write any companion files alongside it). If the path looks like a directory (no file extension, or a trailing slash), the format’s default filename is appended. When omitted, the primary output is written to stdout.

boolean

default:"false"

Emit every supported format. Treats --out as a directory (defaults to ./agent-tools) and writes each format into its own subdirectory.

Supported Formats

Format	Primary output	Default filename	Companion files
`mcp`	Raw MCP catalog (`{ "tools": [...] }`)	`tools.mcp.json`	—
`openai`	OpenAI Chat Completions function-calling tools (`{ "tools": [{ "type": "function", "function": { ... } }] }`)	`tools.openai.json`	—
`anthropic`	Anthropic Messages API tools (flat shape with `input_schema`)	`tools.anthropic.json`	—
`hermes`	OpenAI-compatible tool JSON (Nous Hermes 4)	`tools.json`	`system_prompt.md`, `tools.md`
`openclaw`	Markdown skill reference (grouped tool tables + full JSON-schema appendix)	`tools.md`	—

Examples

# Print the raw MCP tool catalog to stdout
so-me agent export-tools --format mcp

# Write OpenAI-style function definitions to a file
so-me agent export-tools --format openai --out tools.openai.json

# Write the Anthropic tool-use format
so-me agent export-tools --format anthropic --out tools.anthropic.json

# Hermes kit — writes tools.json plus companion system_prompt.md and tools.md
so-me agent export-tools --format hermes --out ./hermes/

# OpenClaw skill reference (markdown). Writes tools.md when --out is a directory
so-me agent export-tools --format openclaw --out tools.md

# Emit every format. Each lands in its own subdirectory under ./agent-tools,
# e.g. ./agent-tools/mcp/tools.mcp.json, ./agent-tools/hermes/tools.json, etc.
so-me agent export-tools --all --out ./agent-tools

Every format is derived from the same tools/list response, so exported definitions stay in sync with the live tool catalog. Tool names are snake_case (e.g. create_post) and mirror the CLI’s resource:verb commands. Over the MCP transport the same tools register as mcp_so-me-studio_<tool_name> (e.g. mcp_so-me-studio_create_post).

Self-Hosted Instances

Point the CLI at a custom API URL via the flag or the environment variable:

# Via flag (per command)
so-me posts:list --api-url https://api.yourdomain.com

# Via environment variable (whole session)
export SOME_API_URL=https://api.yourdomain.com
so-me posts:list

Getting Started

Publishing

AI Studio

Inbox & Engagement

Analytics

Biolink

Team & Collaboration

Settings & Billing

Webhooks

Support

Output Modes

JSON Output & jq

Shell Scripting

Create and Schedule

Bulk Delete Failed Posts

Convert All Drafts

Authentication for CI

GitHub Actions

Error Handling

Exit Codes

Verbose Errors

Rate Limit Handling

Agent Tool Definitions

Supported Formats

Examples

Self-Hosted Instances

​Output Modes

​JSON Output & jq

​Pagination

​Shell Scripting

​Create and Schedule

​Bulk Delete Failed Posts

​Convert All Drafts

​Authentication for CI

​GitHub Actions

​Error Handling

​Exit Codes

​Verbose Errors

​Rate Limit Handling

​Agent Tool Definitions

​Supported Formats

​Examples

​Self-Hosted Instances

Output Modes

JSON Output & jq

Pagination

Shell Scripting

Create and Schedule

Bulk Delete Failed Posts

Convert All Drafts

Authentication for CI

GitHub Actions

Error Handling

Exit Codes

Verbose Errors

Rate Limit Handling

Agent Tool Definitions

Supported Formats

Examples

Self-Hosted Instances