> For the complete documentation index, see [llms.txt](https://socialcli.gitbook.io/socialcli-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://socialcli.gitbook.io/socialcli-docs/cli-reference.md).

# CLI Reference

## CLI Reference

**Install:**

```bash
npm install -g social-cli
```

Or run without installing:

```bash
npx social-cli --help
```

### Authentication

```bash
social-cli auth:set --key <apiKey>   # Save API key locally
social-cli auth:check                # Verify key and show workspace info
social-cli auth:whoami               # Show current saved key
social-cli auth:logout               # Remove saved key
```

### Accounts

```bash
social-cli accounts list                           # List all connected accounts
social-cli accounts health                         # Check OAuth token validity
social-cli accounts connect <platform>             # Get OAuth URL to connect
social-cli accounts disconnect <accountId>         # Disconnect an account
social-cli accounts bluesky <handle> <appPass>     # Connect Bluesky directly
```

Supported platforms: `twitter` `instagram` `facebook` `linkedin` `tiktok` `youtube` `pinterest` `reddit` `telegram` `discord` `bluesky` `snapchat` `googlebusiness` `threads`

### Posts

```bash
social-cli posts list [--status <s>] [--platform <p>] [--limit <n>]
social-cli posts create -c <text> -p <platform> -a <accountId> [options]
social-cli posts get <postId>
social-cli posts delete <postId>
social-cli posts retry <postId>
social-cli posts stats
social-cli posts validate -c <text> -p <platform> -a <accountId>
```

**Cross-posting to multiple platforms:**

```bash
social-cli posts create \
  -c "Cross-platform launch!" \
  -p twitter -a <twitterId> \
  -p instagram -a <instagramId> \
  -p linkedin -a <linkedinId> \
  --now
```

### Media Upload

```bash
social-cli upload <filePath>          # Upload local file, returns publicUrl
social-cli upload:url                 # Get raw presigned S3 URL
```

Supported types: `image/jpeg` `image/png` `image/gif` `image/webp` `video/mp4` `video/quicktime` `application/pdf`

**Workflow:**

```bash
social-cli upload ./photo.jpg
# Returns: { "publicUrl": "https://media.socialcli.dev/..." }

social-cli posts create \
  -c "Post with image!" \
  -p twitter -a <accountId> \
  --media "https://media.socialcli.dev/..." \
  --media-type image \
  --now
```

### Queue

```bash
social-cli queue list                              # Show posting schedule
social-cli queue set --slots <file.json> --timezone <tz>
social-cli queue next                              # Show next available slot
social-cli queue preview [--count <n>]             # Preview upcoming N slots
```

### Profile

```bash
social-cli profile get
social-cli profile update [--name <name>] [--description <desc>] [--color <hex>]
```

### Analytics and Usage

```bash
social-cli analytics [--platform <p>] [--from <date>] [--to <date>]
social-cli usage
```

### Twitter/X Engagement

```bash
social-cli twitter retweet <accountId> <tweetId>
social-cli twitter bookmark <accountId> <tweetId>
social-cli twitter follow <accountId> <targetUserId>
social-cli twitter unfollow <accountId> <targetUserId>
```

### Environment Variables

| Variable             | Description                                                              |
| -------------------- | ------------------------------------------------------------------------ |
| `SOCIAL_CLI_API_KEY` | Required - your API key                                                  |
| `SOCIAL_CLI_API_URL` | Optional - custom backend URL (default: `https://backend.socialcli.xyz`) |

### Response Format

Every command returns JSON to stdout:

```json
{
  "status": "SUCCESS",
  "message": "Post created successfully",
  "data": {
    "postId": "post_abc123",
    "status": "scheduled",
    "scheduledFor": "2025-06-01T09:00:00Z"
  }
}
```

Errors:

```json
{
  "status": "ERROR",
  "message": "SOCIAL_CLI_API_KEY not set. Run: social-cli auth:set --key sk_...",
  "data": null
}
```

Exit code `0` on success, `1` on error - works cleanly in shell scripts and CI pipelines.

***


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://socialcli.gitbook.io/socialcli-docs/cli-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.