Documentation

MarketingCLI lets you post content to social media via a REST API or CLI. Connect your account in the dashboard, generate an API key, and start posting from any HTTP client, script, or AI agent.

Authentication

All API requests require a Bearer token. Generate an API key from your dashboard.

Authorization: Bearer mk_live_YOUR_API_KEY

API keys start with mk_live_. Keep them secret.

Base URL

http://marketingcli.dev/api/v1

All endpoint paths below are relative to this base URL.

List all social media accounts connected to your user. Filter by platform with ?platform=tiktok.

curl http://marketingcli.dev/api/v1/accounts \
  -H "Authorization: Bearer mk_live_..."

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-...",
      "platform": "tiktok",
      "username": "yourhandle",
      "display_name": "Your Name",
      "is_active": true
    }
  ]
}

Get a single account's details, including platform-specific data.

curl http://marketingcli.dev/api/v1/accounts/ACCOUNT_ID \
  -H "Authorization: Bearer mk_live_..."

{
  "data": {
    "id": "a1b2c3d4-e5f6-...",
    "platform": "tiktok",
    "username": "yourhandle",
    "display_name": "Your Name",
    "is_active": true,
    "platform_data": { "privacy_level_options": ["PUBLIC_TO_EVERYONE", "SELF_ONLY"] }
  }
}

Upload media files and post to a connected social media account. Media requirements (count, type) depend on the platform.

Form Parameters

curl -X POST http://marketingcli.dev/api/v1/accounts/ACCOUNT_ID/posts \
  -H "Authorization: Bearer mk_live_..." \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "title=5 Tips for Better Sleep" \
  -F "description=Here are my favorite tips. #sleep #wellness #fyp" \
  -F 'platform_options={"privacy_level": "PUBLIC_TO_EVERYONE"}'

{
  "data": {
    "post_id": "a1b2c3d4-e5f6-...",
    "publish_id": "7349201485921038337",
    "status": "processing"
  }
}

Post using pre-hosted media URLs instead of file uploads. Same parameters as the upload endpoint, but image_urls replaces images.

curl -X POST http://marketingcli.dev/api/v1/accounts/ACCOUNT_ID/posts/json \
  -H "Authorization: Bearer mk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "image_urls": [
      "https://example.com/slide1.jpg",
      "https://example.com/slide2.jpg"
    ],
    "title": "5 Tips for Better Sleep",
    "description": "Here are my favorite tips. #sleep #wellness #fyp",
    "platform_options": {
      "privacy_level": "PUBLIC_TO_EVERYONE",
      "auto_add_music": true
    }
  }'

Response format is identical to the upload endpoint (202 with post_id).

Platform Options

Each platform accepts different options via the platform_options field. Pass these as a JSON object (or JSON string for multipart uploads).

TikTok

TikTok requires 2-35 images per slideshow post. Supported formats: JPEG, PNG, WebP.

Instagram Login

Connect a Business or Creator account directly through Instagram in Accounts. No linked Facebook Page is required. MarketingCLI currently supports single images and carousels of 2-10 images; Reels, Stories, collaborators, location tags, and user tags are not implemented. Omit platform_options for Instagram.

The title and description become the caption (combined maximum 2200 characters). File uploads are converted to JPEG and padded to fit the supported aspect ratio without cropping. Hosted URLs must already serve public HTTPS JPEG images, up to 8 MB each, with an aspect ratio from 4:5 to 1.91:1.

Instagram submissions publish automatically once processing completes. There is no TikTok-style inbox draft step. The initial response is processing; publish_id identifies the container used to track processing. Only a successful publish response or Instagram's PUBLISHED container status is reported as published.

curl -X POST http://marketingcli.dev/api/v1/accounts/INSTAGRAM_ACCOUNT_ID/posts \
  -H "Authorization: Bearer $MARKETINGCLI_API_KEY" \
  -F "[email protected]" \
  -F "title=Party Fundraisers" \
  -F "description=Parents host parties. Guests buy seats. Schools raise funds. #schoolfundraiser"

Meta app setup instructions

Meta Setup for Instagram Login

1. In Meta for Developers, create or select the MarketingCLI app and add the Instagram product/use case. Choose API setup with Instagram login, not Facebook Login.
2. Use a Professional Instagram account (Business or Creator). For development testing, add your account as an Instagram tester and accept the invitation. A Facebook Page is not required.
3. In Instagram business login settings, register the exact redirect URI https://marketingcli.dev/auth/instagram/callback.
4. Configure the app domain marketingcli.dev, website https://marketingcli.dev, privacy policy https://marketingcli.dev/privacy, terms https://marketingcli.dev/terms, and data deletion instructions https://marketingcli.dev/privacy#data-deletion.
5. Copy the Instagram App ID and Instagram App Secret from the Instagram product's setup panel into the server variables below. These may differ from the parent Meta app's credentials.
6. For customers outside your app's development roles, request the required access through App Review for instagram_business_basic and instagram_business_content_publish. Complete Meta's business verification if requested and switch the app to Live after approval. A review recording should demonstrate connecting an account and publishing a photo or carousel.

INSTAGRAM_APP_ID=your_instagram_app_id
INSTAGRAM_APP_SECRET=your_instagram_app_secret
INSTAGRAM_REDIRECT_URI=https://marketingcli.dev/auth/instagram/callback
INSTAGRAM_API_VERSION=v24.0

Redeploy after setting these variables, then use Accounts → Connect Instagram. Test one photo and one carousel, and confirm they are visible on Instagram. Long-lived tokens are renewed automatically during their final week of validity; revoked or expired authorization requires reconnecting.

Query the platform for the latest status of an existing post. A 202 submission response only means processing has started. Poll every 10 seconds while processing; do not upload again to check delivery.

curl http://marketingcli.dev/api/v1/posts/a1b2c3d4-e5f6-.../status \
  -H "Authorization: Bearer mk_live_..."

Status values

Status responses include platform_status, status_checked_at, and delivery_confirmed_at. TikTok's SEND_TO_USER_INBOX confirms an inbox notification; only PUBLISH_COMPLETE confirms publication. A 502 means the status check was unavailable. Retry the check, not the upload.

{
  "data": {
    "post_id": "a1b2c3d4-e5f6-...",
    "publish_id": "7349201485921038337",
    "status": "published",
    "fail_reason": null,
    "created_at": "2026-03-25T20:06:00+00:00",
    "published_at": "2026-03-25T20:07:12+00:00"
  }
}

List your recent posts, newest first.

Query Parameters

{
  "data": [
    {
      "post_id": "a1b2c3d4-e5f6-...",
      "publish_id": "7349201485921038337",
      "status": "published",
      "title": "5 Tips for Better Sleep",
      "image_count": 4,
      "created_at": "2026-03-25T20:06:00+00:00"
    }
  ]
}

Get your current billing period usage and limits.

curl http://marketingcli.dev/api/v1/usage \
  -H "Authorization: Bearer mk_live_..."

{
  "data": {
    "plan": "pro",
    "posts_used": 42,
    "posts_limit": 300,
    "current_period_end": "2026-04-22T00:00:00+00:00"
  }
}

Install

pip install git+https://github.com/davidedicillo/tikclock.git#subdirectory=cli

Then configure your API key:

# Save key to ~/.config/marketingcli/config.json
marketingcli configure --api-key mk_live_YOUR_KEY

# Or use an environment variable
export MARKETINGCLI_API_KEY=mk_live_YOUR_KEY

Commands

$ marketingcli accounts
Connected accounts:
  yourhandle (a1b2c3d4-e5f6-...)

# Basic post with title and description
marketingcli post -a ACCOUNT_ID \
  -t "5 Tips for Better Sleep" \
  -d "Here are my favorite tips for getting better rest. #sleep #wellness #fyp" \
  slide1.jpg slide2.jpg slide3.jpg

# Public post, no comments
marketingcli post -a ACCOUNT_ID --privacy PUBLIC_TO_EVERYONE --no-comments *.jpg

# JSON output (for AI agents and scripts)
marketingcli post -a ACCOUNT_ID -j slide1.jpg slide2.jpg

$ marketingcli status a1b2c3d4-e5f6-...
Post a1b2c3d4-e5f6-...
  Status:     published
  Publish ID: 7349201485921038337

$ marketingcli posts -n 5
Recent posts:
  a1b2c3d4...  published  5 Tips for Better Sleep  (4 images)
  b2c3d4e5...  sent       Untitled                 (2 images)

$ marketingcli usage
Plan:  pro
Usage: 42 / 300 posts
Resets: 2026-04-22

MCP Server (Recommended)

The easiest way for AI agents to use MarketingCLI. Install the MCP server and agents get typed tools — no HTTP or doc reading needed.

{
  "mcpServers": {
    "marketingcli": {
      "command": "npx",
      "args": ["-y", "marketingcli-mcp"],
      "env": { "MARKETINGCLI_API_KEY": "mk_live_YOUR_KEY" }
    }
  }
}

Available tools

Install: npm install -g marketingcli-mcp. Requires Node.js 18+.

Machine-readable reference

A plain-text API reference is also available at /llms.txt for agents that auto-discover documentation.

Using the CLI from an agent

Set the API key as an environment variable and always use -j for JSON output that's easy to parse programmatically:

export MARKETINGCLI_API_KEY=mk_live_YOUR_KEY

# Get account ID
ACCOUNT_ID=$(marketingcli accounts -j | jq -r '.data[0].id')

# Post images
RESULT=$(marketingcli post -a $ACCOUNT_ID -j \
  -t "5 Tips for Better Sleep" \
  -d "Here are my favorite tips. #sleep #wellness #fyp" \
  slide1.jpg slide2.jpg)

POST_ID=$(echo $RESULT | jq -r '.data.post_id')

# Check status
marketingcli status $POST_ID -j

End-to-end API workflow

A complete posting flow has 3 steps. Here's the full sequence with curl:

curl http://marketingcli.dev/api/v1/accounts \
  -H "Authorization: Bearer mk_live_..."

# → { "data": [{ "id": "acc_123...", "username": "yourhandle" }] }

curl -X POST http://marketingcli.dev/api/v1/accounts/acc_123.../posts \
  -H "Authorization: Bearer mk_live_..." \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "[email protected]" \
  -F "title=5 Tips for Better Sleep" \
  -F "description=Here are my favorite tips. #sleep #wellness #fyp"

# → 202 { "data": { "post_id": "post_456...", "publish_id": "734...", "status": "processing" } }

curl http://marketingcli.dev/api/v1/posts/post_456.../status \
  -H "Authorization: Bearer mk_live_..."

# → { "data": { "post_id": "post_456...", "status": "published" } }