Wahlu CLI

Manage your social media from the terminal. Works for humans, AI agents, and CI/CD pipelines.

Install

npm install -g @wahlu/cli

Authentication

Generate an API key at wahlu.com under Settings > API Keys.

# Option 1: Save to config
wahlu auth login wahlu_live_abc123...

# Option 2: Environment variable
export WAHLU_API_KEY=wahlu_live_abc123...

Authentication priority:

1. WAHLU_API_KEY environment variable (highest)
2. Saved key in ~/.config/wahlu/config.json

Quick start

# List your brands
wahlu brand list

# Set a default brand so you don't need --brand every time
wahlu brand switch <brand-id>

# List content items (via post alias)
wahlu post list

# Create a content item
wahlu post create --name "Monday motivation" \
  --copy-mode single \
  --single-copy '{"caption":"Rise and grind","hashtags":[]}' \
  --instagram '{"post_type":"GRID_POST"}'

# Schedule it
wahlu schedule create <content-item-id> \
  --at 2026-03-15T14:00:00Z \
  --integrations <integration-id>

# Upload media
wahlu media upload ./photo.jpg

# List what's been published
wahlu publication list

Commands

Auth

| Command | Description | |---------|-------------| | wahlu auth login <key> | Save API key to ~/.config/wahlu/config.json | | wahlu auth logout | Remove saved API key | | wahlu auth status | Show current auth method, masked key, and config |

Brands

Brands represent social media profiles. All content items, media, publish runs, and queues belong to a brand.

| Command | Description | |---------|-------------| | wahlu brand list | List all brands | | wahlu brand get <id> | Get full brand details | | wahlu brand switch <id> | Set default brand for all commands |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Brand ID | | name | string | Brand name | | description | string|null | Brand description | | logo_url | string|null | Logo URL | | timezone | string|null | IANA timezone (e.g. Australia/Sydney) | | website | string|null | Brand website URL | | business_category | string|null | Business category | | brand_kit | object|null | Brand kit (fonts, colours, voice) | | content_preferences | object|null | CTA, logo frequency settings | | image_posting | object|null | Image posting preferences | | video_posting | object|null | Video posting preferences | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Content items (post command)

Content items are the core content unit. Captions/hashtags are canonical via copy_mode + single_copy/platform_copy, while platform settings control media/post options.

| Command | Description | |---------|-------------| | wahlu post list | List content items (paginated) | | wahlu post get <id> | Get full content item details | | wahlu post create [options] | Create a new content item | | wahlu post update <id> [options] | Update a content item (partial update) | | wahlu post delete <id> | Permanently delete a content item |

Create/update options:

| Option | Description | |--------|-------------| | --name <name> | Content item name (max 500 chars) | | --copy-mode <mode> | Canonical caption mode: single or per_platform | | --single-copy <json> | Canonical shared copy JSON: {"caption":"...","hashtags":["..."],"title":"..."} | | --platform-copy <json> | Canonical per-platform copy JSON map | | --instagram <json> | Instagram settings as JSON string | | --tiktok <json> | TikTok settings as JSON string | | --facebook <json> | Facebook settings as JSON string | | --youtube <json> | YouTube settings as JSON string | | --linkedin <json> | LinkedIn settings as JSON string | | --labels <ids...> | Label IDs to attach (max 50) |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Content item ID | | name | string|null | Content item name | | brand_id | string | Brand ID | | label_ids | string[] | Attached label IDs | | created_by | string|null | Creator user ID | | thumbnail_timestamp | number | Thumbnail timestamp (seconds) | | copy_mode | string|null | single | per_platform | | single_copy | object|null | Canonical shared caption + hashtags | | platform_copy | object|null | Canonical per-platform caption map | | instagram_settings | object|null | Instagram configuration | | tiktok_settings | object|null | TikTok configuration | | facebook_settings | object|null | Facebook configuration | | youtube_settings | object|null | YouTube configuration | | linkedin_settings | object|null | LinkedIn configuration | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Platform settings reference

Captions and hashtags come from canonical copy fields:

• --copy-mode single --single-copy '{"caption":"...","hashtags":["..."]}'
• --copy-mode per_platform --platform-copy '{"instagram":{"caption":"...","hashtags":[]}}'

Instagram (--instagram):

| Field | Type | Values | |-------|------|--------| | post_type | string | GRID_POST | REEL | STORY | | media_ids | string[] | Media IDs to attach | | trial_reel | boolean | Post as trial reel (non-followers first) | | graduation_strategy | string | MANUAL | SS_PERFORMANCE |

TikTok (--tiktok):

| Field | Type | Values | |-------|------|--------| | post_type | string | VIDEO | IMAGE | CAROUSEL | | media_ids | string[] | Media IDs to attach | | privacy_level | string | PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | SELF_ONLY | | allow_comment | boolean | Allow comments (default: true) | | allow_duet | boolean | Allow duets (default: true, video only) | | allow_stitch | boolean | Allow stitches (default: true, video only) | | auto_add_music | boolean | Auto-add music (photo/carousel only) | | is_aigc | boolean | Disclose as AI-generated content | | is_commercial_content | boolean | Mark as commercial/branded content |

Facebook (--facebook):

| Field | Type | Values | |-------|------|--------| | post_type | string | FB_POST | FB_STORY | FB_REEL | FB_TEXT | | media_ids | string[] | Media IDs to attach |

YouTube (--youtube):

| Field | Type | Values | |-------|------|--------| | title | string | Video title | | description | string | Video description | | post_type | string | YT_SHORT | YT_VIDEO | | media_ids | string[] | Media IDs to attach | | privacy_level | string | PUBLIC | UNLISTED | PRIVATE | | notify_subscribers | boolean | Notify subscribers on publish |

LinkedIn (--linkedin):

| Field | Type | Values | |-------|------|--------| | post_type | string | LI_TEXT | LI_IMAGE | LI_VIDEO | LI_ARTICLE | | media_ids | string[] | Media IDs to attach | | visibility | string | PUBLIC | CONNECTIONS | | title | string | Article title (LI_ARTICLE only) | | original_url | string | Article URL (LI_ARTICLE only) |

Examples:

# Instagram grid post
wahlu post create --name "Photo post" \
  --copy-mode single \
  --single-copy '{"caption":"Hello!","hashtags":[]}' \
  --instagram '{"post_type":"GRID_POST","media_ids":["mid-123"]}'

# Cross-platform video
wahlu post create --name "Video" \
  --copy-mode per_platform \
  --platform-copy '{"tiktok":{"caption":"Check this out","hashtags":["video"]},"instagram":{"caption":"Check this out","hashtags":[]}}' \
  --tiktok '{"post_type":"VIDEO","media_ids":["mid-123"]}' \
  --instagram '{"post_type":"REEL","media_ids":["mid-123"]}'

# LinkedIn article
wahlu post create --name "Article share" \
  --copy-mode single \
  --single-copy '{"caption":"Read our latest","hashtags":[]}' \
  --linkedin '{"post_type":"LI_ARTICLE","original_url":"https://example.com","title":"Our Post"}'

Publish runs (schedule command)

Schedule content items for future publishing to specific integrations.

| Command | Description | |---------|-------------| | wahlu schedule list | List publish runs (paginated) | | wahlu schedule create <content-item-id> | Schedule a content item | | wahlu schedule update <publish-run-id> | Update a publish run (reschedule/retarget) | | wahlu schedule delete <id> | Remove a publish run (does not delete the content item) |

Create options:

| Option | Required | Description | |--------|----------|-------------| | --at <datetime> | Yes | ISO 8601 datetime (e.g. 2026-03-15T14:00:00Z) | | --integrations <ids...> | Yes | Integration IDs to publish to (max 20) |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Publish run ID | | content_item_id | string | Referenced content item ID | | scheduled_at | string | ISO 8601 datetime | | integration_ids | string[] | Integration IDs | | status | string | e.g. ready_for_processing, published, failed | | approval_status | string|null | Approval status | | source | string|null | api for API-created entries | | failure_reason | string|null | Failure reason | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Example:

wahlu schedule create content-abc \
  --at 2026-03-15T14:00:00Z \
  --integrations int-123 int-456

Queues

Queues define recurring time slots for automatic publishing.

| Command | Description | |---------|-------------| | wahlu queue list | List all queues | | wahlu queue add <queue-id> <content-item-id> | Append a content item to a queue |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Queue ID | | name | string | Queue name | | active | boolean | Whether the queue is active | | mode | string | Queue mode | | times_of_day | string[] | Scheduled times (e.g. ["09:00","17:00"]) | | timezone | string|null | IANA timezone | | next_run_at | string|null | Next scheduled publishing time | | loop | boolean | Whether to loop through posts | | content_item_ids | string[] | Ordered content item IDs in the queue | | integration_ids | string[] | Integration IDs | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Media

Upload images and videos to your media library.

| Command | Description | |---------|-------------| | wahlu media list | List media files (paginated) | | wahlu media upload <file> | Upload a local file | | wahlu media delete <id> | Permanently delete a media file |

Supported formats: .png, .jpg, .jpeg, .gif, .webp, .mp4, .mov, .webm

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Media ID (use in media_ids arrays) | | file_name | string | Original filename | | content_type | string | MIME type (e.g. image/jpeg) | | size | number | File size in bytes | | duration | number|null | Duration in seconds (video only) | | status | string | ready_for_processing | processing | completed | failed | | download_url | string|null | Signed download URL | | thumbnail_large_url | string|null | Large thumbnail | | thumbnail_small_url | string|null | Small thumbnail | | source | string|null | upload | generated | stock | scan | | description | string|null | Media description | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Upload workflow:

# Upload returns a media ID
wahlu media upload ./photo.jpg
# Uploaded photo.jpg — media ID: mid-abc123

# Use the media ID in a content item
wahlu post create --name "Photo post" \
  --copy-mode single \
  --single-copy '{"caption":"Nice!","hashtags":[]}' \
  --instagram '{"post_type":"GRID_POST","media_ids":["mid-abc123"]}'

Ideas

Save content ideas for later development into full content items.

| Command | Description | |---------|-------------| | wahlu idea list | List ideas (paginated) | | wahlu idea create <name> | Save a new idea | | wahlu idea delete <id> | Delete an idea |

Create options:

| Option | Description | |--------|-------------| | --description <text> | Detailed description (max 10000 chars) | | --type <type> | Idea type (max 50 chars) |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Idea ID | | name | string|null | Idea name/title | | description | string|null | Detailed description | | type | string|null | Idea type | | status | string | Status | | labels | string[] | Text labels | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Labels

Labels categorise and organise content items and media.

| Command | Description | |---------|-------------| | wahlu label list | List all labels | | wahlu label create <name> | Create a label | | wahlu label delete <id> | Delete a label |

Create options:

| Option | Description | |--------|-------------| | --color <hex> | Colour hex code (e.g. #ff5500) |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Label ID | | name | string | Label name | | color | string|null | Colour hex code | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Integrations (read-only)

Connected social media accounts. You need integration IDs when scheduling content items.

| Command | Description | |---------|-------------| | wahlu integration list | List connected integrations |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Integration ID (use in --integrations when scheduling) | | platform | string | instagram | tiktok | facebook | youtube | linkedin | | status | string | Connection status | | display_name | string|null | Display name on the platform | | username | string|null | Platform username/handle | | avatar_url | string|null | Profile avatar URL | | permissions | object|null | Granted permissions | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Publications (read-only)

Records of content items published to social media platforms.

| Command | Description | |---------|-------------| | wahlu publication list | List published content items (paginated) |

Response fields:

| Field | Type | Description | |-------|------|-------------| | id | string | Publication ID | | platform | string | instagram | tiktok | facebook | youtube | linkedin | | post_id | string | Source content item ID | | post_name | string|null | Content item name | | post_type | string|null | Post type | | status | string | processing | published | failed | | source | string|null | calendar (from schedule) or queue (from queue) | | failure_reason | string|null | Failure reason | | integration_id | string | Integration used | | publish_id | string|null | Platform content ID | | published_at | string | When published (ISO 8601) | | created_at | string | ISO 8601 timestamp | | updated_at | string | ISO 8601 timestamp |

Global options

| Flag | Description | |------|-------------| | --brand <id> | Use a specific brand (overrides default) | | --json | Output as JSON (available on all list/get/create/update commands) | | --help | Show help for any command | | --version | Show CLI version |

Pagination

All list commands support pagination:

| Flag | Default | Max | Description | |------|---------|-----|-------------| | --page <n> | 1 | - | Page number | | --limit <n> | 50 | 100 | Items per page |

Configuration

Config is stored at ~/.config/wahlu/config.json:

{
  "api_key": "wahlu_live_...",
  "api_url": "https://api.wahlu.com",
  "default_brand_id": "abc123"
}

Environment variables take priority over config file:

| Variable | Description | |----------|-------------| | WAHLU_API_KEY | API key | | WAHLU_API_URL | API base URL (default: https://api.wahlu.com) | | WAHLU_BRAND_ID | Default brand ID |

For AI agents

Every command supports --json for structured output:

# Get content item IDs
wahlu post list --json | jq '.[].id'

# Get integration IDs for scheduling
wahlu integration list --json | jq '.[] | {id, platform, username}'

# Find failed publications
wahlu publication list --json | jq '.[] | select(.status == "failed")'

# Create and capture the ID
CONTENT_ITEM_ID=$(wahlu post create --name "Auto post" --json | jq -r '.id')
wahlu schedule create $CONTENT_ITEM_ID --at 2026-03-15T14:00:00Z --integrations int-123

Documentation

Full documentation: wahlu.com/docs

License

MIT