CLI account management commands
Configuration, media library, folders, and webhook management.
Setup and configuration
| Command | Description |
|---|---|
setup | Interactive setup: prompts for an API key, validates it, writes the config file, and adds .omnisocials/ to .gitignore. Flags: --api-key <key> (skip the prompt), --global (write the global config), --base-url <url> |
config:show | Show the resolved config: masked API key, base URL, and which source it came from |
These two commands are the only ones that run without authentication. See CLI authentication for the full resolution order.
Media
| Command | Description |
|---|---|
media:list | List uploaded media files. Flags: --limit, --offset |
media:upload | Upload from a URL (image, video, or PDF). Flags: --url (required), --filename, --name, --folder, --folder-id, --pdf-mode. PDFs are split into one image slide per page for carousels; --pdf-mode document keeps the PDF as one media item whose single id expands into every page |
media:upload-base64 | Upload a local file: --file <path> (auto-encodes and infers the MIME type) or --data <base64> plus --mime-type <type>; also --filename, --name, --folder, --folder-id, --pdf-mode |
media:check | Check media compatibility against target platforms before posting. Pass --url, --media-id, or --size-bytes plus --mime. For a library image (--media-id) it also prints how each channel shows it as a feed post (ratio, whether it fits, the crop target and the default action), so you can decide on --media-fit before you post |
media:delete <id> | Delete a media file |
Terminal
Folders
| Command | Description |
|---|---|
folders:list | List media folders with id, name, parent, and item count |
folders:create | Create a folder. Flags: --name (required), --parent-id (nested folders) |
Hashtag sets
Save a group of hashtags once, then apply it to any post with posts:create --hashtag-set "<name>". Tags merge into the captions at create time (editing a set later never changes existing posts), duplicates already in a caption are skipped, and Instagram's 5-hashtag cap fails fast. Add --hashtag-placement first_comment to post the tags as the automatic first comment where supported, and --hashtag-platforms instagram,tiktok to target a subset of channels.
| Command | Description |
|---|---|
hashtag-sets:list | List saved sets with id, name, tag count, and a preview |
hashtag-sets:create | Save a set. Flags: --name (required, unique per workspace), --tags (required, e.g. "#fitness #gym"; the # is optional, max 100 tags) |
hashtag-sets:update <id> | Rename or replace tags. Flags: --name, --tags (replaces the full list) |
hashtag-sets:delete <id> | Delete a set. Posts that already used it keep their hashtags |
Terminal
Automations (comment to DM)
An automation DMs a person once when they comment a keyword on an Instagram post (or send it in a DM or a story reply), and can post a public reply under the comment. It also runs on a Facebook Page with --platform facebook: a keyword in a comment under a Page post, or in a Messenger message to the Page, gets the DM in Messenger. Facebook has no story replies. With --platform x it answers a keyword in a DM to the X account (the trigger is dm, no post and no public reply); it runs only while X DMs are on for the workspace (409 x_dms_off otherwise, --paused always saves), and every X answer ends with "Reply STOP to stop automatic messages." The platform is set at create and cannot change. The API key needs the opt-in automations:read and automations:write scopes (Settings, API, "Automations" on the key).
| Command | Description |
|---|---|
automations:list | List automations with status, trigger, keywords, post and counts. Flags: --status <active|paused|completed>, --platform <instagram|facebook|x>, --post-id |
automations:get <id> | One automation in full |
automations:create | Flags: --dm "<text>" (required), --keywords "guide,link", --match <word|contains|any>, --reply "Sent you a DM!" (public reply, comma list for variations), --platform <instagram|facebook|x> (default instagram; x answers DMs only), one of --post-id <id>, --instagram-media-id <id> or --facebook-post-id <id> (a Page post published outside OmniSocials, {page-id}_{post-id} or the post id alone; implies facebook), --scope <post|next_post|any>, --triggers comment,dm,story_reply (Facebook: comment,dm; X: dm, the default there), --max-sends <n>, --stop-at <ISO8601>, --name, --paused |
automations:update <id> | Same flags, all optional, plus --pause / --resume (an X automation resumes only while X DMs are on). The platform cannot change |
automations:delete <id> | Delete it and its activity. DMs already sent stay sent |
automations:events <id> | The activity: who commented or wrote, what was sent, answers waiting in the queue (queued), people who replied STOP on X (opted_out), skips with their reason. Flags: --outcome <sent|skipped|failed|pending|queued|opted_out>, --limit, --offset |
A new post can carry its automation: posts:create --dm-keywords "guide" --dm-message "Here is the guide" --dm-reply "Sent you a DM!" (Instagram or Facebook must be a channel; --dm-platforms instagram,facebook makes one automation per channel); posts:update <id> --no-dm removes it.
Terminal
On a Facebook Page, for a post published on the Page outside OmniSocials:
Terminal
On X, a keyword in a DM to the X account (saved paused until X DMs are on for the workspace):
Terminal
Webhooks
| Command | Description |
|---|---|
webhooks:list | List all configured webhooks |
webhooks:create | Create a webhook. Flags: --url (required), --events (required; comma-separated: post.scheduled, post.published, post.failed, post.approved, post.rejected). The signing secret is shown once |
webhooks:get <id> | Webhook details |
webhooks:update <id> | Update URL, events, or active state. Flags: --url, --events, --active <true|false> |
webhooks:delete <id> | Delete a webhook |
webhooks:rotate-secret <id> | Rotate the signing secret; the new secret is shown once |
Terminal
post.approved and post.rejected fire when the review of a post in an approval workflow ends. To be told about both:
Terminal
Their payload names the decision, the approver and the reason; read the full review with posts:approval <id>.
See the Webhooks guide for event payloads and signature verification.