Copy page

CLI: post to social media from your terminal

The OmniSocials CLI is a single-file, zero-dependency Node.js command line tool that covers the full v1 API: posting, media, analytics, the social inbox, accounts, and webhooks. It is designed for both humans and AI agents (it ships as part of OmniSocials Agent Skills), and every command supports --json for machine-readable output.

Install

The CLI is a single executable script; there is no npm package. Clone the repository and put the script on your PATH under the name omnisocials:

Terminal
git clone https://github.com/OmniSocials/omnisocials-agent-skills
sudo ln -s "$PWD/omnisocials-agent-skills/skills/omnisocials/scripts/omnisocials.js" /usr/local/bin/omnisocials
omnisocials --help

If you prefer not to touch /usr/local/bin, an alias works the same: alias omnisocials="$HOME/omnisocials-agent-skills/skills/omnisocials/scripts/omnisocials.js". Every example below assumes the omnisocials name; without the symlink or alias, invoke the script by its path instead.

For AI agents, install it as a skill instead; the skill ships the same CLI and instructs the agent how to call it:

Terminal
npx skills add OmniSocials/omnisocials-agent-skills

Requires Node.js 18 or newer. No dependencies are installed; the CLI uses the built-in fetch.

Authentication

Run the interactive setup once. It prompts for your API key, validates it against the API, writes a config file, and adds .omnisocials/ to your .gitignore:

Terminal
omnisocials setup            # project config (./.omnisocials/config.json)
omnisocials setup --global   # global config (~/.config/omnisocials/config.json)

Create an API key in the OmniSocials app under Settings → API. Keys start with omsk_live_; there is no separate test mode. See Authentication for scopes.

The CLI resolves credentials in this order (first match wins):

1. --api-key <key> flag on the command
2. OMNISOCIALS_API_KEY environment variable
3. Project config: ./.omnisocials/config.json
4. Global config: ~/.config/omnisocials/config.json

The config file is plain JSON:

JSON
{ "api_key": "omsk_live_...", "base_url": "https://api.omnisocials.com/v1" }

base_url is optional and defaults to https://api.omnisocials.com/v1. Check what the CLI resolved with omnisocials config:show.

Global flags

Every command accepts:

Flag	Description
--json	Output the raw JSON response instead of formatted text
--api-key <key>	Override the API key for this invocation
--base-url <url>	Override the API base URL
--help	Show the built-in help

Channels

Commands that target platforms take --channels with comma-separated channel ids:

instagram, facebook, linkedin (personal profile), linkedin_page (company page), youtube, tiktok, x, pinterest, bluesky, threads, mastodon, google_business, telegram (a channel or group), discord (a Discord channel)

Command groups

Group	Commands	Page
Posting	posts:list, posts:get, posts:create, posts:create-and-publish, posts:update, posts:publish, posts:retry, posts:approve, posts:reject, posts:approval, posts:delete, posts:recent-platform	Posting commands
Inbox	inbox:list, inbox:messages, inbox:next, inbox:read, inbox:reply, inbox:hide, inbox:delete	Inbox commands
Analytics	analytics:post, analytics:posts, analytics:overview, analytics:accounts, analytics:best-times	Analytics commands
Platforms	accounts:list, accounts:get, locations:search, audio:search, pinterest:products, pinterest:validate	Platform commands
Management	setup, config:show, media:*, folders:*, hashtag-sets:*, automations:*, webhooks:*	Management commands

Quick example

Terminal
# Connect once
omnisocials setup

# See what is connected
omnisocials accounts:list

# Schedule a post to two platforms
omnisocials posts:create \
  --text "Big announcement coming Friday" \
  --channels instagram,linkedin \
  --media-urls https://example.com/teaser.jpg \
  --schedule 2026-08-01T09:00:00Z

Rate limit: 100 requests per minute per API key. See Rate limits and errors.