SocialCue Documentation

Everything you need to install, configure, and use SocialCue — a self-hosted social media content calendar for agencies and freelancers.

What SocialCue does

SocialCue is a content planning and approval tool. Your team plans posts in a calendar, clients or managers approve them, and approved posts are automatically sent to Buffer which handles the actual publishing to Instagram, LinkedIn, Facebook, and more.

It replaces Planable for agencies who want to own their data and pay once instead of monthly per client.

Installation

SocialCue runs on any shared hosting with PHP 7.4 or newer — Strato, IONOS, Hostinger, cPanel hosts all work. No database needed.

1. Download your filesYou receive 5 files from Gumroad: index.html, data.php, optimize.php, generate-image.php, publish.php
2. Upload all 5 files to the same folderUse your hosting file manager or FTP. Example path: your-domain.com/socialcue/
3. Open your URL in the browserNavigate to https://your-domain.com/socialcue/ — the login screen should appear.
4. Log in with the default credentialsUsername: admin · Password: admin123
5. Change your password immediatelyAdmin → Settings → Change Password. The default password is public.

Large file uploads

If you plan to upload images over 8MB or videos, create a .htaccess file in the same folder:

php_value upload_max_filesize 512M
php_value post_max_size 512M
php_value memory_limit 256M
php_value max_execution_time 300

Supported formats: PNG, JPG, GIF, WebP (up to 50MB) · MP4, MOV, WebM (up to 500MB)

First Login Setup

After logging in for the first time, head to Admin → 🚀 Setup. SocialCue includes a built-in setup guide that checks every integration live and tells you exactly what still needs attention.

The Setup tab walks you through all six steps:

Calendar & Board

SocialCue has three views for organising content:

Month view

The default calendar view. Each post appears as a coloured chip on its scheduled date, showing the platform icon, status dot, account badge, title, and time. Click any chip to open the post detail.

Week / Day views

Tighter time-based views for daily planning. Same chips, more granular layout.

Board (Kanban)

Four columns: Draft → In Review → Approved → Published. Drag posts between columns or change status from the post detail. Great for reviewing all posts at once during a content sprint.

Filtering

Use the filter bar above the calendar to narrow posts by platform, account, or status. Multiple filters can be combined.

Creating Posts

Click + New Post in the top right (or press N) to open the post creation modal.

Post fields

AI generation

Click Generate with AI in the post modal to write a full caption from a topic idea. You can set the tone (Professional, Casual, Funny…) and language. Requires a Groq or Anthropic API key set in Admin → Settings.

Templates

Save any post as a template via the post detail menu. Load templates when creating new posts to reuse structure and content.

File format & dimension requirements

SocialCue enforces platform rules at upload time — incorrect files are blocked before they reach the server, so nothing ever ends up in your Buffer queue that can't be published.

Approval Workflow

Every post moves through a four-stage lifecycle:

Comments

Every post has a comment thread visible in the post detail. Use it for feedback, revision requests, or client notes. All comments are stored with timestamps and author names.

Activity log

The bottom of each post detail shows a full history: who created it, every status change, and when edits were made.

Roles & Users

SocialCue has four roles. Assign them in Admin → Users.

Adding users

1. Go to Admin → Users → + New User
2. Set username, password, role, and account accessApprovers should be linked to a specific account so they only see that client's content.
3. Share the login URL and credentialsSend the URL of your SocialCue install plus their username and temporary password.

Resetting a forgotten password

If a user forgets their password and there's no admin access: open data/users.json via your hosting file manager, find the user's "password" field, and replace the entire value with admin123. Log in and change it immediately.

Accounts

Accounts (also called "account layers") are how SocialCue separates clients. Each account has its own colour, initials, and Buffer token. Posts are assigned to an account when created.

Go to Admin → Accounts → + Add Account to create one. Each account can have:

• A name and colour (shown as a badge on calendar chips)
• Its own Buffer API key (so posts go to that client's Buffer queue automatically)
• Approver users linked to it (so clients only see their own content)

Buffer Publishing

SocialCue uses Buffer's API to publish posts to social media. Buffer's free plan supports 3 connected channels with unlimited queue.

Setting up Buffer

1. Create a free Buffer accountSign up at buffer.com
2. Connect your social channels in BufferInstagram, LinkedIn, Facebook, X, TikTok, etc.
3. Generate an API keyGo to publish.buffer.com/settings/api → Generate API Key → choose expiry (7 days, 30, 60, 90 days, or 1 year) → copy the key
4. Paste the key in SocialCueAdmin → Accounts → Edit → Buffer Access Token field → Save
5. Test the connectionClick "Test this token" — you should see your Buffer channels listed

How auto-publishing works

When you change a post's status to Approved, SocialCue automatically:

1. Fetches the Buffer channels connected to that account
2. Matches them to the platforms selected on the post
3. Sends the post text, image, and scheduled time to Buffer
4. Marks the post with a ⬆ icon on the calendar to confirm

Platform support via Buffer

Manual Send to Buffer

For posts already in Approved or Published status, you can also send manually: open the post detail → click Send to Buffer → select channels → send. Useful for re-sending or selecting specific channels.

The Buffer modal shows a preview of the post text and media (including a video thumbnail for video posts) before sending. Once sent, a ⬆ green badge appears on the calendar chip confirming delivery.

Auto-delete from Buffer queue

When you delete a post in SocialCue, it is also automatically removed from your Buffer queue — it will not be published. A confirmation message appears in the delete dialog when a post is queued in Buffer.

Troubleshooting Buffer

AI Text Generation

SocialCue can generate full captions from a topic idea. Two providers are supported — both configurable in Admin → Settings → AI Text Generation.

Groq (free — recommended)

1. Sign up at console.groq.comEmail only, no credit card required — takes about 60 seconds.
2. Create an API keyGo to API Keys → Create new key → copy it
3. Add to SocialCueAdmin → Settings → AI Text → select Groq → paste key → Save → Test connection

Groq uses Llama 3.3 70B — fast, high quality, completely free for typical usage.

Anthropic Claude (paid — premium quality)

1. Get a key at console.anthropic.comCredit card required. Pay-as-you-go.
2. Add to SocialCueAdmin → Settings → AI Text → select Anthropic → paste key → Save

How to use

In the New Post modal, click ✦ Generate with AI. Enter a topic or idea, select tone and language, and click Generate. The full caption is written and inserted into the post text field. You can edit it freely before saving.

AI Image Generation

Generate social media images directly in SocialCue. Two providers available in Admin → Settings → AI Image Generation.

Pollinations (free — zero setup)

Works out of the box with no account or API key. Uses open-source models. Good for quick drafts and concepts.

Ideogram (paid — higher quality)

1. Get a key at ideogram.ai/manage-api
2. Add to SocialCueAdmin → Settings → AI Images → Ideogram → paste key → Save

Ideogram produces higher quality images with better text rendering — good for branded social posts.

File Reference

Data Storage

SocialCue stores everything as JSON files in a data/ folder and uploaded media in an uploads/ folder — both auto-created on first run and protected from direct browser access via .htaccess.

your-folder/
├── index.html
├── data.php
├── optimize.php
├── generate-image.php
├── publish.php
├── data/                ← auto-created, browser-blocked
│   ├── users.json
│   ├── posts.json
│   ├── accounts.json
│   ├── platforms.json
│   ├── settings.json    ← AI keys, Buffer tokens
│   └── .htaccess
└── uploads/             ← auto-created, serves images/videos
    ├── sc_abc123.jpg
    └── .htaccess

AI keys and Buffer tokens are stored in settings.json on your server. They are never sent to the browser or logged.

Keyboard Shortcuts

Press ? anywhere in SocialCue to open the shortcuts guide. All shortcuts are disabled when a text field is focused.

Customisation

SocialCue can be white-labelled or customised for your agency. All changes are made directly in the source files.

Mentions & Tagging

Use the @ Mention button (next to "From library" in the post editor) to tag accounts, pages, or profiles in your posts. Each platform works differently.

LinkedIn — Company Pages

LinkedIn uses annotations to create real clickable tags. You need three things:

The display name is inserted into your post text. Buffer uses the Organization ID to create the real LinkedIn tag when publishing.

LinkedIn — Person mentions

Same as company pages but uses urn:li:person: URN. Person mentions only work if that person follows your Page and has tagging enabled on their profile.

Facebook — Pages

Enter the display name, Facebook Page URL, and optionally the numeric Page ID. Buffer resolves the tag on publish. Works the same as LinkedIn but uses Facebook's annotation format.

Instagram, TikTok, X / Twitter

Simply enter the @handle — it's inserted directly into your post text. The platform automatically hyperlinks it when published.

Recently used mentions

Every mention you add is saved to a per-account database (data/mentions.json). Next time you open the @ Mention modal, your recently used mentions appear as one-click chips at the top — no need to re-enter URLs or IDs.

To reset the mention database, delete data/mentions.json via FTP or your hosting file manager. It will be recreated automatically.

Image Management

Uploading images

Drag and drop files onto the upload zone, or click to browse. Supported formats and size limits vary by platform — SocialCue validates them before upload and shows a warning if something won't be accepted.

Reordering images

When you have multiple images on a post, drag any thumbnail to reorder them. The first image is always the cover — it appears first in carousels (LinkedIn, Instagram) and as the preview image. A blue Cover badge marks it clearly in both the editor and the post detail view.

Cover image

The cover badge appears on the first image whenever there are 2 or more images attached. Drag a different image to the first position to change the cover.

AI-generated images

Images generated via AI (Pollinations or Ideogram) are automatically saved to your server's uploads/ folder so Buffer can fetch them when publishing. Externally hosted images (e.g. expiring CDN links) are also downloaded and saved locally when you save the post.

Timezones

Each account can have its own posting timezone, set in Admin → Accounts → Edit. When a post is scheduled or auto-published, the time you enter is interpreted in that account's timezone and converted to UTC before being sent to Buffer.

For example: if your Swobbee NYC account is set to New York (ET) and you schedule a post for 9:00 AM, Buffer receives it as 13:00 UTC (during EDT / UTC−4).

If no timezone is set for an account, the browser's local timezone is used as a fallback. A timezone badge (e.g. New_York) is shown in the post detail view next to the scheduled time so you always know which timezone applies.

Troubleshooting

Getting support

Reply to your Gumroad purchase receipt with a description of the issue. Include: your PHP version (check in hosting control panel), any error messages, and what you were doing when it happened.

Email: info@socialcue.eu