# 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):**

```bash
npx -y @socialneuron/mcp-server sn <command>
```

**Global install (recommended for frequent use):**

```bash
npm install -g @socialneuron/mcp-server
socialneuron-mcp sn <command>
```

:::tip
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 |

```bash
# Authenticate (opens browser)
socialneuron-mcp login --device

# Verify your session
socialneuron-mcp sn info

# Sign out
socialneuron-mcp logout
```

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.

```bash
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" \
  --confirm
```

| 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.

```bash
socialneuron-mcp sn quality-check \
  --caption "5 tips for better engagement on Instagram" \
  --platforms "instagram,linkedin" \
  --threshold 25
```

| 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.

```bash
socialneuron-mcp sn e2e \
  --media-url "https://example.com/video.mp4" \
  --caption "Our best tips for creators" \
  --platforms "youtube,tiktok" \
  --threshold 20 \
  --dry-run \
  --confirm
```

| 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:

```json
{
  "schema_version": "1",
  "ok": true,
  "command": "credits",
  "data": { ... }
}
```

On errors:

```json
{
  "schema_version": "1",
  "ok": false,
  "command": "publish",
  "error": "Insufficient credits",
  "errorType": "CREDITS",
  "retryable": false,
  "hint": "Purchase credits or upgrade your plan"
}
```

### Piping to Other Tools

```bash
# 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"
fi
```

## Interactive REPL

For exploratory sessions, launch the interactive REPL with tab completion:

```bash
socialneuron-mcp repl
```

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](https://socialneuron.com) and get 50 free credits to start.