Skip to content

CLI ​

The @socialized.dev/cli drives the whole /api/v1 from a terminal, a CI job or an agent. Every API operation is a command, generated from the API reference’s spec, and publications create wraps the multi-step upload for you.

Built for scripts and agents first: a command prints its result as JSON on stdout, a failure as one JSON line on stderr (exit 1), and nothing ever prompts. The one interactive step is login without a key: it waits up to three minutes for you to approve in the browser, even when stdin isn’t a terminal, so an agent can run it and leave the approval to you.

Install ​

Terminal: install
npm install -g @socialized.dev/cli
socialized.dev --help

@socialized.dev/cli on npm

Authenticate ​

Terminal: log in
socialized.dev login

login opens the dashboard in your browser. Approve there (signing in first if you need to) and the dashboard hands the CLI a new API key for your team: every brand, able to upload, publish and manage webhooks. It shows on the Developer page, where you can revoke it.

On a remote or headless machine, create a key on the Developer page and give it to login instead:

Terminal: log in with a key
socialized.dev login --key sk_…

# or pipe it, so the key stays out of your shell history
echo sk_… | socialized.dev login

Either way, login verifies the key against the API and, when the key reaches exactly one brand, stores it as the default. The config is written to ~/.config/socialized.dev/config.json (honouring XDG_CONFIG_HOME), with file mode 0600.

Terminal: check and clear the login
socialized.dev whoami   # the API, the default brand, and the brands the key reaches
socialized.dev logout   # clear the stored config

Headless and CI ​

No stored config is needed — read everything from the environment instead:

VariablePurpose
SOCIALIZED_DEV_API_KEYAPI key for every request.
SOCIALIZED_DEV_BRAND_IDDefault brand for brand-scoped commands.
SOCIALIZED_DEV_API_URLThe API’s origin. Defaults to https://api.socialized.dev.
SOCIALIZED_DEV_DASHBOARD_URLWhere login sends the browser. Defaults to https://dash.socialized.dev.
Terminal: a command in CI
SOCIALIZED_DEV_API_KEY=sk_… socialized.dev brands list

Commands ​

One command per operation: publications.create is socialized.dev publications create. Each path parameter, query parameter and top-level body field is a flag (videoAssetId → --video-asset-id); a field that isn’t text, a number or a boolean takes JSON. Two commands describe the rest:

Terminal: describe the commands
socialized.dev commands                    # every command and its summary
socialized.dev schema publications create  # its flags, request body and output, as JSON Schema

Every generated command also takes (the hand-written login, logout, whoami, brands use and assets upload don’t):

FlagWhat it does
--bodyThe whole JSON request body: inline, @file, or - for stdin. Field flags override it.
--dry-runPrint the request instead of sending it.
--yesRequired by every DELETE.
--idempotency-keyOn publications create: reuse a key so a retry answers with the publication the first call created. A fresh one is sent otherwise.

Brand-scoped commands default --brand-id to the stored brand. Pin it with:

Terminal: pin a brand
socialized.dev brands list
socialized.dev brands use --brand brand_…   # an id or the exact brand name

Publish ​

Terminal: publish
socialized.dev publications create \
  --video ./clip.mp4 \
  --cover ./cover.jpg \
  --title "Launch clip" \
  --description "Posted once, everywhere." \
  --targets '[{ "platform": "youtube" }, { "platform": "instagram" }]'

--video and --cover upload local files first. To reuse an uploaded asset, pass --video-asset-id or --cover-asset-id instead.

--targets is the destinations, each a platform and its optional options (described in Publications & targets, and in full by socialized.dev schema publications create). A YouTube target, scheduled, with tags:

Terminal: a scheduled YouTube target
socialized.dev publications create \
  --video ./explainer.mp4 \
  --title "How tides work" \
  --targets '[{
    "platform": "youtube",
    "options": {
      "tags": ["tides", "moon", "physics"],
      "categoryId": "27",
      "publishAt": "2026-10-02T17:00:00+01:00"
    }
  }]'

A caption is an asset too. Upload it, then name it in the YouTube options (captions and playlists need the extra permission described in Captions and playlists):

Terminal: upload a caption
socialized.dev assets upload --file ./explainer.en.srt   # {"assetId": "asset_…"}
The YouTube target naming it
{ "platform": "youtube", "options": { "captions": [{ "assetId": "asset_…", "language": "en" }] } }

Inspect ​

Terminal: read a publication
socialized.dev publications get --id pub_…           # one read
socialized.dev publications get --id pub_… --watch   # read every 2 seconds until it settles

With --watch, get logs each state to stderr and prints the publication once it reaches done, partial or failed — useful as the last step of a CI job. A caption or playlist that didn’t land is listed in its target’s warnings.

Terminal: list and retry
socialized.dev publications list --filter attention          # newest first, 50 a page
socialized.dev publications list --cursor "$NEXT_CURSOR"     # the next page
socialized.dev publications retry-failed --filter attention  # every failure a retry can send

list answers with every filter’s counts and the view’s failures, as the API does.

Failures ​

A failure is one JSON line on stderr, with the API’s error code and message, and the HTTP status:

A failure on stderr
{"error":{"code":"PlatformNotConnectedError","message":"…","platform":"youtube","status":422,"idempotencyKey":"…"}}

UsageError means the invocation was wrong and nothing was sent; NetworkError means no response came back, so a write may have landed. A failed publications create reports the idempotencyKey it sent: retry with --idempotency-key and the same assets (--video-asset-id, from the upload’s log) to replay it rather than publish twice.

For the asset / publication / target model, see Publishing a video; for the endpoints underneath, the REST API reference.

The API is the product; the dashboard is its best-known client.