Socifyr CLI reference
The socifyr CLI posts to your connected social accounts from a terminal or a CI job. It is a thin wrapper over the TypeScript SDK, so every command maps to one REST API call you can also make with cURL.
What commands does the Socifyr CLI have?
| Command | What it does | Page |
|---|---|---|
socifyr configure | Save API key, workspace ID and API URL | configure |
socifyr connections (alias conn) | List accounts and their slugs | connections |
socifyr connections refresh <slug> | Renew an account token | connections |
socifyr connections reconnect <slug> | Get a one-time re-authorization link | connections |
socifyr post [text] | Publish, schedule or draft text, images, video, documents | post |
socifyr schedule <file.csv> | Bulk-schedule text posts from a CSV | schedule |
socifyr status <id> | Check a post, optionally wait | status |
socifyr edit <id> | Change a draft or scheduled post | edit, retry, publish |
socifyr retry <id> | Re-queue failed channels | edit, retry, publish |
socifyr publish <id> | Publish a saved draft | edit, retry, publish |
socifyr media list / upload / get / delete | Manage the media library | media |
socifyr analytics followers / accounts | Follower growth and account comparison | analytics |
socifyr usage | Usage against your plan limits | usage |
Run socifyr --help or socifyr <command> --help for the built-in help.
How do I install and configure the CLI?
npm install -g @socifyr/cli
socifyr configure --key sk_... --workspace <workspaceId>
socifyr connectionsThe unscoped package socifyr installs the same binary. Details are on the installation page. Create the API key in the dashboard under API Keys; see API keys.
Where does the CLI read its settings from?
Each setting is resolved in this order, first match wins:
- Environment variable
~/.socifyr/config.json, written bysocifyr configure- Built-in default (API URL only)
| Setting | Env var | Config key | Default |
|---|---|---|---|
| API key | SOCIFYR_API_KEY | apiKey | none, required |
| Workspace ID | SOCIFYR_WORKSPACE_ID | workspaceId | none, required |
| API URL | SOCIFYR_API_URL | apiUrl | https://api.socifyr.com/api |
Every command except configure needs both an API key and a workspace ID. If one is missing the CLI prints how to set it and exits with code 1.
How do I get machine-readable output?
Every command except configure takes --json and prints the API response as formatted JSON to stdout. Progress messages ("Uploading banner.png...", "Waiting for results...") go to stderr, so piping stdout into jq stays clean:
socifyr post "Hello" --to x-myhandle --json | jq -r '.id'configure is the only command without --json.
What exit codes does the CLI return?
| Code | Meaning |
|---|---|
0 | The command ran. This includes a --wait that ended in failed or partial_failure: the CLI reports the post result but does not turn it into a non-zero exit. |
1 | Missing configuration, a missing file, invalid flag values, an API error (auth, validation, usage limit, not found), a timeout while waiting, or a usage error from the argument parser. |
The CLI has no other exit codes. To fail a CI step when a post did not fully publish, read the status:
STATUS=$(socifyr status "$ID" --wait --json | jq -r '.status')
[ "$STATUS" = "completed" ] || exit 1--wait polls every 3 seconds and gives up after 5 minutes with Upload <id> did not complete within 300000ms and exit code 1.
What are the common CLI errors?
| Message | Cause | Fix |
|---|---|---|
No API key configured. | Neither SOCIFYR_API_KEY nor a saved key exists | socifyr configure --key sk_... |
No workspace ID configured. | No workspace ID | socifyr configure --workspace <id> |
No connections specified. | post ran without --to | Add --to; run socifyr connections for slugs |
Invalid format: ... | --format is not a known content format | Use one of short_video, story, feed_video, photo_single, photo_carousel, text_post, document_post |
Only one video file can be posted at a time | More than one video passed | Post one video per command |
Upload limit reached for your plan. Upgrade to continue. (HTTP 403) | Monthly post limit reached. Related messages: Scheduling is not available on your current plan., Storage limit reached for your plan. | Run socifyr usage, then upgrade or free storage. See error handling |
| An error mentioning rate limit (HTTP 429) | Too many requests | Wait for the Retry after seconds and rerun |
See error handling for platform-side failures.
What can't the CLI do?
The CLI does not cover everything the API does. It has no commands for connecting a brand-new account (use the dashboard), submitting a draft for approval, approving or rejecting posts, managing API keys, members or webhooks, listing or filtering post history, or generating hashtags. See the feature parity matrix for every surface side by side, and choose your surface for which tool fits which job.