# 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](/integrations/agent-skills)), and every command supports
`--json` for machine-readable output.

## Install

The CLI ships with the Agent Skills package:

```bash
npx skills add OmniSocials/omnisocials-agent-skills
```

Or clone the repository and run the script directly:

```bash
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`:

```bash
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](/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`

## 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](/cli/posting) |
| Inbox | `inbox:list`, `inbox:messages`, `inbox:read`, `inbox:reply` | [Inbox commands](/cli/inbox) |
| Analytics | `analytics:post`, `analytics:posts`, `analytics:overview`, `analytics:accounts`, `analytics:best-times` | [Analytics commands](/cli/analytics) |
| Platforms | `accounts:list`, `accounts:get`, `locations:search`, `audio:search` | [Platform commands](/cli/platforms) |
| Management | `setup`, `config:show`, `media:*`, `folders:*`, `hashtag-sets:*`, `webhooks:*` | [Management commands](/cli/management) |

## Quick example

```bash
# 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](/rate-limits-and-errors).