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):
Code
Global install (recommended for frequent use):
Code
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 |
Code
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.
Code
| 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.
Code
| 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.
Code
| 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:
Code
On errors:
Code
Piping to Other Tools
Code
Interactive REPL
For exploratory sessions, launch the interactive REPL with tab completion:
Code
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.