# CLI Posting Commands

Create, schedule, publish, update, and delete posts from the command line. All
commands honor the [global flags](/cli#global-flags) and print JSON with `--json`.

## Commands

| Command | Description |
|---------|-------------|
| `posts:list` | List posts. Flags: `--status <draft\|scheduled\|published\|failed>`, `--limit`, `--offset` |
| `posts:get <id>` | Full details for one post |
| `posts:create` | Create a draft or scheduled post. `--text` is required |
| `posts:create-and-publish` | Create a post and publish it immediately (no `--schedule`) |
| `posts:update <id>` | Update a draft or scheduled post; takes the same flags as `posts:create` |
| `posts:publish <id>` | Publish an existing draft or scheduled post now |
| `posts:delete <id>` | Delete a post (irreversible) |
| `posts:recent-platform` | Fetch recent posts live from the connected platforms, including content published outside OmniSocials. Flags: `--limit` (1-50, default 25), `--platforms <a,b>`. Requires the `analytics:read` scope |

## Post options

For `posts:create`, `posts:create-and-publish`, and `posts:update`:

| Flag | Description |
|------|-------------|
| `--text <str>` | Caption / post content (required on create) |
| `--channels <a,b>` | Comma-separated [channel ids](/cli#channels) |
| `--type <post\|story\|reel>` | Content type (default `post`) |
| `--schedule <ISO8601>` | Schedule time, e.g. `2026-08-01T09:00:00Z` |
| `--media-urls <url,url>` | Attach media by URL |
| `--media-ids <id,id>` | Attach media from the library |
| `--link-url <url>` | Link-preview card (LinkedIn / Facebook) |
| `--link-title <str>` | Override the link-preview title |
| `--link-description <str>` | Override the link-preview description |
| `--link-thumbnail-url <url>` | Override the link-preview thumbnail |
| `--location-id <id>` | Instagram place tag (find ids with [`locations:search`](/cli/platforms#location-search)) |
| `--collaborators <a,b>` | Instagram co-author usernames (max 3) |
| `--user-tags '<json>'` | Instagram photo tags: JSON array of `{"username","x","y","image_index?"}` |
| `--x-thread "a \|\| b \|\| c"` | X thread; parts split on `\|\|` |
| `--bluesky-thread "a \|\| b \|\| c"` | Bluesky thread |
| `--mastodon-thread "a \|\| b \|\| c"` | Mastodon thread |

## Platform-specific flags

### Instagram

| Flag | Description |
|------|-------------|
| `--instagram-share-to-feed` | Also share the reel to the feed |
| `--instagram-cover-url` | Custom reel thumbnail URL |
| `--instagram-thumbnail-type` | `from-video` or `from-library` |
| `--instagram-thumb-offset` | Video timestamp in ms (for `from-video`) |
| `--instagram-audio-id` | Licensed music for reels (find ids with [`audio:search`](/cli/platforms#audio-search)) |
| `--instagram-audio-volume` | Music volume 0-100 |
| `--instagram-video-volume` | Original audio volume 0-100 (0 = music only) |
| `--instagram-first-comment` | First comment (not for stories) |
| `--instagram-trial-reel` | Publish as a trial reel (roughly 1,000+ followers required) |
| `--instagram-trial-graduation-strategy` | `MANUAL` or `SS_PERFORMANCE` |

### YouTube

| Flag | Description |
|------|-------------|
| `--youtube-title` | Video title |
| `--youtube-privacy` | `public`, `private`, or `unlisted` |
| `--youtube-tags` | Comma-separated tags |
| `--youtube-category-id` | Category ID |
| `--youtube-made-for-kids` | Mark as made for kids |
| `--youtube-notify-subscribers` | Notify subscribers on publish |
| `--youtube-contains-synthetic-media` | Mark as AI-generated |
| `--youtube-first-comment` | First comment (video must allow comments) |

### TikTok

| Flag | Description |
|------|-------------|
| `--tiktok-privacy` | `PUBLIC_TO_EVERYONE`, `MUTUAL_FOLLOW_FRIENDS`, `FOLLOWER_OF_CREATOR`, `SELF_ONLY` |
| `--tiktok-disable-comment` | Disable comments |
| `--tiktok-disable-duet` | Disable duets |
| `--tiktok-disable-stitch` | Disable stitches |
| `--tiktok-video-cover-timestamp-ms` | Cover frame timestamp in ms |
| `--tiktok-is-aigc` | Mark as AI-generated content |
| `--tiktok-brand-content-toggle` | Paid partnership disclosure |
| `--tiktok-brand-organic-toggle` | Own-brand disclosure |
| `--tiktok-auto-add-music` | Auto-add music to photo carousels |

### Pinterest

| Flag | Description |
|------|-------------|
| `--pinterest-board-id` | Board ID (required for Pinterest; find it with `accounts:get`) |
| `--pinterest-title` | Pin title |
| `--pinterest-link` | Destination URL |
| `--pinterest-video-cover` | Cover image URL for video pins |
| `--pinterest-alt-text` | Accessibility alt text |

### Other platforms

| Flag | Description |
|------|-------------|
| `--facebook-first-comment` | First comment on the page post |
| `--linkedin-first-comment` | First comment on a personal profile post |
| `--linkedin-page-first-comment` | First comment on a company page post |
| `--x-reply-settings` | `following` or `mentionedUsers` (empty = everyone) |

## Examples

Schedule an image post to Instagram and LinkedIn:

```bash
omnisocials posts:create \
  --text "Launch day! Here is what we built." \
  --channels instagram,linkedin \
  --media-urls https://example.com/launch.jpg \
  --schedule 2026-08-01T09:00:00Z
```

Publish an X thread right away:

```bash
omnisocials posts:create-and-publish \
  --channels x \
  --text "How we cut our posting time by 90%" \
  --x-thread "How we cut our posting time by 90% || Step 1: stop copy-pasting between tabs || Step 2: automate the boring parts"
```

Publish a reel with licensed music:

```bash
omnisocials audio:search "summer vibes"
omnisocials posts:create-and-publish \
  --type reel \
  --channels instagram \
  --text "POV: your content calendar fills itself" \
  --media-urls https://example.com/reel.mp4 \
  --instagram-audio-id 123456789 \
  --instagram-video-volume 0
```

Check what went out recently, straight from the platforms:

```bash
omnisocials posts:recent-platform --platforms instagram,tiktok --limit 10
```