@agendapanda/cli

CLI for Agenda Panda — schedule and manage social media posts from the terminal.

Works with X (Twitter), LinkedIn, Facebook Pages, Instagram, Threads, Bluesky, and TikTok.

Install

npm install -g @agendapanda/cli && ap init

Quick start

New user? Run the setup wizard:

ap init

ap init walks you through authentication, workspace selection, connecting your first platform (with OAuth polling), and optionally sending a test post.

Manual setup (for scripting / CI):

# Authenticate — opens API key settings page in browser, then prompts for key
ap auth login --browser

# Or pass the key directly
ap auth login --key "ap_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Check who you are
ap whoami

# Select a workspace
ap projects list
ap projects use <project-id>

# Connect a platform (opens browser, waits for OAuth to complete)
ap connections add x
ap connections add tiktok

# Set a default connection (by platform name — no UUID needed)
ap connections use x

# Post immediately — that's it!
ap post "Hello from Agenda Panda CLI"

# Post to ALL connected platforms at once
ap post "Hello everywhere!" --all

# Post to specific platforms (comma-separated)
ap post "Hello X and LinkedIn" --connection twitter,linkedin

# Post with media
ap post "Check this out" --media photo.jpg

# Schedule a post
ap post "Scheduled post" --schedule "2026-03-01T14:00:00Z"

# Interactive mode — multi-select connections
ap post create

# AI-powered content (pipe context into your AI tool)
ap context | claude "Write 5 posts for this week"

Commands Reference

| Command | Description | |---------|-------------| | ap init | Guided first-run setup wizard | | ap whoami | Show current user and active workspace | | ap auth login [--browser] [--key] | Authenticate with an API key | | ap auth switch | Switch between saved API key profiles | | ap auth switch --add --name <n> --key <k> | Save a new profile | | ap auth switch --delete --name <n> | Delete a saved profile | | ap auth logout | Clear stored credentials | | ap auth api-keys list\|create\|revoke | Manage API keys | | ap projects list\|use\|get\|update | Manage workspaces | | ap connections list | List connected social accounts | | ap connections add <platform> | Connect a platform via OAuth | | ap connections use <platform\|id> | Set a default connection (x, bluesky, or ID) | | ap connections clear | Unset the default connection | | ap connections health [--watch] | Check connection health (live with --watch) | | ap post "text" | Post immediately using default connection | | ap post "text" --all | Post to all connected platforms | | ap post "text" --connection x,linkedin | Post to specific platforms | | ap post "text" --media <file> | Post with media attached | | ap post "text" --schedule <datetime> | Schedule a post | | ap post create | Interactive post creation (multi-select) | | ap post list\|get\|delete\|retry\|update | Manage posts | | ap alias set\|list\|delete | Manage command aliases | | ap calendar import\|sync\|pull | Bulk content calendar operations | | ap context [--json] [--verbose] | Dump brand context for AI tools | | ap media upload <file> | Upload an image or video | | ap update | Update CLI to the latest version | | ap completion bash\|zsh\|fish | Generate shell completion scripts |

Supported platforms: twitter / x, linkedin, facebook / fb, instagram / ig, threads, bluesky / bsky, tiktok / tt

Shell autocomplete

# Bash
source <(ap completion bash)

# Zsh
ap completion zsh >> ~/.zshrc && source ~/.zshrc

# Fish
ap completion fish > ~/.config/fish/completions/ap.fish

Aliases

Create shortcuts for common workflows:

# Create shortcuts
ap alias set tw "post --connection <twitter-id>"
ap alias set ig "post --connection <instagram-id>"

# Use them
ap tw "Hello X"
ap ig "Hello Instagram" --media photo.jpg

# List all aliases
ap alias list

# Delete an alias
ap alias delete tw

Calendar

Import

Bulk-create posts from a JSON array:

[
  {
    "content": "Post text here",
    "connection": "<connection-id>",
    "schedule": "2026-03-15T14:00:00Z"
  }
]

ap calendar import --file posts.json
ap calendar import --file posts.json --dry-run   # preview without creating

Sync

Two-way sync using external_id for stable identity:

[
  {
    "content": "Updated text",
    "connection": "<connection-id>",
    "schedule": "2026-03-15T14:00:00Z",
    "external_id": "post-001"
  }
]

ap calendar sync --file cal.json
ap calendar sync --file cal.json --delete-missing   # remove posts not in file

Pull

Fetch current posts as a CalendarItem JSON array:

ap calendar pull --file cal.json
ap calendar pull --from 2026-03-01 --to 2026-03-31
ap calendar pull --include-published

Round-trip workflow:

ap calendar pull --file cal.json        # pull current state
# edit cal.json (or feed to AI with ap context)
ap calendar sync --file cal.json        # push changes back

Configuration

Config is stored at ~/.config/agendapanda/config.json (follows XDG Base Directory convention, respects $XDG_CONFIG_HOME).

Environment variables

| Variable | Description | |----------|-------------| | AP_API_KEY | API key (overrides stored key) | | AP_API_URL | API base URL (default: https://agendapanda.com) | | AP_PROJECT | Active project ID (overrides stored value) | | AP_CONNECTION | Default connection ID (overrides stored value) |

API key profiles

Save multiple API keys and switch between them:

ap auth switch --add --name work --key ap_abc123
ap auth switch --add --name personal --key ap_def456
ap auth switch --name work
ap auth switch --list
ap auth switch --delete --name personal

JSON output

All commands support --json for machine-readable output. JSON mode is also enabled automatically when stdout is piped.

Response envelopes:

• Lists: { "items": [...] }
• Mutations: { "success": true, "item": {...} }
• Errors: { "error": "message", "code": "ERROR_CODE" } (stderr)

Schedule format

All schedule times must be UTC ISO 8601 with Z suffix:

"schedule": "2026-03-15T14:00:00Z"   # correct
"schedule": "2026-03-15T14:00:00"    # rejected (no Z)

License

MIT