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

Instagram supports 1 image (single post) or 2-10 images (carousel). Requires an Instagram Professional account linked to a Facebook Page. Caption is built from title + description.

Check the current status of a post. Poll this after creating a post.

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

Status values

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