@marketingblocks/mb

Command-line tool for the MarketingBlocks Social Growth Engine. Designed for AI agents and developers who need to manage social media posts from the terminal or inside automation scripts.

All output is JSON. No interactive prompts. Fully pipeable.

Requirements

• Node.js 18 or higher
• A MarketingBlocks API token → get one here

Installation

npm install -g @marketingblocks/mb
mb --help

Authentication

Export your token before running any command:

export MARKETINGBLOCKS_API_TOKEN=your_token_here

Add to .zshrc or .bashrc to make it permanent.

When generating your token, select the scopes your use case requires:

| Scope | Required for | |---|---| | social-read-channels | mb channels list | | social-create-post | mb post create | | social-read-posts | mb post list | | social-view-post | mb post find | | social-delete-post | mb post delete |

Commands

mb channels list

Lists all connected social accounts. Run this first to get channel_id values for creating posts.

mb channels list
mb channels list --types facebook,instagram
mb channels list --limit 20

Output:

{
  "total": 2,
  "channels": [
    { "channel_id": 254, "platform": "facebook", "account_name": "My Brand Page" },
    { "channel_id": 301, "platform": "instagram", "account_name": "@mybrand" }
  ]
}

mb post create

Creates and publishes or schedules a post.

Required flags:

| Flag | Values | |---|---| | --channel-id | ID from mb channels list | | --channel-type | facebook instagram linkedin twitter tiktok youtube threads | | --post-type | post reel story tweet thread | | --mode | now scheduled queued share_next |

Optional flags:

| Flag | Description | |---|---| | --caption | Post body text | | --media | Comma-separated image or video URLs | | --hashtags | e.g. "#marketing #ai" |

When --mode scheduled: also requires --schedule-time "2025-08-01 14:30" and --timezone "America/New_York"

When --channel-type youtube: also requires --youtube-title, optionally --youtube-category and --youtube-privacy (public / private / unlisted)

When --post-type thread: also requires --threads '[{"message":"First"},{"message":"Second"}]'

Examples:

# Publish to Facebook now
mb post create \
  --channel-id 254 \
  --channel-type facebook \
  --post-type post \
  --mode now \
  --caption "Hello world" \
  --hashtags "#launch"

# Schedule an Instagram post
mb post create \
  --channel-id 301 \
  --channel-type instagram \
  --post-type post \
  --mode scheduled \
  --schedule-time "2025-09-01 09:00" \
  --timezone "America/New_York" \
  --caption "Good morning"

# Upload to YouTube
mb post create \
  --channel-id 321 \
  --channel-type youtube \
  --post-type post \
  --mode now \
  --media "https://example.com/video.mp4" \
  --youtube-title "My Video Title" \
  --youtube-category 28 \
  --youtube-privacy public

# Post a Twitter thread
mb post create \
  --channel-id 443 \
  --channel-type twitter \
  --post-type thread \
  --mode now \
  --threads '[{"message":"First tweet"},{"message":"Second tweet"}]'

Output:

{
  "post_id": 10042,
  "status": "processing",
  "message": "Post processing. Check Find Post for post status."
}

After creating a post, poll its status with mb post find <post_id>.

mb post list

Lists posts from one or more platforms.

mb post list --channels facebook,instagram --limit 10 --page 1

Output includes post_id, channel_type, STATUS, permalink (if published), and error (if failed).

mb post find <post_id>

Gets the current status and details of a post. Use this to poll after mb post create.

mb post find 10042

{
  "post_id": 10042,
  "channel_type": "facebook",
  "STATUS": "published",
  "permalink": "https://www.facebook.com/..."
}

Status lifecycle: pending → processing → scheduled | queued → published | failed

mb post delete <post_id>

Removes a post from the publishing queue. Does not remove already-published posts from the social platform.

mb post delete 10042

Agent Polling Loop

Create a post and wait for confirmation:

POST_ID=$(mb post create \
  --channel-id 254 \
  --channel-type facebook \
  --post-type post \
  --mode now \
  --caption "Hello" | jq '.post_id')

while true; do
  STATUS=$(mb post find $POST_ID | jq -r '.STATUS')
  echo "Status: $STATUS"
  [ "$STATUS" = "published" ] || [ "$STATUS" = "failed" ] && break
  sleep 3
done

jq Pipelines

# Get a channel ID
mb channels list --types facebook | jq '.channels[0].channel_id'

# Poll post status
mb post find 10042 | jq -r '.STATUS'

# Get permalink
mb post find 10042 | jq -r '.permalink'

# Find all failed posts
mb post list --channels facebook,twitter | jq '.posts[] | select(.STATUS == "failed")'

YouTube Category IDs

1 Film & Animation · 2 Autos & Vehicles · 10 Music · 15 Pets & Animals · 17 Sports · 20 Gaming · 22 People & Blogs · 23 Comedy · 24 Entertainment · 25 News & Politics · 26 Howto & Style · 27 Education · 28 Science & Technology · 29 Nonprofits & Activism

Error Reference

All errors return JSON with an "error" key and exit code 1.

{ "error": "MARKETINGBLOCKS_API_TOKEN environment variable is not set." }
{ "error": "--schedule-time and --timezone are required when --mode is scheduled" }
{ "error": "--youtube-title is required when --channel-type is youtube" }

| HTTP | Meaning | |---|---| | 401 | Authentication failed — check your token | | 403 | Permission denied — add the required scope | | 400 | Bad request — check required fields | | 429 | Rate limit exceeded (max 100 req/s) |

Links

• npm package
• Get API token
• API docs