---
url: /cli.md
---

# CLI

The `@socialized.dev/cli` runs the whole publish loop from a terminal or a CI
job: it wraps the multipart upload, dispatches the publication, and optionally
watches each target settle. Same `/api/v1` the dashboard runs on — one command
instead of the [multi-step REST upload](/quickstart#rest-api-quickstart-curl).

## Install

```sh
npm install -g @socialized.dev/cli
```

This installs the `socialized.dev` command. Run `--help` to list every command:

```sh
socialized.dev --help
```

[`@socialized.dev/cli` on npm](https://www.npmjs.com/package/@socialized.dev/cli)

## Authenticate

Create an API key on the [Developer page](https://dash.socialized.dev/developer),
then store it locally:

```sh
socialized.dev login --key sk_…

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

`login` verifies the key against the API and, when the account has exactly one
brand, selects it for you. The key is written to
`~/.config/socialized.dev/config.json` (honouring `XDG_CONFIG_HOME`), with file
mode `0600`.

```sh
socialized.dev whoami   # API URL, selected brand, connected platforms
socialized.dev logout   # clear the stored config
```

### Headless 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` | API host. Defaults to `https://api.socialized.dev/api/v1`. |

```sh
SOCIALIZED_DEV_API_KEY=sk_… socialized.dev brands list
```

Each value resolves **flag → environment → stored config**, so a `--brand` flag
beats `SOCIALIZED_DEV_BRAND_ID`, which beats the brand saved by `brands use`.

## Brands

A brand is the publishing identity that owns the connections and the
publications. List the brands a key can reach, then pin the default:

```sh
socialized.dev brands list          # id ⇥ name ⇥ connected platforms
socialized.dev brands use brand_…   # accepts an id or the exact brand name
```

After `brands use`, publication commands no longer need `--brand`. You can skip
it entirely when the key (or `SOCIALIZED_DEV_BRAND_ID`) already resolves to a
single brand, and override it per call with `--brand` on any publication
command.

## Publish

`publications create` is the whole loop in one command. Pass local file paths and
the CLI uploads them as assets first; pass an existing `asset_…` id to reuse one
and skip the upload.

```sh
socialized.dev publications create \
  --video ./clip.mp4 \
  --cover ./cover.jpg \
  --to youtube,instagram \
  --title "Launch clip" \
  --description "Posted once, everywhere." \
  --watch
```

| Flag | |
| --- | --- |
| `--video` | Local video path **or** an `asset_…` id. Required. |
| `--cover` | Local cover-image path or an `asset_…` id. Optional. |
| `--to` | Comma-separated platforms, e.g. `youtube,instagram,facebook`. |
| `--title` | Publication title. Required. |
| `--description` | Publication description. Optional. |
| `--brand` | Brand id, overriding the stored default. |
| `--idempotency-key` | Reuse a key so a retried create is safe; one is generated otherwise. |
| `--watch` | Poll until every target reaches a final state. |
| `--json` | Print the raw JSON response instead of the summary. |

## Inspect

Read a publication back, or watch one settle:

```sh
socialized.dev publications get pub_…              # one-shot summary
socialized.dev publications status pub_… --watch   # poll until final
```

Both accept `--brand` and `--json`. With `--watch`, `status` blocks until the
publication reaches `done`, `partial`, or `failed` — useful as the last step of a
CI job that should fail when a target does.

## Scripting

Every read command takes `--json` and writes to stdout, so results pipe straight
into `jq` or a downstream step:

```sh
socialized.dev publications status pub_… --json | jq '.publication.status'
```

For the asset / publication / target model these commands drive, see
[Publishing a video](/publishing); for the endpoints underneath, the
[REST API reference](https://api.socialized.dev/reference).