Skip to main content
Posts about a new version or a won keyword work best when they go out with the change itself. With Appeeky Spec, a post is a small YAML file: drafted by you or your agent, reviewed in the same pull request as the listing change, and sent through the accounts you connected in Appeeky after the merge. Social posts need APPEEKY_API_KEY, the Startup plan or above in Appeeky, and your accounts connected in Appeeky under Growth → Social Media (Social media).

​
Files

social pull writes the first three. You, your agent or the weekly review write the drafts.

​
Pull accounts and results

--limit <n> sets how many recent posts to read (default 100). Each line of posts.jsonl is one post: its text, status, schedule and, per platform, the post URL, when it went out, any error, and the numbers the platform reports (views, impressions, reach, likes, comments, shares, reposts, saves, clicks). summary.md has, for the last 30 days:
  • the connected accounts, and any that need reconnecting in Appeeky
  • per platform: posts, times seen, likes, comments, shares and failures
  • the five posts that did best, with their links
  • posts still waiting to go out
The daily workflow and the Docker daily routine run social pull, so the results stay current.

​
Write a draft

Spec adds status, postId and sentAt when the post is sent. Leave them out of a new draft.

​
Check drafts

check reads accounts.yaml, so run social pull first. It flags:
  • a platform or id with no connected account, or one that needs reconnecting
  • text over the platform’s limit
  • Instagram, TikTok or Pinterest without media:
  • a when that is not in the future
It exits with code 1 when a draft would fail, so it can gate CI.

​
Review and send

  1. A pull request adds drafts under appeeky/social/drafts/, often next to a listing change.
  2. The pull request report lists the posts the merge would send, with their accounts, time and text, and what would fail.
  3. You merge.
  4. The push workflow from init --ci (or the Docker push routine) runs social push --yes and commits the updated drafts.
By hand:
push sends every draft still marked as a draft. Each one is created in Appeeky, which publishes it right away or at its when. The draft is then marked status: sent with the postId and sentAt, so it never goes out twice. If any draft fails check, nothing is sent until you fix it. Without --yes, push asks first; in a script with no terminal it sends nothing unless you pass --yes. The weekly agent writes drafts but is never allowed to run social push.

​
Measure

social pull brings back views, likes, comments and shares per platform. To count installs and revenue from a post, give it a smart link through an experiment, and put the link in the post:
Once it is due, verify closes it from the link; experiment close <id> does it on demand. Smart links need attribution. On iOS, links count clicks, not installs, so link_clicks is the metric for an App Store only app.

​
How agents use it

The appeeky-social specialist reads the connected accounts, how past posts did, what shipped and won, the next version’s notes, what users praise in reviews and which channels bring installs. It returns posts per platform, each with a time, media and the smart link to use. The co-founder review turns them into drafts in appeeky/social/drafts/ and checks them with social check, so they go out after the same merge. Related: UGC clips · Attribution · CI