Posty: Social Media Scheduler

Using it with an AI agent

The package includes the full command reference written for agents, SKILL.md. After install, show it to the agent and it can use the whole CLI with no further explanation.

The repo ships two Claude Code plugins, kept separate on purpose:

• `posty`, the MCP connector for conversation (Claude app, Cowork, Claude Code). Sign-in through the browser, no key; it uses Posty's MCP tools and installs nothing on your machine.
• `posty-cli`, the command-line tool and its full reference for coding agents (Claude Code, Codex, OpenClaw, Hermes), where the terminal is the working surface.

claude plugin marketplace add norbertlevente/posty-agent

claude plugin install posty@posty-agent # MCP, for conversation claude plugin install posty-cli@posty-agent # CLI, for the terminal and scripts

In ChatGPT the same MCP server is the official plugin: https://posty.hu/ai/chatgpt

---

Posty CLI

Social media scheduling from the command line, or from your AI agent.

Posty is a social media scheduler, and this is its command-line surface. It uses the same public API as the web app: what you schedule here shows up in your Posty calendar, and what you schedule there you can see here too.

Posty deliberately has no built-in AI writer. You already pay for a good model; with the CLI that model can work straight into your calendar, so you do not have to copy between two windows. SKILL.md is written for AI agents. Show it to Claude, ChatGPT, Codex, Muse, OpenClaw or Hermes and they can use the whole CLI with no further explanation.

Commands, flags and output are English on purpose: the command line is for

developers and agents. The product itself is still Hungarian in the app.

Install

npm install -g posty-cli

or

pnpm install -g posty-cli

The package is `posty-cli`, the command is `posty`.

The two names differ on purpose. On npm the bare name posty belongs to an

unrelated project, so npm install -g posty silently installs somebody

else's package.

Authentication

Option 1: OAuth2 (recommended)

posty auth:login     # device flow, opens a browser

posty auth:status # checks the credential; a valid key whose workspace has no plan yet is reported as such, not as invalid posty auth:logout # deletes stored credentials

The CLI stores credentials in ~/.posty/credentials.json, mode 0600, in a 0700 directory. The file is separate from settings, so logout clears secrets and leaves your config alone.

Option 2: API key — for a server, CI, or an agent:

export POSTY_API_KEY=your_api_key   # Settings → Developers, in the web app

No account yet: create one from the terminal

posty auth:signup --email anna@example.com            # e-mails a code, asks for it and for the terms

posty auth:signup --email anna@example.com --code 123456 --accept-terms --workspace-name "Anna Kávézó"

Posty e-mails a six-digit code to the address; the person reads it to you (or types it at the prompt). The person must agree to the terms (https://posty.hu/aszf) and the privacy notice (https://posty.hu/adatvedelem): --accept-terms says they did, or the command asks on a terminal. The new account's full-workspace key is stored like auth:login stores it and is never printed. Accounts created this way have no free trial: until the person pays, only the billing:* commands work, so the next step is posty billing:plans and posty billing:subscribe. An address that already has an account is refused (sign in with posty auth:login). Off a terminal, the first run only sends the code and prints the command to run next, with every option of the first run in it (--api-url, --language, --workspace-name, --timezone). The timezone defaults to the one saved by config:set, then to this machine's own. After the payment the key works for every command only on a plan with API access (apiAndMcpAccess: true in billing:plans); Alap has none, so say so before the person picks it. --workspace stays the global workspace id flag; the new workspace's name is --workspace-name.

Workspaces

A credential can reach one workspace or several (tick "All my workspaces" on the approval page, or make a multi-workspace key in Settings). Channel ids belong to a workspace, so the CLI has to know which one you mean:

posty workspaces:list          # what this credential can act on; "current" marks the active one

posty workspaces:use # every following command acts on that workspace posty workspaces:current # the one commands act on now posty posts:list --workspace # one command in another workspace

auth:login asks which workspace to use when the key spans several. The choice is stored with your login (or in ~/.posty/config.json for an env key); POSTY_WORKSPACE and --workspace override it for one shell or one command. A multi-workspace key with no choice made is refused by the API with 403 on every route except workspaces:list, so nothing is ever posted to a guessed workspace.

Commands

Discover channels

posty integrations:list                      # connected channels and their ids

posty integrations:list --group # one customer's channels posty integrations:groups # groups (customers) posty integrations:settings # settings schema, rules, character limit posty integrations:trigger # channel-specific lookup

Create a post

# Simple scheduled post

posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i " "

Draft

posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -t draft -i " "

Publish now (no date needed)

posty posts:create -c "Content" -t now -i " "

With media — upload the file first

IMG=$(posty upload photo.jpg | jq -r '.path') posty posts:create -c "Content" -m "$IMG" --date "2026-12-31T12:00:00Z" -i " "

Several channels at once

posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i " , "

With channel-specific settings

posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" \ --settings '{"who_can_reply_post":"everyone"}' -i " "

Complex post from JSON

posty posts:create --json post.json

Every posts:create sends an Idempotency-Key (a new UUID per run). After a network failure or a 5xx it retries once with the same key, so the server returns the post it already made instead of making a second one. Running the command again is a new post: check posts:list first after an error.

Manage posts

posty posts:list                                   # default -30 … +30 days

posty posts:list --startDate "..." --endDate "..." # a given range posty posts:delete # delete one post (one channel) posty posts:delete-group # delete every channel of a group posty posts:status --status draft # back to draft posty posts:status --status schedule # queue a draft posty posts:find-slot # next free slot

Analytics

posty analytics:platform <integration-id>        # channel, 7 days

posty analytics:platform -d 30 # channel, 30 days posty analytics:post # post, 7 days

If analytics:post returns {"missing": true}, the post is already live but the platform did not return a usable id. Then:

posty posts:missing <post-id>                     # available content from the provider

posty posts:connect --release-id " " # connect it posty analytics:post # works now

Media

posty upload file.jpg

For `-m` you may only pass a path returned by `posty upload`. Bare filenames (photo.jpg) and external URLs (https://...) do not work, because the platforms only accept addresses Posty serves.

Settings

posty config:set timezone Europe/Budapest

posty config:get posty workspaces:use # see "Workspaces" above

FotoAI images and videos

With the key owner's own FotoAI account and credits (fotoai.hu), images and videos are generated and saved into the workspace's media library, ready for posts:create. The person connects FotoAI once in Posty (/integraciok/fotoai); the commands print that link while it is missing. The key needs media:write.

posty fotoai:status                                              # connected?, as whom, credit balance, connectUrl

posty fotoai:models --category image # models, parameters (aspect, resolution, duration), base price posty fotoai:generate -m image.seedream-5-lite -p "kávé a teraszon" --aspect 4:5 # the price only; nothing is spent posty fotoai:generate -m image.seedream-5-lite -p "kávé a teraszon" --aspect 4:5 --yes --wait 60 # generate; prints media[].path posty fotoai:get --wait 60 # status, and the outputs saved in the media library

fotoai:generate spends credits only with --yes, and never more than the price it just quoted (FotoAI answers PRICE_CHANGED instead). A failed generation costs nothing. fotoai:get also imports a generation made on fotoai.hu itself; importing twice returns the same media.

Subscription

An agent can take the person from "subscribe me to Pro yearly" to a live subscription. The one step that stays human is the payment, in Stripe Checkout, with the person's own Link wallet or card.

posty billing:plans                                       # the four plans, prices in HUF, limits, trial rule, current tier

posty billing:subscribe --tier pro --period yearly # a Stripe Checkout link as JSON; nothing is charged posty billing:subscribe --tier pro --period yearly --open # same, and open it in this machine's browser posty billing:status # none | trialing | active | past_due | read_only | cancelled, plus any unpaid checkout (plan, start time, expiry) posty billing:manage # a link to the Stripe billing portal (plan change, cancel, invoices, card)

Never pay with a one-time or agent-issued card. A Posty subscription renews monthly or yearly; a one-time card fails at the first renewal and the plan ends. Give the link to the subscriber, let them pay, then run posty billing:status to confirm before continuing setup.

billing:subscribe and billing:manage need a full-workspace key (tick "the whole workspace" on the posty auth:login approval page) or an OAuth token, held by the person who pays for the workspace (or a workspace owner when nobody pays yet). A scoped key is refused with a message that says so. All four commands work before the workspace has a plan with API access: they are how it gets one.

Channel-specific settings

The exact schema is always what posty integrations:settings shows. In short:

X (Twitter) — x

posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" \

--settings '{"who_can_reply_post":"everyone"}' -i " "

who_can_reply_post is required. Values: everyone, following, mentionedUsers, subscribers, verified.

Facebook — facebook

IMG=$(posty upload photo.jpg | jq -r '.path')

posty posts:create -c "Content" -m "$IMG" --date "2026-12-31T12:00:00Z" \ --settings '{"post_type":"post"}' -i " "

post_type: post or story. You can publish to Pages, not to a personal profile.

Instagram — instagram

IMG=$(posty upload photo.jpg | jq -r '.path')

posty posts:create -c "Caption #hashtag" -m "$IMG" --date "2026-12-31T12:00:00Z" \ --settings '{"post_type":"post"}' -i " "

post_type is required: post or story.

Threads — threads, Bluesky — `