Appearance
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 --helpAuthenticate
Terminal: log in
socialized.dev loginlogin 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 loginEither 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 configHeadless and CI
No stored config is needed — read everything from the environment instead:
| Variable | Purpose |
|---|---|
SOCIALIZED_DEV_API_KEY | API key for every request. |
SOCIALIZED_DEV_BRAND_ID | Default brand for brand-scoped commands. |
SOCIALIZED_DEV_API_URL | The API’s origin. Defaults to https://api.socialized.dev. |
SOCIALIZED_DEV_DASHBOARD_URL | Where login sends the browser. Defaults to https://dash.socialized.dev. |
Terminal: a command in CI
SOCIALIZED_DEV_API_KEY=sk_… socialized.dev brands listCommands
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 SchemaEvery generated command also takes (the hand-written login, logout, whoami, brands use and assets upload don’t):
| Flag | What it does |
|---|---|
--body | The whole JSON request body: inline, @file, or - for stdin. Field flags override it. |
--dry-run | Print the request instead of sending it. |
--yes | Required by every DELETE. |
--idempotency-key | On 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 namePublish
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 settlesWith --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 sendlist 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.