You generate captions with the Creator OS CLI by installing @creatoros/cli, authenticating, writing the caption in a posts:create command or a JSON calendar file, and pushing it with creatoros posts:bulk-upload --file calendar.json. Before anything publishes, creatoros validate:post-length --text "..." tells you which platforms would truncate. The workflow runs from your terminal, so a week of posts takes one file and one command.
creatoros media:upload ./clip.mp4
|
v
med_abc123 --------------------+
|
caption text --> posts:create ---+--> scheduled posts
|
validate:post-length (per-platform cap check)
posts:bulk-upload --dryRun (whole week preview)
|
v
12:00 Mon Instagram Reel
12:00 Mon TikTok video
18:00 Tue X threadWhat Is the Creator OS CLI and Why Use It for Captions?
The Creator OS CLI is a terminal client for your Creator OS workspace, and it is the fastest path to captions when you already think in files.
Creator OS is one place to publish, schedule, reply and read analytics on 11 platforms plus Skool. The same account is reachable from the web app, the iOS app, the REST API, the CLI, a Claude Code plugin and a hosted MCP server. The CLI talks to the same backend as the web app, so a post scheduled from your shell appears in the calendar like any other.
Why reach for the terminal instead of the composer? Three reasons that matter for captions specifically:
- Length checks are cheap.
creatoros validate:post-lengthruns before anything is queued, so you find out a caption is too long for X or Threads while it is still text on your disk. - Batch beats one at a time. One JSON file with a week of captions uploads in one call instead of twelve.
- Captions live in version control. Commit the file, diff it, reuse the pattern next month.
If you want the writing side first, start with the voice and the hooks. This post assumes you have the words and need to ship them.
How to Install and Authenticate @creatoros/cli
Installing takes one command and authentication takes one check.
npx @creatoros/cli@latest init
creatoros auth:check
creatoros accounts:listinit sets up the CLI and installs 14 Claude Code skills, including post-everywhere, schedule-posts and analytics. auth:check confirms your key is live. accounts:list prints the account ids you will pass to --accounts. Every command is documented at https://www.creatoros.ca/docs/cli.
If you only ever post to the same channels, skip account ids and use --platforms instagram,tiktok,youtube. Creator OS applies each platform’s own rules, Reels, Shorts and TikTok consent flags included, so one caption can fan out to several networks.
How to Generate Captions With One CLI Command
One posts:create call writes a caption and queues it, and it accepts the plumbing flags you would otherwise click through.
Start by uploading the video once, so you get a media id you can reuse on every platform in the post:
creatoros media:upload ./clip.mp4
# returns med_abc123Then create the post. --media and --cover take a med_ id or a URL, not a local file path:
creatoros posts:create \
--text "Three takes on the new edit. Which one lands?" \
--platforms instagram,tiktok \
--media med_abc123 \
--scheduledAt 2025-06-02T12:00:00Z \
--timezone America/Toronto \
--hashtags reels,editing \
--cover med_cover456If the media already lives at a public URL, pass the URL directly to --media and skip the upload step.
Useful flags beyond --text:
| Flag | What it does |
|---|---|
--title |
Title field for YouTube uploads |
--draft |
Queues as a draft instead of publishing |
--cover / --coverAt |
Cover image (med_ id or URL), or a frame timestamp in ms |
--tags |
Tag list for filtering later |
--scheduledAt + --timezone |
Schedules instead of posting now |
One upload works across every platform in the post, so the same med_ id serves the Instagram Reel and the TikTok video.
Want the scheduling time to be data driven? creatoros analytics:best-time --platform instagram prints your best posting window, which you can feed straight into --scheduledAt. The scheduling walkthrough goes deeper on timing.
How to Queue Captions to Your Channels From the Terminal
Queueing is the same command twice with different flags: draft first, then schedule.
creatoros posts:create --text "Draft caption" \
--platforms instagram --draft
creatoros posts:create --text "Ready caption" \
--accounts acc_123,acc_456 \
--scheduledAt 2025-06-03T09:00:00Z \
--timezone America/TorontoThen verify what is actually queued:
creatoros posts:list --status scheduled --limit 20If one post fails on one network, creatoros posts:retry <postId> re-fires it. If you need to pull a published caption from a single network, creatoros posts:unpublish <postId> --platform youtube handles that without touching the others. Caption edits after publish go through creatoros posts:edit for the networks that allow it.
On agency plans you get a scoped API key per client workspace, so the CLI and API can be pointed at one client at a time without a cross-posting risk. Agency 5 is $49.99/month for five sets of socials, Agency 10 is $99/month for ten.
How to Batch a Full Week of Captions From a Calendar File
posts:bulk-upload reads a calendar JSON file, and you can dry run it to see what would happen.
creatoros posts:bulk-upload --file week.json --dryRun
creatoros posts:bulk-upload --file week.jsonThe dry run prints what would be created, per platform, without posting. That is the moment to catch a missing media id or a caption that is too long for one network. When the dry run looks right, drop --dryRun and the whole week queues.
If your captions start life in a spreadsheet, export a CSV and convert it to the JSON shape once with a short script. The shape mirrors the CLI flags: text, platforms or accounts, media, scheduledAt and timezone. Put the med_ ids from media:upload in the file, not paths on your laptop, so the job works from any machine. Keep the file in git and next week is a copy and edit.
Two habits make batching reliable:
- Validate every caption first:
creatoros validate:post-length --text "...". It reports the platforms where the caption fits and where it would be cut. - Validate media URLs with
creatoros validate:media --url <url>before uploading, so a dead link fails on your machine, not in the queue.
A related pattern is covered in batching captions for one week.
Can You Generate Captions With the REST API Instead?
Yes. The same caption that the CLI creates can be created with POST /v1/posts, which is what you want inside a server or a scheduled job.
POST /v1/posts
{
"content": "Three takes on the new edit.",
"platforms": ["instagram", "tiktok"],
"media": ["med_abc123"],
"schedule_at": "2025-06-02T12:00:00Z",
"timezone": "America/Toronto"
}The simple form takes strings for platforms and a list of med_ ids or URLs for media. The advanced form takes objects with per-platform options, so you can set TikTok consent flags, a Reddit subreddit and title, or a Discord embed in the same post. The API returns one error shape, { error: { code, message, status } }, and any network you named that is not connected comes back in missing_platforms while the rest go out.
The base URL lives in the docs at https://www.creatoros.ca/docs, along with the full request reference at https://www.creatoros.ca/docs/api/posts. Keys are prefixed cos_live_ and are pinned to one workspace, so a key for one set of socials cannot post to another.
| Choose | When |
|---|---|
| CLI | You are at a shell, writing captions by hand, doing a weekly batch |
| REST API | A server, cron job or app needs to create posts programmatically |
| MCP server | An AI app like Claude or ChatGPT should create posts from a prompt |
Common CLI Caption Errors and How to Fix Them
Almost every caption failure is a length problem, a missing account, or an auth problem, and each has a one-line fix.
Caption too long for one network
Run creatoros validate:post-length --text "<caption>". It tells you which platforms reject or truncate. Shorten the text or split the long version into a per-platform caption using the advanced post form.
Auth errors
Run creatoros auth:check. If it fails, the key is expired, revoked or scoped to another workspace. Create a fresh key in Settings > API keys and re-run creatoros init.
Media rejected
Check the flag value first: --media and --cover take a med_ id or a URL, never a local path. If it is a URL, run creatoros validate:media --url <url>. Dead links and unsupported types fail here rather than after upload. Uploading the file once with creatoros media:upload and reusing the med_ id avoids the problem entirely.
Account confusion
Run creatoros accounts:list and creatoros accounts:health. A disconnected account is the usual cause of a post landing on some networks and not others. --platforms targets every connected account on that platform; --accounts targets exact ids.
Bulk upload quietly skipped rows
Re-run with --dryRun and read the output line by line. A malformed timezone, a missing platforms array, or a local file path where a med_ id belongs drops a row.
For terminal video work alongside captions, the CLI 0.6.8 release notes cover what changed, and scheduling YouTube from the terminal shows the long-form path. Watch the walkthroughs on the KevBuildsApps YouTube channel if you prefer to see the commands run.
FAQ
How do I install the Creator OS CLI for caption generation?
Run npx @creatoros/cli@latest init. It installs the CLI and 14 Claude Code skills. Then run creatoros auth:check to confirm your key works and creatoros accounts:list to see which accounts are connected.
Can I generate captions from a CSV file in the Creator OS CLI?
posts:bulk-upload takes a calendar JSON file, not a raw CSV, so convert your spreadsheet to that JSON shape once and reuse the script. Always run it with --dryRun first to see exactly what would be created per platform before anything publishes.
Why does –media reject my file path?
--media takes a med_ id or a public URL, not a path on your laptop. Run creatoros media:upload ./clip.mp4 first and pass the returned id instead.
Is there a REST API for Creator OS captions?
Yes. POST /v1/posts creates a caption post with content, platforms, media, schedule_at and timezone, and the same endpoint offers an advanced form with per-platform options. The base URL and full reference are at https://www.creatoros.ca/docs.
What is the difference between the Creator OS CLI and the web app for captions?
They hit the same backend, so a post scheduled in one shows up in the other. The CLI is built for files, length checks and batch uploads. The web app is built for visual composition, calendars and browsing comments and DMs.
Get Started With Creator OS
Install the CLI, run npx @creatoros/cli@latest init, and push your first batch this afternoon. Creator OS plans start at $14.99/month for 11 platforms plus Skool, with the API, the MCP server and the CLI included. There is a free trial, cancellable anytime. Sign up here.
Get started for $0
Free trial for new subscribers. Cancel anytime.