# MarketingCLI

> Post to social media via MCP server, REST API, or CLI. Supports TikTok and Instagram.

## MCP Server (Recommended for AI Agents)

    npx -y marketingcli-mcp
    Env: MARKETINGCLI_API_KEY=mk_live_YOUR_KEY

Tools: list_accounts, get_account, create_post, get_post_status, list_posts, get_usage

## REST API Quick Start

Base URL: https://marketingcli.dev/api/v1
Auth: Bearer token via `Authorization: Bearer mk_live_YOUR_KEY` header
Docs: https://marketingcli.dev/docs

## Complete Workflow

Step 1: List accounts to get an account_id

    GET /api/v1/accounts
    Optional query: ?platform=tiktok
    → Returns { "data": [{ "id": "ACCOUNT_ID", "platform": "tiktok", "username": "...", ... }] }

Step 2: Post content (images vary by platform)

    POST /api/v1/accounts/{account_id}/posts
    Content-Type: multipart/form-data
    Form fields: images (file[], required), title (string), description (string),
                 platform_options (JSON string with platform-specific settings)
    → Returns 202 { "data": { "post_id": "...", "publish_id": "...", "status": "processing" } }

    Alternative (JSON body with hosted image URLs):
    POST /api/v1/accounts/{account_id}/posts/json
    Content-Type: application/json
    Body: { "image_urls": ["https://...jpg", ...], "title": "...", "description": "...", "platform_options": {...} }
    → Same response format

Step 3: Check post status

    GET /api/v1/posts/{post_id}/status
    → Returns { "data": { "post_id": "...", "platform": "tiktok", "status": "published|sent|processing|failed", ... } }

## Other Endpoints

    GET /api/v1/accounts/{account_id}    — Get account details + platform-specific data
    GET /api/v1/posts?limit=20&offset=0  — List recent posts
    GET /api/v1/usage                    — Current plan usage (posts_used, posts_limit)

## Platform Options

TikTok platform_options:
    privacy_level: SELF_ONLY (default), PUBLIC_TO_EVERYONE, MUTUAL_FOLLOW_FRIENDS, FOLLOWER_OF_CREATOR
    disable_comment: boolean (default: false)
    auto_add_music: boolean (default: true)
    photo_cover_index: integer (default: 0)
    Media: 2-35 images per slideshow

Instagram platform_options:
    location_id: string (Facebook Place ID, optional)
    user_tags: array of {username, x, y} (optional)
    collaborators: array of usernames (optional)
    Media: 1 image (single post) or 2-10 images (carousel)

## Error Codes

    400  Bad request (invalid params, wrong media count for platform)
    401  Invalid or missing API key
    402  Active subscription required
    404  Account or post not found
    429  Monthly post limit reached

## CLI

    pip install git+https://github.com/davidedicillo/tikclock.git#subdirectory=cli
    marketingcli configure --api-key mk_live_YOUR_KEY

    marketingcli accounts                                    # List accounts (all platforms)
    marketingcli post -a ACCOUNT_ID -t "Title" -d "#tags" img1.jpg img2.jpg  # Post
    marketingcli status POST_ID                              # Check status
    marketingcli posts -n 10                                 # List posts
    marketingcli usage                                       # Plan usage

All CLI commands support -j / --json-output for machine-readable JSON output.

## Backwards Compatibility

The old /tiktok_accounts/... endpoints still work as aliases:
    GET /api/v1/tiktok_accounts         → same as /accounts?platform=tiktok
    POST /api/v1/tiktok_accounts/{id}/photos → same as /accounts/{id}/posts