schedulala

CLI for the Schedulala Developer API — schedule social media posts from your terminal or AI agent.

Quick Start

# Authenticate
npx schedulala init --email [email protected]

# Create a post
npx schedulala post "Hello world!" --platforms twitter --now

# Check status
npx schedulala post:status <post-id>

Installation

# Use directly with npx (no install needed)
npx schedulala <command>

# Or install globally
npm install -g schedulala

Requires Node.js 18+ (uses built-in fetch). Zero runtime dependencies.

Authentication

Interactive (device auth flow)

schedulala init --email [email protected]

This starts a device authorization flow — you'll get a verification code to enter at schedulala.com. Your API key is saved to ~/.schedulala/config.json.

Non-interactive (environment variable)

export SCHEDULALA_API_KEY=sk_live_...
schedulala whoami

Per-command override

schedulala whoami --api-key sk_live_abc123

Priority order: --api-key flag > SCHEDULALA_API_KEY env > config file

Commands

Posts

# Create a post (publish immediately)
schedulala post "Hello world!" --platforms twitter --now

# Schedule a post
schedulala post "Scheduled post" --platforms twitter,linkedin --schedule "2025-06-15T10:00:00Z"

# Save as draft
schedulala post "Draft idea" --platforms instagram --draft

# Add to auto-scheduling queue
schedulala post "Queued post" --platforms twitter --queue

# With media
schedulala post "Check this out" --platforms instagram --media "https://example.com/photo.jpg" --now

# Platform-specific content
schedulala post "Default text" --platforms twitter,linkedin \
  --platform-content '{"twitter":{"content":"Tweet version"},"linkedin":{"content":"LinkedIn version"}}' \
  --now

# List posts
schedulala post:list --status published --limit 10

# Get post status
schedulala post:status <id>

# Watch until published/failed
schedulala post:status <id> --watch

# Delete a post
schedulala post:delete <id>

# Retry a failed post
schedulala post:retry <id>

Accounts

# List connected accounts
schedulala accounts

# Filter by platform
schedulala accounts --platform twitter

# Health check all accounts
schedulala accounts:health

# Get OAuth URL to connect a new account
schedulala connect twitter --brand-id <id>

Info

# Show current user and plan
schedulala whoami

# Show API usage and limits
schedulala usage

Configuration

# Set a config value
schedulala config set api_key sk_live_abc123

# Get a config value
schedulala config get api_key

# List all config
schedulala config list

# Show config file path
schedulala config path

JSON Output (for scripts and AI agents)

Every command supports --json for structured output:

# Returns JSON to stdout, no human formatting
schedulala post:list --json

# Errors are also structured JSON
schedulala whoami --json  # returns {"error":{"message":"...","code":2}} on auth failure

In --json mode:

• Success data goes to stdout as JSON
• No human-readable text is printed
• Errors are structured JSON: {"error":{"message":"...","code":N}}

AI Agent Usage

This CLI is designed for AI agents (Claude, GPT, etc.) that need to schedule social media posts:

# Agent authenticates once
export SCHEDULALA_API_KEY=sk_live_...

# Create post and get the ID
POST_ID=$(schedulala post "Hello!" --platforms twitter --now --json | jq -r '.post.id // .post._id')

# Watch until published
schedulala post:status $POST_ID --watch --json

# Check usage limits
schedulala usage --json

Best practices for agents:

1. Always use --json for parseable output
2. Set SCHEDULALA_API_KEY as an environment variable
3. Use --idempotency-key to prevent duplicate posts
4. Check usage --json before creating posts to avoid hitting limits
5. Use post:status --watch to confirm delivery

Global Flags

| Flag | Description | |------|-------------| | --json | Output JSON (for scripts/agents) | | --api-key <key> | Override API key for this command | | --base-url <url> | Override API base URL | | --verbose | Show request/response details | | --help, -h | Show help | | --version, -V | Show version |

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Authentication error (401/403) | | 3 | Validation error (400) | | 4 | Not found (404) | | 5 | Rate limited (429) | | 6 | Server error (5xx) | | 7 | Network error |

Environment Variables

| Variable | Description | |----------|-------------| | SCHEDULALA_API_KEY | API key (overrides config file) | | SCHEDULALA_API_URL | API base URL (overrides config file) | | NO_COLOR | Disable colored output |

Config File

Configuration is stored at ~/.schedulala/config.json with 0600 permissions:

{
  "api_key": "sk_live_...",
  "email": "[email protected]",
  "base_url": "https://schedulala.com"
}

Supported Platforms

Twitter, Instagram, Facebook, LinkedIn, TikTok, Threads, Bluesky, YouTube, Pinterest, Telegram

Links

• Developer Docs
• API Reference
• Dashboard