CLI reference
Every command and flag of the bulkit command-line tool.
Run bulkit <command> --help to see the same information in your terminal.
Most commands have a short alias, shown in brackets: bulkit posts ls is
bulkit posts list.
Wherever a command takes a channel, you can give its id, @username,
display name, or platform. See Pick channels by name.
Wherever it takes a time, you can give ISO 8601 (2026-11-01T09:00, in
your time zone, or 2026-11-01T09:00Z) or an offset from now (+30m, +2h,
+1d, +1w).
Global flags
These work with every command.
| Flag | What it does |
|---|---|
--json | Print the API's JSON on stdout. Errors are JSON on stderr. |
--profile <name> | Use the key saved under this profile. Default: $BULKIT_PROFILE, then default. |
--no-input | Never ask a question. Fail instead, with exit code 2. |
--no-color | No colors. |
--debug | Log every request and show stack traces. Never shows your key. |
-v, --version | Print the version. |
-h, --help | Show help for a command. |
posts
posts list [ls]
List posts, newest first.
| Flag | What it does |
|---|---|
-s, --status <status> | Only posts with this status: draft, scheduled, publishing, published or failed. Repeatable. |
--tag <id> | Only posts with this tag. Repeatable. |
--from <time> | Only posts at or after this time. |
--to <time> | Only posts before this time. |
-L, --limit <n> | How many to show. Default 25. |
--all | Show every matching post. |
posts get <post-id> [view]
Show a post and where each channel stands.
| Flag | What it does |
|---|---|
-w, --wait | Wait until publishing finishes. Exits 1 if any channel failed. |
--timeout <seconds> | How long --wait waits. Default 300. |
posts create [new]
Create one post for one or more channels.
| Flag | What it does |
|---|---|
-c, --channel <channel> | A channel to post to. Repeatable. |
-t, --text <text> | The text. Repeat it to write a thread: one part per --text. |
--text-file <path> | Read the text from a file, or - for stdin. |
-m, --media <media-id> | Attach uploaded media to the first part. Repeatable. |
--title <title> | A title, on platforms that have one (YouTube, Reddit, Pinterest, …). |
--tag <tag-id> | Label the post with a workspace tag. Repeatable. |
-f, --file <path> | The whole request body as JSON, or - for stdin. Use it for per-channel text and platform options. Can't be combined with the content flags above. |
--draft | Save as a draft. This is the default. |
--at <time> | Schedule it. |
--now | Publish now, to real accounts. |
-w, --wait | With --now: wait until publishing finishes. Exits 1 if any channel failed. |
--timeout <seconds> | How long --wait waits. Default 300. |
--dry-run | Print the request body instead of sending it. |
--idempotency-key <key> | Run again with the same key to retry without making a second post. |
-y, --yes | Don't ask before publishing. |
Prints the new post's id on stdout.
posts update <post-id> [edit]
Replace a post that isn't published yet. The body replaces the whole post, in
the same shape as posts create --file.
| Flag | What it does |
|---|---|
-f, --file <path> | The new body as JSON, or - for stdin. Required. |
-y, --yes | Don't ask first. |
bulkit posts get pst_123 --json > post.json # edit it, then:
bulkit posts update pst_123 --file post.jsonposts publish <post-id>
Publish a draft or scheduled post now, or retry a failed one. Channels that already published are skipped, so retrying is safe.
| Flag | What it does |
|---|---|
-w, --wait | Wait until publishing finishes. Exits 1 if any channel failed. |
--timeout <seconds> | How long --wait waits. Default 300. |
-y, --yes | Don't ask first. |
posts revise <post-id>
Change the text of a published post, on platforms that allow it. Run
bulkit channels get <channel> to see if a channel does ("Edit live post").
| Flag | What it does |
|---|---|
-f, --file <path> | The revision as JSON ({ "channels": [...] }), or - for stdin. Required. |
-y, --yes | Don't ask first. |
List every channel of the post, with the same number of parts as were published. Only the wording can change.
posts retract <post-id>
Permanently delete a published post from the platforms, with its likes and
replies. Anything that couldn't be taken down is listed, and the command exits
1.
| Flag | What it does |
|---|---|
-y, --yes | Don't ask first. Without it, a live key asks you to type the post id. |
posts delete <post-id> [rm]
Delete Bulkit's record of a post. Published copies stay live. Use
posts retract to take them down.
| Flag | What it does |
|---|---|
-y, --yes | Don't ask first. |
posts metrics <post-id>
A published post's likes, views and more over time, per channel. Prints JSON.
channels
channels list [ls]
The social accounts you can post to. Warns about any that need reconnecting.
channels get <channel>
One channel: its status, whether its posts can be retracted or edited after publishing, and its account-specific options.
media
media list [ls]
The workspace's media library.
media upload <sources...>
Upload files or URLs. Prints one media id per file on stdout, for
posts create --media.
| Flag | What it does |
|---|---|
--mime-type <type> | Override the type. By default it comes from the server (for URLs), then the file extension. |
--concurrency <n> | How many parts of a large video to upload at once. Default 4. |
Every source is checked before anything is uploaded. URLs are downloaded by
the CLI; quote them if they contain & or ?.
media delete <media-id> [rm]
Delete a file from the media library.
| Flag | What it does |
|---|---|
-y, --yes | Don't ask first. |
comments
comments list <post-id> [ls]
The comments on one channel's copy of a published post.
| Flag | What it does |
|---|---|
-c, --channel <channel> | Which channel's copy. Required. |
-L, --limit <n> | How many to show. Default 50. |
--all | Show every comment. |
comments reply <post-id> <comment-id>
Reply to a comment, in public.
| Flag | What it does |
|---|---|
-c, --channel <channel> | Which channel's copy the comment is on. Required. |
-t, --text <text> | The reply. Required. |
-y, --yes | Don't ask first. With a live key, the CLI shows the reply and asks. |
platforms
platforms list [ls]
Every platform, with its text length, media and thread limits.
platforms get <platform>
One platform's limits and options, for example bulkit platforms get instagram.
tags
tags list [ls]
The workspace's tags. Tags are internal labels: they're never published.
stats
stats
Publishing and engagement totals for a time window, per channel.
| Flag | What it does |
|---|---|
--from <time> | Start of the window. Default: 30 days before --to. |
--to <time> | End of the window. Default: now. |
--timezone <zone> | Time zone for days and hours, like Europe/Paris. Default: yours. |
stats insights
When, where and in what format your posts perform best. Prints JSON. Takes
the same flags as stats, plus:
| Flag | What it does |
|---|---|
--platform <id> | Only these platforms. Repeatable. |
--channel <id> | Only these channels. Repeatable. |
--tag <id> | Only posts with these tags. Repeatable. |
usage
usage
This billing period's usage against your plan's limits.
webhooks
See Webhooks for the events and how to check signatures.
| Command | What it does |
|---|---|
webhooks list [ls] | List webhook endpoints. |
webhooks get <webhook-id> | Show one endpoint. |
webhooks create --url <url> | Add an endpoint. Choose events with -e, --event <event> (repeatable) or --all-events. Prints the signing secret once: store it now. |
webhooks update <webhook-id> | Change --url or --event, or --enable / --disable it. --enable also clears its failure count. |
webhooks delete <webhook-id> [rm] | Delete an endpoint. Asks first, unless --yes. |
webhooks test <webhook-id> | Send a signed webhook.test event now. Exits 1 if your endpoint didn't accept it. |
webhooks roll-secret <webhook-id> | Make a new signing secret. The old one stops working at once. Asks first, unless --yes. |
webhooks deliveries <webhook-id> | Recent delivery attempts, newest first. -L, --limit <n> (default 25) or --all. |
Events: post.published, post.failed, post.partially_failed,
channel.needs_reconnect.
auth
auth login
Save an API key. Asks for it, hiding what you type.
| Flag | What it does |
|---|---|
--with-key | Read the key from stdin instead, for scripts. |
Add --profile <name> to save it under a profile.
auth logout
Remove the saved key for the profile. Does nothing if there is none.
auth status
Which key is in use (shown masked), where it comes from, and whether the API accepts it.
completion
completion <shell>
Print the completion script for bash, zsh or fish. See
Shell completion.