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 ships with the Agent Skills package:

Code
npx skills add OmniSocials/omnisocials-agent-skills

Or clone the repository and run the script directly:

Code
git clone https://github.com/OmniSocials/omnisocials-agent-skills
cd omnisocials-agent-skills
./scripts/omnisocials.js --help

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:

Code
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_ (production) or omsk_test_ (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:

Code
{ "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

Command groups

Group	Commands	Page
Posting	posts:list, posts:get, posts:create, posts:create-and-publish, posts:update, posts:publish, posts:delete, posts:recent-platform	Posting commands
Inbox	inbox:list, inbox:messages, inbox:read, inbox:reply	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	Platform commands
Management	setup, config:show, media:*, folders:*, hashtag-sets:*, webhooks:*	Management commands

Quick example

Code
# 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.