social-plugin 0.2.4

CLI tool for AI-powered social media content generation and publishing

Social Plugin

AI-powered CLI tool for social media content generation and publishing, focused on Physical AI & Robotics.

Discovers trending topics via RSS feeds, reads reference content from local files/Google Docs/PDFs, uses AI to generate tweet and LinkedIn post drafts, and posts approved content.

Quick Start

macOS / Linux:

pipx install social-plugin
social-plugin init

Windows (PowerShell):

pipx install social-plugin
social-plugin init

The init wizard walks you through choosing an AI provider, entering API keys, setting your local docs folder, and configuring your topics.

Prerequisites

You need an API key from at least one provider:

Provider	Get API Key	Models
Anthropic	console.anthropic.com	claude-sonnet-4-5-20250929, claude-opus-4-6
OpenAI	platform.openai.com	gpt-4o, gpt-4o-mini, o1, o3-mini
Google	aistudio.google.com	gemini-2.0-flash, gemini-2.5-pro

For posting to Twitter/X, you also need API keys from developer.x.com.

Manual Install (from source)

git clone https://github.com/nirmalsharma/social-plugin.git
cd social-plugin
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
cp config/config.example.yaml config/config.yaml
cp .env.example .env
# Edit .env with your API keys
social-plugin --help

Configuration

After running social-plugin init, config is stored in:

• macOS: ~/Library/Application Support/social-plugin/config.yaml
• Linux: ~/.config/social-plugin/config.yaml
• Windows: %APPDATA%\social-plugin\config.yaml

If running from the repo directory, ./config/config.yaml takes priority (development mode).

Upgrading

When upgrading to a new version, run init --upgrade to add any new config sections while keeping all your existing settings:

pipx upgrade social-plugin
social-plugin init --upgrade

This creates a backup (config.yaml.bak), then merges new defaults into your config. Your provider, model, topics, hashtags, and all other customizations are preserved.

Multi-Provider Config

generation:
  provider: "anthropic"           # "anthropic", "openai", or "google"
  model: "claude-sonnet-4-5-20250929"  # or "gpt-4o", "gemini-2.0-flash"
  max_tokens: 4096
  temperature: 0.7

Provider is auto-detected from the model name if not set. Set the matching env var:

• ANTHROPIC_API_KEY for Claude models
• OPENAI_API_KEY for GPT/o1/o3 models
• GOOGLE_API_KEY for Gemini models

Usage

Typical Workflow

social-plugin fetch-trends       # 1. Get latest trending topics
social-plugin fetch-sources      # 2. Read local docs/PDFs
social-plugin generate           # 3. Generate AI drafts
social-plugin drafts             # 4. Review pending drafts
social-plugin approve <id>       # 5. Approve a draft
social-plugin post --id <id>     # 6. Post to Twitter/LinkedIn

Or run steps 1-3 in one command:

social-plugin run-all

All Commands

Command	Description
init	Interactive setup wizard
init --upgrade	Upgrade existing config with new defaults (preserves your settings)
config --show	Show config paths and active provider
fetch-trends	Fetch trending topics from RSS feeds
fetch-sources	Read configured Google Docs, PDFs, local files
generate	Generate 1 tweet + 1 LinkedIn draft
generate --dry-run	Preview without saving
list --last 10	List last N drafts ordered by date
drafts	List pending drafts
drafts --status all	List all drafts
show <id>	Full draft details
review <id>	Interactive review (approve/edit/regen/reject)
approve <id>	Approve for posting (also accepts failed drafts)
approve <id> -n "what you liked"	Approve with positive feedback (improves future content)
reject <id> -n "reason"	Reject with reason (required)
delete <id>	Delete a draft permanently
edit <id>	Open in $EDITOR
regen <id> -t "casual"	Regenerate with new tone
post --id <id>	Post specific draft
post --all-approved	Post all approved drafts
run-all	Full pipeline: trends + sources + generate
stats	Analytics dashboard
history --days 30	Content history
expire	Expire old pending drafts
auth-check	Verify API credentials

Content Generation Quality

Generated content benefits from several quality features:

• Fully config-driven — topic, hashtags, tone all from config.yaml; no hardcoded values in prompts
• User rules (DO's/DON'Ts) — persistent content rules the AI follows during generation (e.g. "never use clickbait"); sensible defaults built-in
• Style examples (few-shot) — paste 2-3 posts you like in config; the AI mimics your voice and structure
• Feedback loop — rejection reasons and approval notes are fed back to the LLM to improve future content
• Long-form X/Twitter posts — 280 chars by default; set x_premium: true in config for long-form posts up to 25,000 chars
• Reliable tweet posting — auto-drops appended hashtags if over character limit; auto-regenerates via LLM if still over; falls back to manual regen suggestion if no LLM available (no truncation)
• Auto-retry on over-limit — generator retries once with a stricter constraint if a tweet exceeds the character limit
• Source URL references — when referencing articles or research, generated posts include clickable source URLs
• Freshness-aware — avoids repeating content across runs by checking the last 15 drafts / 10 days of history (not just today)
• Meaningful rewrites — review choice 3 (add context) and regen produce genuinely different posts, not minor rewordings
• Source warnings — warns when no reference documents are available, suggests adding docs for richer content
• X.com + Twitter feed support — trend discovery works with both x.com and twitter.com RSS feeds
• Source-first generation — reference documents drive content; trends provide context, not headlines
• Garbled PDF detection — warns when a PDF has unreadable fonts and suggests saving as .txt instead

Draft Lifecycle

PENDING → approve → APPROVED → post → POSTED
  ↓         ↑                    ↓
reject   regen(tone)           FAILED
  ↓
REJECTED
  ↓
expire (7 days) → EXPIRED

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
python -m pytest tests/ -v

Install from TestPyPI

To test a pre-release build before it goes to PyPI:

pipx install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ social-plugin

Publishing

CI publishes automatically on tag push via GitHub Actions:

git tag v0.1.0
git push --tags

This triggers: build → TestPyPI → PyPI (sequential, OIDC trusted publishing).

License

MIT