socifyr post
socifyr post publishes text, images, video or documents to one or more connected accounts. The same command schedules a post with --at or saves a draft with --draft.
socifyr post [text] --to <slugs> [options]Text comes from the positional argument, --file, or stdin. Media comes from --media (local files) or --media-id (library IDs or public URLs). Every post needs at least one connection slug from socifyr connections.
What flags does socifyr post take?
| Flag | Description | Default |
|---|---|---|
[text] | Caption or body text | empty |
-t, --to <slugs> | Required. Comma-separated connection slugs, for example x-myhandle,linkedin-myhandle | none |
-f, --file <path> | Read the caption from a text file. Overrides the positional text | none |
-m, --media <paths> | Comma-separated local file paths. Each is uploaded to your media library first | none |
--media-id <refs> | Comma-separated media library IDs or public http(s) URLs. No upload needed | none |
--format <format> | Content format override | chosen by the API |
-a, --at <datetime> | Schedule for an ISO 8601 time | publish now |
--ai | Generate platform-specific captions with AI and use the first one | off |
-w, --wait | Poll until the post reaches a final state and print per-platform results | off |
--draft | Save as a draft instead of publishing | off |
--json | Print the API response as JSON | off |
Valid --format values are short_video, story, feed_video, photo_single, photo_carousel, text_post and document_post. See content formats.
How do I post text to several platforms from the CLI?
socifyr post "Just shipped v2.0" --to linkedin-myhandle,x-myhandle
# ✓ Post submitted
# ID: 6a05033584584482ace13d72
# Check status: socifyr status 6a05033584584482ace13d72Read the text from a file or from stdin:
socifyr post --file CHANGELOG.md --to linkedin-myhandle
cat release-notes.md | socifyr post --to linkedin-myhandleStdin is read from /dev/stdin when no text is given and the terminal is not interactive. On Windows, use --file.
How do I post an image or a carousel?
The media type is detected from the extension of the first path. Images: .jpg, .jpeg, .png, .gif, .webp, .heic.
socifyr post "New product reveal" --media banner.jpg --to instagram-mybrand
socifyr post "Photo dump" --media a.jpg,b.jpg,c.jpg --to instagram-mybrandHow do I post a video or a Reel?
Videos: .mp4, .mov, .avi, .mkv, .webm, .m4v. Only one video can be posted per command.
socifyr post "Demo of v2.0" --media demo.mp4 --to youtube-mychannel,instagram-mybrand
socifyr post "Quick demo" --media demo.mp4 --format short_video --to instagram-mybrand,tiktok-mePlatform size, length and format limits are listed on each platform page.
How do I reuse media that is already in my library?
Pass library IDs (24-character hex) or public URLs with --media-id. Local files and IDs can be mixed.
socifyr post "Same banner, new caption" --media-id 6a04f715d3d7d93575e65d13 --to linkedin-myhandle
socifyr post "From a CDN" --media-id https://cdn.example.com/banner.png --to instagram-mybrandFor bare library IDs the CLI looks up each item to learn whether it is an image, video or document, so a video ID is never sent as a photo. Documents can only be posted this way, because --media rejects non-image, non-video extensions. See media library.
How do I schedule a post with the CLI?
socifyr post "Deploy at 9am" --to linkedin-myhandle --at "2026-12-01T09:00:00Z"
# ✓ Scheduled
# ID: 6a05033584584482ace13d73Use ISO 8601. Add an offset such as -04:00 for another timezone. The free plan can schedule 5 posts a month (scheduledPostsPerMonth in the shared plan limits); check what is left with socifyr usage. To change the time later use socifyr edit. For many posts at once use socifyr schedule.
How do I save a draft and publish it later?
socifyr post "Polish this later" --media banner.jpg --to instagram-mybrand --draft
# ✓ Draft saved
# ID: 6a05032a84584482ace13d5f
socifyr publish 6a05032a84584482ace13d5f --wait--wait is ignored with --draft.
How do I generate the caption with AI?
socifyr post "launch of our analytics dashboard" --to linkedin-myhandle,x-myhandle --ai --waitWith --ai the CLI derives the platform types from the slug prefix (text before the first -), asks the AI endpoint for captions, and uses the first generated caption for every account. Your text becomes the description the AI works from. The workspace needs its own AI provider key, otherwise the API answers No AI provider key set for this workspace. Add your own key in Settings → AI to use AI features. AI endpoints allow 10 requests per minute. See AI composer and BYOK.
How do I wait for the result and see per-platform status?
socifyr post "Test cross-post" --to instagram-mybrand,x-myhandle --wait⚠ partial failure
✓ instagram → https://instagram.com/p/...
✗ x
rate limit exceeded--wait polls every 3 seconds for up to 5 minutes. The final states are completed (shown as ✓ published), partial_failure and failed. The exit code is 0 in all three cases.
What does --json return?
The API response, with an id field added that holds uploadId or draftId:
{
"success": true,
"requestId": "9f2c7a1e-3d44-4b2a-8e1f-0a5c2d7e9f10",
"uploadId": "6a05033584584482ace13d72",
"id": "6a05033584584482ace13d72"
}Responses can also carry a usage object (count, limit, remaining). A draft returns draftId instead of uploadId.
ID=$(socifyr post "Hello" --to x-myhandle --json | jq -r '.id')
socifyr status "$ID" --waitWhat happens with an approval-required API key?
If the key has requireApproval set, the post is created as pending_approval and does not publish until a teammate approves it. The CLI still prints Post submitted. Do not add --wait in that case: pending_approval is not a final state, so the wait times out after 5 minutes. See API keys and guardrails.
What are the common socifyr post errors?
| Message | Fix |
|---|---|
No connections specified. | Add --to with slugs from socifyr connections |
No content provided. | Pass text, --file, --media, --media-id, stdin, or --ai |
Media file not found: <path> | Check the path |
Unrecognized media type: .xyz | Use a supported image or video extension, or upload first and use --media-id |
Only one video file can be posted at a time | One video per command |
Invalid format: <value> | Use a value from the format list above |
Text post requires non-empty content. | A text post needs a caption |
Failed to resolve media library ID | The ID does not exist in this workspace; run socifyr media list |