A post is a file
A post is a YAML file in appeeky/social/drafts/: the accounts it goes to, the text, when, the media, and why it is worth posting. It goes out through the accounts you connected in Appeeky: X, Instagram, TikTok, LinkedIn, Pinterest, Reddit, YouTube, Threads, Facebook and Bluesky.
One draft, several accounts
One file can go to accounts on several platforms. Without when it goes out as soon as it is sent; with it, it is scheduled. media takes public URLs, and the type is read from the file extension.
A platform that needs more than text gets its own block. Here TikTok is told the post promotes your own app and goes to the creator's inbox, so the AI-generated label can be added in the app, and Reddit gets its subreddit and title.
accounts: [x, tiktok:@sleepysounds, reddit:u/sleepdev]text: |Every sound now plays offline. Turn onairplane mode and sleep.when: "2026-11-19T16:00:00Z"media: ["https://…/offline.mp4"]tiktok:disclosure: own_brandinbox_draft: truereddit:subreddit: SideProjecttitle: "I made my rain sounds app work fully offline"why: "Offline was asked for in 11 reviews; it shipped in 3.3."
Naming the accounts
- Or an id from
accounts.yaml: that exact account.
accounts: [instagram]
connected in Appeeky · appeeky/social/accounts.yaml
- x Sleep Sounds✓
- tiktok @sleepysounds✓
- tiktok @rainlab✓
- instagram @sleepysounds✓
- reddit u/sleepdev✓
- youtube Sleep Sounds✓
✓ goes to 1 account
✗ social check: tiktok matches @sleepysounds, @rainlab
✓ goes to 2 accounts
✓ goes to 1 account
✓ goes to 1 account
Blocks for the platforms that need them
TikTokevery key optional
tiktok: # or friends, followers, only_me privacy: public # or none, paid_partnership disclosure: own_brand # lands in the inbox, to finish in the app inbox_draft: true # turns them off comments: false # video cover frame; photos: title, cover_index cover_time_ms: 1200
YouTubeevery key optional
youtube: # up to 100; default: the first line title: "…" # or public, private visibility: unlisted # true when made for children made_for_kids: false # AI-generated or altered synthetic_media: true
Redditrequired for Reddit
reddit: # required, with or without r/ subreddit: SideProject # up to 300; default: the first line title: "…" # makes it a link post link: https://… # when the subreddit requires one flair_id: "…"
From a file to a post, and back
Posts go the same way as a listing change. Nothing is public until a person merges, and nothing goes out twice.
- 01

Draft
Your agent, or you, writes the post as a file in appeeky/social/drafts/.
- 02

Check
social check reads it per account: length, media and each platform's own rules.
- 03

Review
Drafts and UGC briefs share the pull request with the listing change. Its check lists what the merge sends.
- 04

Send
The push workflow from init --ci, or the docker push routine, runs social push --yes. The draft gets status: sent, its post id and the time, and is committed.
- 05

Measure
The next social pull brings back views, likes, comments and shares.
What each platform takes
social check runs on every pull request and fails a draft that a platform would refuse, before anyone merges it.
X
280 characters
optional
Threads
500 characters
up to 20 images and 10 videos
Bluesky
300 characters
up to 4 images or one video, not both
Facebook
63,206 characters
up to 10 images or one video, not both
Instagram
2,200 characters
at least one image or video
TikTok
2,200 characters
at least one; at most 35 images; never images and a video
Pinterest
500 characters
at least one image or video
YouTube
5,000 characters, the description
exactly one video
Reddit
40,000 characters, the body
optional; a subreddit is required
One text, measured per platform
The same draft can be fine on Instagram and refused on X. The check measures the text against every account it goes to, and the draft fails if one of them would refuse it.
$ appeeky-spec social check · also fails a draft on
- media: []✗ Instagram needs an image or a video
- media: [a.jpg, b.mp4]✗ Bluesky: images or one video, not both
- accounts: [linkedin]✗ not connected in Appeeky
- accounts: [tiktok]✗ matches two TikTok accounts
when: "2026-11-01T09:00:00Z"✗ a time already in the past- privacy: only_me + disclosure✗ only as an inbox draft
- title: 91 characters✗ TikTok photo titles stop at 90
- title: 101 characters✗ YouTube titles stop at 100
- reddit: { title: … }✗ no subreddit; a title over 300
Every post measured, every comment seen
The numbers and the conversation come back into the repo, for you and for your agent.
Posts from Appeeky and from the apps
social pull writes the connected accounts, each post's views, likes, comments and shares, the posts you made in each platform's own app with the same numbers, recent comments and followers per account.
summary.md has the last 30 days per platform and account, and what did best across all posts. The daily workflow runs it, so it is always current.
$ npx @appeeky/spec social pullAccounts x (Sleep Sounds), tiktok (sleepysounds), reddit (sleepdev)Posts 38 through Appeeky · 36 published · 112 made in the appsComments 214Written to appeeky/social/: accounts.yaml, posts.jsonl,native-posts.jsonl, comments.jsonl, insights.yaml, summary.md.
Answered by you, drafted by the agent
social comments --unanswered lists what people asked under your posts, newest first, with the id to act on. --account, --post and --limit narrow it, and --json says whether each can be replied to, hidden, liked or deleted.
The social specialist writes a reply for each as a social reply command. It never sends one, and the weekly routines deny these commands to the agent. You run the ones you agree with.
$ npx @appeeky/spec social comments --unanswered91ab… tiktok @sleepysounds 2026-11-20 09:12mara.k: does it work on a plane??6f1c… reddit u/sleepdev 2026-11-20 07:40nightowl: Does it drain the battery overnight?Reply with: appeeky-spec social reply <id> "<message>"
Creator videos from a brief
A creator video starts as a brief in appeeky/ugc/briefs/, for one of your creator personas. After the merge the clip is made the way Appeeky UGC makes it: a still of the persona in the scene, then a talking video in their voice.
A brief per video
ugc pull writes your personas from Appeeky to personas.yaml, with whether each is ready, and the clips made so far to clips.jsonl. A persona needs a look, its reference images, before it can make clips.
The script is what the persona says out loud: one clip is about eight seconds of speech.
persona: Miascript: "I fell asleep on a plane for the first time. No wifi, just rain."scene: window seat at night, phone on the tray tablecaption: "works in airplane mode"durationSec: 8aspectRatio: "9:16"why: "Offline hooks did best on TikTok last month (summary.md)."
See the cost before anything is made
ugc generate makes a clip from each draft brief with Appeeky media credits. --dry-run shows what each costs and makes nothing. The push workflow runs ugc generate --yes after a merge and marks each brief generating, so it is made once.
$ npx @appeeky/spec ugc generate --dry-runappeeky/ugc/briefs/2026-11-19-plane.yaml Mia · 40 credits40 credits in all. Nothing was made.
Or render on your own fal key
--local runs the same pipeline where Spec runs, on your own FAL_KEY. fal bills your account and no Appeeky credits are used. The dry run shows the cost in dollars.
The clip is saved to .appeeky/media/ and the brief records clipFile, fal's videoUrl for a draft's media:, and costUsd. Set FAL_KEY as a secret and the push workflow renders locally too.
The persona can be one from Appeeky (its cover image is the look) or appeeky/ugc/personas/mia.yaml with its look images.
$ npx @appeeky/spec ugc generate --local --dry-runappeeky/ugc/briefs/2026-11-19-plane.yamlMia · 8s 9:16 · veo-3.1-fast · about $1.24 on falAbout $1.24 on your fal account in all. Nothing was made.
The social and UGC specialists
Two of the six specialists work on this. They only read: the co-founder review turns what they return into drafts and briefs in the same pull request as the week's listing change.
reads
posts.jsonl · native-posts.jsonl: which hooks did best per account
comments.jsonl: the unanswered ones
what shipped and won, the next What's New, review words
the channels and smart links that bring installs
returns
a post per connected account, within its limit
x · 63/280 · Thu 16:00
tiktok · video · own_brand · link …/l/ab12xy
replies, as commands for you to run
social reply 91ab… "Yes, fully offline."
and comments a person may want to hide
reads
- personas.yaml: which personas are ready
clips.jsonl and the briefs already waiting
UGC experiments: smart link installs and revenue
the personas in the spec, the words in reviews
returns
what won, by link installs or revenue
before/after hooks · 52 link installs · target 40
the next video, as a brief
Mia · script under 25 words · 8s · 9:16
one variable changed per experiment
why: "Offline was asked for in 11 reviews; it shipped in 3.3." ↳ appeeky/reviews/summary.md, no names
Only what the app does today, from the repo. No made-up numbers or quotes.
tiktok: disclosure: own_brand inbox_draft: true youtube: synthetic_media: true
Posts about the app are disclosed. AI-generated media goes as a TikTok inbox draft.
$ social check ✓ $ ugc generate --dry-run 40 credits in all. Nothing was made.
The co-founder only checks. Sending and making stay with the merge.
The commands
- social pull
- Accounts, posts from Appeeky and the apps, comments, followers and a 30-day summary into appeeky/social/.
- social check
- Check the drafts: accounts, length, media, TikTok, YouTube and Reddit rules, time.
- social push
- Send the drafts, now or at their when. --yes in the push workflow.
- social comments
- Comments on your posts, newest first: all of them, only the unanswered, one account or one post.
- social reply · hide · like
- Act on one comment, where the platform allows it.
- social delete-comment
- Delete a comment; asks first, or --yes outside a terminal.
- ugc pull
- Your creator personas and their clips into appeeky/ugc/.
- ugc generate
- A clip from each draft brief: --dry-run for the cost, --local on your own FAL_KEY.