CLI Reference
The Social Neuron CLI gives you direct access to publishing, analytics, account management, and automation from your terminal. Every command is deterministic -- no AI model calls, no LLM latency. Ideal for scripts, CI/CD pipelines, and quick checks.
Installation
Run directly (no install):
npx -y @socialneuron/mcp-server sn <command>bash
Global install (recommended for frequent use):
npm install -g @socialneuron/mcp-server socialneuron-mcp sn <command>bash
After a global install, you can use socialneuron-mcp directly instead of the npx prefix. All examples below use the short form.
Authentication
Before using any command, authenticate with your Social Neuron account. Three methods are available:
| Method | Command | Best For |
|---|---|---|
| Device Flow | socialneuron-mcp login --device | Interactive terminals -- opens a browser for secure login |
| Browser | socialneuron-mcp login | Default -- same browser flow without the device code step |
| API Key Paste | socialneuron-mcp login --paste | Headless servers and CI -- paste an API key from your dashboard |
# Authenticate (opens browser) socialneuron-mcp login --device # Verify your session socialneuron-mcp sn info # Sign out socialneuron-mcp logoutbash
Credentials are stored securely in your system keychain (macOS Keychain, Linux secret-tool) or a local file fallback.
Command Reference
All commands support the --json flag for machine-readable output.
Discovery
| Command | Description |
|---|---|
sn tools | List all available MCP tools |
sn tools --module <module> | Filter tools by module (e.g., ideation, analytics) |
sn tools --scope <scope> | Filter tools by required scope (e.g., mcp:write) |
sn info | Show version, auth status, credit balance, and tool count |
Content
| Command | Description |
|---|---|
sn publish --media-url <url> --caption <text> --platforms <list> --confirm | Publish content to one or more platforms |
sn quality-check --caption <text> | Run a quality score check on your caption |
sn e2e --media-url <url> --caption <text> --platforms <list> --confirm | End-to-end publish with quality gate |
sn plan list | List your content plans |
sn plan view --plan-id <id> | View a specific content plan |
sn plan approve --plan-id <id> | Approve a content plan for publishing |
sn preset list | List platform presets (6 built-in) |
sn preset show --name <name> | Show details of a preset |
sn preset save --name <name> --platform <name> --max-length <n> --aspect-ratio <ratio> | Save a custom preset |
sn preset delete --name <name> | Delete a custom preset |
Account
| Command | Description |
|---|---|
sn preflight | Pre-publish checklist -- verify accounts and permissions are ready |
sn preflight --check-urls | Include URL validation (privacy policy, terms) |
sn oauth-health | Check token health for all connected accounts |
sn oauth-health --warn-days 7 | Warn if tokens expire within N days |
sn oauth-refresh --platforms <list> | Refresh OAuth tokens for specific platforms |
sn oauth-refresh --all | Refresh all connected platform tokens |
Analytics
| Command | Description |
|---|---|
sn posts --days <1-90> | List your recent posts |
sn posts --platform youtube --status published | Filter posts by platform and status |
sn refresh-analytics | Trigger an analytics refresh across all platforms |
sn loop | Get a closed-loop performance summary with actionable insights |
System
| Command | Description |
|---|---|
sn status --job-id <id> | Check the status of an async job (video renders, scheduled posts) |
sn autopilot | View your autopilot configuration and schedule |
sn usage | Show current usage statistics |
sn credits | Check your credit balance and spending |
Command Details
publish
Publish content to one or more social platforms.
socialneuron-mcp sn publish \ --media-url "https://example.com/video.mp4" \ --caption "Check out our new product launch" \ --platforms "youtube,instagram,tiktok" \ --title "Product Launch Video" \ --schedule-at "2026-04-15T09:00:00Z" \ --confirmbash
| Flag | Required | Description |
|---|---|---|
--media-url <url> | Yes | URL of the media file to publish |
--caption <text> | Yes | Post caption or description |
--platforms <list> | Yes | Comma-separated platform names |
--confirm | Yes | Safety flag to confirm publishing |
--title <text> | No | Post title (for platforms that support it) |
--schedule-at <iso8601> | No | Schedule for later instead of publishing immediately |
--idempotency-key <key> | No | Prevent duplicate publishes in retry scenarios |
quality-check
Run a quality analysis on your content before publishing.
socialneuron-mcp sn quality-check \ --caption "5 tips for better engagement on Instagram" \ --platforms "instagram,linkedin" \ --threshold 25bash
| Flag | Required | Description |
|---|---|---|
--caption <text> | Yes | The caption text to check |
--title <text> | No | Optional title to include in the check |
--platforms <list> | No | Target platforms for platform-specific scoring |
--threshold <0-35> | No | Minimum quality score to pass (default: auto) |
e2e (End-to-End)
Combines quality check and publish in a single command. Content is only published if it passes the quality gate.
socialneuron-mcp sn e2e \ --media-url "https://example.com/video.mp4" \ --caption "Our best tips for creators" \ --platforms "youtube,tiktok" \ --threshold 20 \ --dry-run \ --confirmbash
| Flag | Required | Description |
|---|---|---|
--dry-run | No | Simulate the full flow without publishing |
--force | No | Publish even if quality check fails |
--check-urls | No | Validate media URLs before publishing |
All publish flags are also supported.
JSON Output
Add --json to any command for structured output. Every JSON response includes:
{
"schema_version": "1",
"ok": true,
"command": "credits",
"data": { ... }
}jsonOn errors:
{
"schema_version": "1",
"ok": false,
"command": "publish",
"error": "Insufficient credits",
"errorType": "CREDITS",
"retryable": false,
"hint": "Purchase credits or upgrade your plan"
}jsonPiping to Other Tools
# Get credit balance as a number socialneuron-mcp sn credits --json | jq '.data.balance' # List posts and filter by engagement socialneuron-mcp sn posts --days 30 --json | jq '.data.posts | sort_by(.engagement) | reverse' # Check if quality passes before publishing in a script RESULT=$(socialneuron-mcp sn quality-check --caption "my post" --json) if echo "$RESULT" | jq -e '.data.passed' > /dev/null; then echo "Quality check passed" fibash
Interactive REPL
For exploratory sessions, launch the interactive REPL with tab completion:
socialneuron-mcp replbash
The REPL supports all sn subcommands and persists your authentication session.
Environment Variables
| Variable | Purpose |
|---|---|
SOCIALNEURON_API_KEY | API key for non-interactive auth (CI/CD) |
DO_NOT_TRACK=1 | Disable anonymous usage telemetry |
Ready to try this? Sign up free and get 100 credits to start.