> ## Documentation Index > Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt > Use this file to discover all available pages before exploring further. # Social posts > Draft social posts as files, review them in a pull request next to the listing change, send them after the merge, and see how each one did. 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](https://docs.appeeky.com/docs/social-media.md)). ## Files ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} appeeky/social/accounts.yaml connected accounts (platform, name, id) appeeky/social/posts.jsonl recent posts and each platform's result appeeky/social/summary.md the last 30 days per platform, and what did best appeeky/social/drafts/.yaml a post to send ``` `social pull` writes the first three. You, your agent or the [weekly review](https://docs.appeeky.com/docs/spec-growth-team.md) write the drafts. ## Pull accounts and results ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec social pull # Accounts twitter (@sleepsounds), instagram (sleepsounds), tiktok (sleepsounds) # Posts 42 · 38 published # Written to appeeky/social/: accounts.yaml, posts.jsonl, summary.md. ``` `--limit ` 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 ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} # appeeky/social/drafts/2026-11-10-fan-sounds.yaml accounts: [twitter, instagram] text: "Fan sounds are here. Pick a fan, set a timer, sleep." when: "2026-11-12T16:00:00Z" media: ["https://cdn.sleepsounds.app/posts/fan.mp4"] why: "Users asked for fan sounds in 9 reviews; it shipped in 3.2." ``` | Field | Required | What it is | | - | - | - | | `accounts` | Yes | Platforms from `accounts.yaml` (`twitter` or `x`, `instagram`, `tiktok`…), or account ids. A platform name means every connected account on it | | `text` | Yes | The post | | `when` | No | When to publish, as an ISO time. Without it, the post goes out when it is sent | | `media` | No | Public image or video URLs. Instagram, TikTok and Pinterest need one | | `why` | No | Why this post, for whoever reviews the pull request | Spec adds `status`, `postId` and `sentAt` when the post is sent. Leave them out of a new draft. ## Check drafts ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec social check # ✓ appeeky/social/drafts/2026-11-10-fan-sounds.yaml # ✗ appeeky/social/drafts/2026-11-14-timer.yaml # no connected account for tiktok; when 2026-11-01T16:00:00Z is not in the future ``` `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 | Platform | Text limit | | - | - | | X (`twitter`) | 280 | | Bluesky | 300 | | Threads, Pinterest | 500 | | Instagram, TikTok | 2,200 | | LinkedIn | 3,000 | 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](https://docs.appeeky.com/docs/spec-ci.md#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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec social push # appeeky/social/drafts/2026-11-10-fan-sounds.yaml → twitter (@sleepsounds), instagram (sleepsounds), at 2026-11-12T16:00:00Z # Fan sounds are here. Pick a fan, set a timer, sleep. # Publish 1 post? They go out on the accounts above. [y/N] y # Sent 1. ``` `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: ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}} npx @appeeky/spec experiment add --type other --link instagram \ --hypothesis "A fan sounds launch post brings installs" --metric link_clicks --target 200 --days 7 ``` Once it is due, `verify` closes it from the link; `experiment close ` does it on demand. Smart links need [attribution](https://docs.appeeky.com/docs/spec-attribution.md). 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](https://docs.appeeky.com/docs/spec-growth-team.md) 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](https://docs.appeeky.com/docs/spec-ugc.md) · [Attribution](https://docs.appeeky.com/docs/spec-attribution.md) · [CI](https://docs.appeeky.com/docs/spec-ci.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.