Install as a skill

npx skills add sharekhq/sharek-agent

Sharek CLI

Social media automation CLI for AI agents - Schedule posts across 28+ platforms programmatically.

The Sharek CLI provides a command-line interface to the Sharek API, enabling developers and AI agents to automate social media posting, manage content, and handle media uploads across platforms like Twitter/X, LinkedIn, Reddit, YouTube, TikTok, Instagram, Facebook, and more.

Sharek CLI is a fork of postiz-agent (AGPL-3.0), adapted for Sharek.

Installation

From npm (Recommended)

npm install -g sharek-cli
# or
pnpm install -g sharek-cli

Authentication

Option 1: OAuth2 (Recommended)

Authenticate using the device flow — no key to copy:

sharek auth:login

This will:

1. Display a one-time code in your terminal
2. Open your browser to authorize
3. Automatically save credentials to ~/.sharek/credentials.json

# Check current auth status (verifies credentials are still valid)
sharek auth:status

# Remove stored credentials
sharek auth:logout

Self-Hosting the Auth Server

By default, sharek auth:login uses the hosted auth server at cli-auth.sharek.app. If you want to self-host the OAuth2 device flow server, follow the guide in server/SERVER.md and point the CLI at it with --auth-server <url> or SHAREK_AUTH_SERVER.

Option 2: API Key

Get your API key at dash.sharek.app/settings → Developers:

export SHAREK_API_KEY=your_api_key_here

Optional: Custom API endpoint

export SHAREK_API_URL=https://your-custom-api.com

Note: OAuth2 credentials take priority over the API key when both are present.

Commands

Discovery & Settings

List all connected integrations

sharek integrations:list
sharek integrations:list --group "customer-id"

Returns integration IDs, provider names, and metadata. Use --group to return only the channels assigned to a specific group (customer).

List all groups (customers)

sharek integrations:groups

Returns all groups (customers) for your organization as {id, name}. Use a group's id with integrations:list --group to filter channels.

Get integration settings schema

sharek integrations:settings <integration-id>

Returns character limits, required settings, and available tools for fetching dynamic data.

Trigger integration tools

sharek integrations:trigger <integration-id> <method-name>
sharek integrations:trigger <integration-id> <method-name> -d '{"key":"value"}'

Fetch dynamic data like Reddit flairs, YouTube playlists, LinkedIn companies, etc.

Examples:

# Get Reddit flairs
sharek integrations:trigger reddit-123 getFlairs -d '{"subreddit":"programming"}'

# Get YouTube playlists
sharek integrations:trigger youtube-456 getPlaylists

# Get LinkedIn companies
sharek integrations:trigger linkedin-789 getCompanies

Creating Posts

Simple scheduled post

sharek posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "integration-id"

Draft post

sharek posts:create -c "Content" -s "2024-12-31T12:00:00Z" -t draft -i "integration-id"

Post with media

sharek posts:create -c "Content" -m "img1.jpg,img2.jpg" -s "2024-12-31T12:00:00Z" -i "integration-id"

Post with comments (each comment can have its own media)

sharek posts:create \
  -c "Main post" -m "main.jpg" \
  -c "First comment" -m "comment1.jpg" \
  -c "Second comment" -m "comment2.jpg,comment3.jpg" \
  -s "2024-12-31T12:00:00Z" \
  -i "integration-id"

Multi-platform post

sharek posts:create -c "Content" -s "2024-12-31T12:00:00Z" -i "twitter-id,linkedin-id,facebook-id"

Platform-specific settings

sharek posts:create \
  -c "Content" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"Post Title","type":"text"}}]}' \
  -i "reddit-id"

Complex post from JSON file

sharek posts:create --json post.json

Options:

• -c, --content - Post/comment content (use multiple times for posts with comments)
• -s, --date - Schedule date in ISO 8601 format (REQUIRED)
• -t, --type - Post type: "schedule" or "draft" (default: "schedule")
• -m, --media - Comma-separated media URLs for corresponding -c
• -i, --integrations - Comma-separated integration IDs (required)
• -d, --delay - Delay between comments in minutes (default: 0)
• --settings - Platform-specific settings as JSON string
• -j, --json - Path to JSON file with full post structure
• --shortLink - Use short links (default: true)

Managing Posts

List posts

sharek posts:list
sharek posts:list --startDate "2024-01-01T00:00:00Z" --endDate "2024-12-31T23:59:59Z"
sharek posts:list --customer "customer-id"

Defaults to last 30 days to next 30 days if dates not specified.

Delete post

sharek posts:delete <post-id>

Change post status (draft ↔ schedule)

sharek posts:status <post-id> --status draft
sharek posts:status <post-id> --status schedule

Move a scheduled post back to a draft, or promote a draft into the publishing queue. Switching to draft also terminates any workflow that's already running for the post, so it won't publish. Switching to schedule queues the post for publishing at its stored date.

Analytics

Get platform analytics

sharek analytics:platform <integration-id>
sharek analytics:platform <integration-id> -d 30

Returns metrics like followers, impressions, and engagement over time for a specific integration/channel. The -d flag specifies the number of days to look back (default: 7).

Get post analytics

sharek analytics:post <post-id>
sharek analytics:post <post-id> -d 30

Returns metrics like likes, comments, shares, and impressions for a specific published post.

⚠️ If analytics:post returns {"missing": true}, the post was published but the platform didn't return a usable post ID. You must resolve this before analytics will work:

# 1. List available content from the provider
sharek posts:missing <post-id>

# 2. Connect the correct content to the post
sharek posts:connect <post-id> --release-id "7321456789012345678"

# 3. Analytics will now work
sharek analytics:post <post-id>

Connecting Missing Posts

Some platforms (e.g. TikTok) don't return a post ID immediately after publishing. The post's releaseId is set to "missing" and analytics won't work until resolved.

List available content from the provider

sharek posts:missing <post-id>

Returns an array of {id, url} items representing recent content from the provider. Returns an empty array if the provider doesn't support this feature.

Connect a post to its published content

sharek posts:connect <post-id> --release-id "<content-id>"

Media Upload

Upload file and get URL

sharek upload <file-path>

⚠️ IMPORTANT: Upload Files Before Posting

You must upload media files to Sharek before using them in posts. Many platforms (especially TikTok, Instagram, and YouTube) require verified/trusted URLs and will reject external links.

Workflow:

1. Upload your file using sharek upload
2. Extract the returned URL
3. Use that URL in your post's -m parameter

Supported formats:

• Images: PNG, JPG, JPEG, GIF
• Videos: MP4

Example:

# 1. Upload the file first
RESULT=$(sharek upload video.mp4)
PATH=$(echo "$RESULT" | jq -r '.path')

# 2. Use the Sharek URL in your post
sharek posts:create -c "Check out my video!" -s "2024-12-31T12:00:00Z" -m "$PATH" -i "tiktok-id"

Why this is required:

• TikTok, Instagram, YouTube only accept URLs from trusted domains
• Security: Platforms verify media sources to prevent abuse
• Reliability: Sharek ensures your media is always accessible

Platform-Specific Features

Reddit

# Get available flairs
sharek integrations:trigger reddit-id getFlairs -d '{"subreddit":"programming"}'

# Post with subreddit and flair
sharek posts:create \
  -c "Content" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"subreddit":[{"value":{"subreddit":"programming","title":"My Post","type":"text","is_flair_required":true,"flair":{"id":"flair-123","name":"Discussion"}}}]}' \
  -i "reddit-id"

YouTube

# Get playlists
sharek integrations:trigger youtube-id getPlaylists

# Upload video FIRST (required!)
VIDEO=$(sharek upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')

# Post with uploaded video URL
sharek posts:create \
  -c "Video description" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"title":"Video Title","type":"public","tags":[{"value":"tech","label":"Tech"}],"playlistId":"playlist-id"}' \
  -m "$VIDEO_URL" \
  -i "youtube-id"

TikTok

# Upload video FIRST (TikTok only accepts verified URLs!)
VIDEO=$(sharek upload video.mp4)
VIDEO_URL=$(echo "$VIDEO" | jq -r '.path')

# Post with uploaded video URL
sharek posts:create \
  -c "Video caption #fyp" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"privacy":"PUBLIC_TO_EVERYONE","duet":true,"stitch":true}' \
  -m "$VIDEO_URL" \
  -i "tiktok-id"

LinkedIn

# Get companies you can post to
sharek integrations:trigger linkedin-id getCompanies

# Post as company
sharek posts:create \
  -c "Company announcement" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"companyId":"company-123"}' \
  -i "linkedin-id"

X (Twitter)

# Create thread
sharek posts:create \
  -c "Thread 1/3 🧵" \
  -c "Thread 2/3" \
  -c "Thread 3/3" \
  -s "2024-12-31T12:00:00Z" \
  -d 2000 \
  -i "twitter-id"

# With reply settings
sharek posts:create \
  -c "Tweet content" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"who_can_reply_post":"everyone"}' \
  -i "twitter-id"

Instagram

# Upload image FIRST (Instagram requires verified URLs!)
IMAGE=$(sharek upload image.jpg)
IMAGE_URL=$(echo "$IMAGE" | jq -r '.path')

# Regular post
sharek posts:create \
  -c "Caption #hashtag" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"post_type":"post"}' \
  -m "$IMAGE_URL" \
  -i "instagram-id"

# Story (upload first)
STORY=$(sharek upload story.jpg)
STORY_URL=$(echo "$STORY" | jq -r '.path')

sharek posts:create \
  -c "" \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"post_type":"story"}' \
  -m "$STORY_URL" \
  -i "instagram-id"

See PROVIDER_SETTINGS.md for all 28+ platforms.

Features for AI Agents

Discovery Workflow

The CLI enables dynamic discovery of integration capabilities:

1. List integrations - Get available social media accounts
2. Get settings - Retrieve character limits, required fields, and available tools
3. Trigger tools - Fetch dynamic data (flairs, playlists, boards, etc.)
4. Create posts - Use discovered data in posts
5. Analyze - Get post analytics; if {"missing": true} is returned, resolve with posts:missing + posts:connect

This allows AI agents to adapt to different platforms without hardcoded knowledge.

JSON Mode

For complex posts with multiple platforms and settings:

sharek posts:create --json complex-post.json

JSON structure:

{
  "integrations": ["twitter-123", "linkedin-456"],
  "posts": [
    {
      "provider": "twitter",
      "post": [
        {
          "content": "Tweet version",
          "image": ["twitter-image.jpg"]
        }
      ]
    },
    {
      "provider": "linkedin",
      "post": [
        {
          "content": "LinkedIn version with more context...",
          "image": ["linkedin-image.jpg"]
        }
      ],
      "settings": {
        "__type": "linkedin",
        "companyId": "company-123"
      }
    }
  ]
}

All Output is JSON

Every command outputs JSON for easy parsing:

INTEGRATIONS=$(sharek integrations:list | jq -r '.')
REDDIT_ID=$(echo "$INTEGRATIONS" | jq -r '.[] | select(.identifier=="reddit") | .id')

Threading Support

Comments are automatically converted to threads/replies based on platform:

• Twitter/X: Thread of tweets
• Reddit: Comment replies
• LinkedIn: Comment on post
• Instagram: First comment

sharek posts:create \
  -c "Main post" \
  -c "Comment 1" \
  -c "Comment 2" \
  -i "integration-id"

Common Workflows

Reddit Post with Flair

#!/bin/bash
REDDIT_ID=$(sharek integrations:list | jq -r '.[] | select(.identifier=="reddit") | .id')
FLAIRS=$(sharek integrations:trigger "$REDDIT_ID" getFlairs -d '{"subreddit":"programming"}')
FLAIR_ID=$(echo "$FLAIRS" | jq -r '.output[0].id')

sharek posts:create \
  -c "My post content" \
  -s "2024-12-31T12:00:00Z" \
  --settings "{\"subreddit\":[{\"value\":{\"subreddit\":\"programming\",\"title\":\"Post Title\",\"type\":\"text\",\"is_flair_required\":true,\"flair\":{\"id\":\"$FLAIR_ID\",\"name\":\"Discussion\"}}}]}" \
  -i "$REDDIT_ID"

YouTube Video Upload

#!/bin/bash
VIDEO=$(sharek upload video.mp4)
VIDEO_PATH=$(echo "$VIDEO" | jq -r '.path')

sharek posts:create \
  -c "Video description..." \
  -s "2024-12-31T12:00:00Z" \
  --settings '{"title":"My Video","type":"public","tags":[{"value":"tech","label":"Tech"}]}' \
  -m "$VIDEO_PATH" \
  -i "youtube-id"

Multi-Platform Campaign

#!/bin/bash
sharek posts:create \
  -c "Same content everywhere" \
  -s "2024-12-31T12:00:00Z" \
  -m "image.jpg" \
  -i "twitter-id,linkedin-id,facebook-id"

Batch Scheduling

#!/bin/bash
DATES=("2024-02-14T09:00:00Z" "2024-02-15T09:00:00Z" "2024-02-16T09:00:00Z")
CONTENT=("Monday motivation 💪" "Tuesday tips 💡" "Wednesday wisdom 🧠")

for i in "${!DATES[@]}"; do
  sharek posts:create \
    -c "${CONTENT[$i]}" \
    -s "${DATES[$i]}" \
    -i "twitter-id"
done

Documentation

For AI Agents:

• SKILL.md - Complete skill reference with patterns and examples

Deep-Dive Guides:

• HOW_TO_RUN.md - Installation and setup methods
• COMMAND_LINE_GUIDE.md - Complete command syntax reference
• PROVIDER_SETTINGS.md - All platform settings schemas
• INTEGRATION_TOOLS_WORKFLOW.md - Tools workflow guide
• INTEGRATION_SETTINGS_DISCOVERY.md - Settings discovery
• SUPPORTED_FILE_TYPES.md - Media format reference
• PROJECT_STRUCTURE.md - Code architecture
• PUBLISHING.md - npm publishing guide

Examples:

• examples/EXAMPLES.md - Comprehensive examples
• examples/ - Ready-to-use scripts and JSON files

API Endpoints

The CLI interacts with these Sharek API endpoints:

| Endpoint | Method | Purpose | |----------|--------|---------| | /public/v1/posts | POST | Create a post | | /public/v1/posts | GET | List posts | | /public/v1/posts/:id | DELETE | Delete a post | | /public/v1/posts/:id/missing | GET | Get missing content from provider | | /public/v1/posts/:id/release-id | PUT | Update release ID for a post | | /public/v1/integrations | GET | List integrations (optional ?group= filter) | | /public/v1/groups | GET | List groups (customers) | | /public/v1/integration-settings/:id | GET | Get integration settings | | /public/v1/integration-trigger/:id | POST | Trigger integration tool | | /public/v1/analytics/:integration | GET | Get platform analytics | | /public/v1/analytics/post/:postId | GET | Get post analytics | | /public/v1/upload | POST | Upload media |

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | SHAREK_API_KEY | No* | - | Your Sharek API key | | SHAREK_API_URL | No | https://dash.sharek.app/api | Custom API endpoint | | SHAREK_AUTH_SERVER | No | https://cli-auth.sharek.app | Custom auth server URL |

*Either OAuth2 (via sharek auth:login) or SHAREK_API_KEY is required.

Error Handling

The CLI provides clear error messages with exit codes:

• Exit code 0: Success
• Exit code 1: Error occurred

Common errors:

| Error | Solution | |-------|----------| | Not authenticated | Run sharek auth:login or set SHAREK_API_KEY | | Integration not found | Run integrations:list to get valid IDs | | startDate/endDate required | Use ISO 8601 format: "2024-12-31T12:00:00Z" | | Invalid settings | Check integrations:settings for required fields | | Tool not found | Check available tools in integrations:settings output | | Upload failed | Verify file exists and format is supported | | analytics:post returns {"missing": true} | Run posts:missing <id> then posts:connect <id> --release-id "<rid>" |

Development

Project Structure

src/
├── index.ts              # CLI entry point with yargs
├── api.ts                # SharekAPI client class
├── config.ts             # Configuration (OAuth2 + API key)
└── commands/
    ├── auth.ts           # OAuth2 authentication (login/logout/status)
    ├── posts.ts          # Post management commands
    ├── integrations.ts   # Integration commands
    ├── analytics.ts      # Analytics commands
    └── upload.ts         # Media upload command
examples/                 # Example scripts and JSON files
package.json
tsconfig.json
tsup.config.ts            # Build configuration
README.md                 # This file
SKILL.md                  # AI agent reference

Scripts

pnpm run dev       # Watch mode for development
pnpm run build     # Build the CLI
pnpm run start     # Run the built CLI

Building

The CLI uses tsup for bundling:

pnpm run build

Output in dist/:

• index.js - Bundled executable with shebang
• index.js.map - Source map

Quick Reference

# Authentication
sharek auth:login                                              # OAuth2 device flow
sharek auth:status                                             # Check auth
sharek auth:logout                                             # Remove credentials
export SHAREK_API_KEY=your_key                                 # Or use API key

# Discovery
sharek integrations:list                           # List integrations
sharek integrations:list --group "<group-id>"      # List integrations in a group
sharek integrations:groups                         # List groups (customers)
sharek integrations:settings <id>                  # Get settings
sharek integrations:trigger <id> <method> -d '{}'  # Fetch data

# Posting (date is required)
sharek posts:create -c "text" -s "2024-12-31T12:00:00Z" -i "id"                    # Simple
sharek posts:create -c "text" -s "2024-12-31T12:00:00Z" -t draft -i "id"          # Draft
sharek posts:create -c "text" -m "img.jpg" -s "2024-12-31T12:00:00Z" -i "id"      # With media
sharek posts:create -c "main" -c "comment" -s "2024-12-31T12:00:00Z" -i "id"      # With comment
sharek posts:create -c "text" -s "2024-12-31T12:00:00Z" --settings '{}' -i "id"   # Platform-specific
sharek posts:create --json file.json                                               # Complex

# Management
sharek posts:list                                  # List posts
sharek posts:delete <id>                          # Delete post
sharek posts:status <id> --status draft           # Move to draft (stops workflow)
sharek posts:status <id> --status schedule        # Queue draft for publishing
sharek upload <file>                              # Upload media

# Analytics
sharek analytics:platform <id>                    # Platform analytics (7 days)
sharek analytics:platform <id> -d 30             # Platform analytics (30 days)
sharek analytics:post <id>                        # Post analytics (7 days)
sharek analytics:post <id> -d 30                 # Post analytics (30 days)
# If analytics:post returns {"missing": true}, resolve it:
sharek posts:missing <id>                         # List provider content
sharek posts:connect <id> --release-id "<rid>"    # Connect content to post

# Help
sharek --help                                     # Show help
sharek posts:create --help                        # Command help

Contributing

This CLI is part of the Sharek monorepo.

To contribute:

1. Fork the repository
2. Create a feature branch
3. Make your changes in apps/cli/
4. Run tests: pnpm run build
5. Submit a pull request

License

AGPL-3.0

Links

• Website: dash.sharek.app
• CLI GitHub: sharekhq/sharek-agent
• App GitHub: sharekhq/sharek-app
• Issues: Report bugs

Supported Platforms

28+ platforms including:

| Platform | Integration Tools | Settings | |----------|------------------|----------| | Twitter/X | getLists, getCommunities | who_can_reply_post | | LinkedIn | getCompanies | companyId, carousel | | Reddit | getFlairs, searchSubreddits | subreddit, title, flair | | YouTube | getPlaylists, getCategories | title, type, tags, playlistId | | TikTok | - | privacy, duet, stitch | | Instagram | - | post_type (post/story) | | Facebook | getPages | - | | Pinterest | getBoards, getBoardSections | - | | Discord | getChannels | - | | Slack | getChannels | - | | And 18+ more... | | |

See PROVIDER_SETTINGS.md for complete documentation.