Skip to content

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.

bash
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? ​

FlagDescriptionDefault
[text]Caption or body textempty
-t, --to <slugs>Required. Comma-separated connection slugs, for example x-myhandle,linkedin-myhandlenone
-f, --file <path>Read the caption from a text file. Overrides the positional textnone
-m, --media <paths>Comma-separated local file paths. Each is uploaded to your media library firstnone
--media-id <refs>Comma-separated media library IDs or public http(s) URLs. No upload needednone
--format <format>Content format overridechosen by the API
-a, --at <datetime>Schedule for an ISO 8601 timepublish now
--aiGenerate platform-specific captions with AI and use the first oneoff
-w, --waitPoll until the post reaches a final state and print per-platform resultsoff
--draftSave as a draft instead of publishingoff
--jsonPrint the API response as JSONoff

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? ​

bash
socifyr post "Just shipped v2.0" --to linkedin-myhandle,x-myhandle
# ✓ Post submitted
#   ID: 6a05033584584482ace13d72
#   Check status: socifyr status 6a05033584584482ace13d72

Read the text from a file or from stdin:

bash
socifyr post --file CHANGELOG.md --to linkedin-myhandle
cat release-notes.md | socifyr post --to linkedin-myhandle

Stdin 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.

bash
socifyr post "New product reveal" --media banner.jpg --to instagram-mybrand

socifyr post "Photo dump" --media a.jpg,b.jpg,c.jpg --to instagram-mybrand

How do I post a video or a Reel? ​

Videos: .mp4, .mov, .avi, .mkv, .webm, .m4v. Only one video can be posted per command.

bash
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-me

Platform 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.

bash
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-mybrand

For 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? ​

bash
socifyr post "Deploy at 9am" --to linkedin-myhandle --at "2026-12-01T09:00:00Z"
# ✓ Scheduled
#   ID: 6a05033584584482ace13d73

Use 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? ​

bash
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? ​

bash
socifyr post "launch of our analytics dashboard" --to linkedin-myhandle,x-myhandle --ai --wait

With --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? ​

bash
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:

json
{
  "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.

bash
ID=$(socifyr post "Hello" --to x-myhandle --json | jq -r '.id')
socifyr status "$ID" --wait

What 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? ​

MessageFix
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: .xyzUse a supported image or video extension, or upload first and use --media-id
Only one video file can be posted at a timeOne 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 IDThe ID does not exist in this workspace; run socifyr media list

Next steps ​