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-agentclaude plugin install posty@posty-agent        # MCP, for conversationclaude 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# orpnpm 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 browserposty auth:status    # checks the credential; a valid key whose workspace has no plan yet is reported as such, not as invalidposty 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 [email protected]            # e-mails a code, asks for it and for the termsposty auth:signup --email [email protected] --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 oneposty workspaces:use <id>      # every following command acts on that workspaceposty workspaces:current       # the one commands act on nowposty posts:list --workspace <id>   # 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 idsposty integrations:list --group <group-id>   # one customer's channelsposty integrations:groups                    # groups (customers)posty integrations:settings <id>             # settings schema, rules, character limitposty integrations:trigger <id> <method>     # channel-specific lookup

Create a post

# Simple scheduled postposty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i "<id>"
# Draftposty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -t draft -i "<id>"
# Publish now (no date needed)posty posts:create -c "Content" -t now -i "<id>"
# With media — upload the file firstIMG=$(posty upload photo.jpg | jq -r '.path')posty posts:create -c "Content" -m "$IMG" --date "2026-12-31T12:00:00Z" -i "<id>"
# Several channels at onceposty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i "<id1>,<id2>"
# With channel-specific settingsposty posts:create -c "Content" --date "2026-12-31T12:00:00Z" \  --settings '{"who_can_reply_post":"everyone"}' -i "<x-id>"
# Complex post from JSONposty 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 daysposty posts:list --startDate "..." --endDate "..." # a given rangeposty posts:delete <id>                            # delete one post (one channel)posty posts:delete-group <group>                   # delete every channel of a groupposty posts:status <id> --status draft             # back to draftposty posts:status <id> --status schedule          # queue a draftposty posts:find-slot <id>                         # next free slot

Analytics

posty analytics:platform <integration-id>        # channel, 7 daysposty analytics:platform <integration-id> -d 30  # channel, 30 daysposty analytics:post <post-id>                   # 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 providerposty posts:connect <post-id> --release-id "<id>" # connect itposty analytics:post <post-id>                    # 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/Budapestposty config:getposty workspaces:use <id>          # 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, connectUrlposty fotoai:models --category image                             # models, parameters (aspect, resolution, duration), base priceposty fotoai:generate -m image.seedream-5-lite -p "kávé a teraszon" --aspect 4:5              # the price only; nothing is spentposty fotoai:generate -m image.seedream-5-lite -p "kávé a teraszon" --aspect 4:5 --yes --wait 60  # generate; prints media[].pathposty fotoai:get <id> --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 tierposty billing:subscribe --tier pro --period yearly        # a Stripe Checkout link as JSON; nothing is chargedposty billing:subscribe --tier pro --period yearly --open # same, and open it in this machine's browserposty 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 <id> shows. In short:

X (Twitter) — x

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

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 "<facebook-id>"

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 "<instagram-id>"

post_type is required: post or story.

Threads — threads, Bluesky — bluesky

No settings. Omit the --settings flag.

Full schema: PROVIDER_SETTINGS.md.

For AI agents

Discovery. Do not let the agent guess. integrations:list shows the channels that are actually connected, and integrations:settings <id> shows the accepted settings. A channel that is not in integrations:list cannot be posted to.

Output contract. The command writes the result as JSON to stdout, and status lines and errors to stderr. On failure it exits with a non-zero code:

posty integrations:list | jq -r '.[].id'

JSON mode. For a complex campaign, write the post to a file and pass it with --json. Working examples are in examples/.

Threads. Repeat -c to build a thread: the first item is the post, the rest are comments. Each -m belongs to the -c in front of it:

posty posts:create \  -c "First post"     -m "$(posty upload one.jpg | jq -r '.path')" \  -c "Second post" \  -c "Third post" -m "$(posty upload three.jpg | jq -r '.path')" \  -d 2 \  --date "2026-12-31T12:00:00Z" -i "<id>"

-d is in minutes, not seconds.

Common workflows

A campaign on several channels, with different text per channel — write it to a JSON file and pass --json; see examples/multi-platform-with-settings.json.

Weekly scheduling from a script:

DATES=("2026-09-01T09:00:00Z" "2026-09-02T09:00:00Z" "2026-09-03T09:00:00Z")TEXTS=("Monday kickoff" "Tuesday tip" "Wednesday takeaway")
for i in "${!DATES[@]}"; do  posty posts:create -c "${TEXTS[$i]}" --date "${DATES[$i]}" -i "<id>"done

Check the character limit before publishing:

MAX=$(posty integrations:settings "<id>" | jq '.output.maxLength')

Environment variables

Dates and timezones

A bare "2026-12-31 12:00" is ambiguous. The CLI fails rather than silently publishing an hour off. It looks for a timezone in this order:

1. an explicit offset in the date — 2026-12-31T12:00:00Z or +01:00
2. --timezone Europe/Budapest
3. POSTY_TIMEZONE
4. posty config:set timezone Europe/Budapest

If none of those is set, the command fails, and the error lists all four fixes. You cannot pass a numeric offset as a timezone value.

Error handling

The CLI writes every error to stderr and exits non-zero. stdout stays clean and machine-readable.

Development

src/├── index.ts        # commands and flags (yargs)├── api.ts          # HTTP client├── commands/       # posts, integrations, analytics, upload, auth, config├── dates.ts        # timezone resolution├── settings.ts     # channel settings└── output.ts       # the JSON/stderr output contract

git clone https://github.com/norbertlevente/posty-agent.gitcd posty-agentpnpm installpnpm run build          # tsup → dist/index.jsnode dist/index.js --help

Quick reference

# Authenticationposty auth:statusposty auth:loginposty auth:signup --email <address>posty auth:logout
# Workspacesposty workspaces:listposty workspaces:use <id>
# Discoveryposty integrations:listposty integrations:settings <id>posty integrations:trigger <id> <method>
# Postingposty posts:create -c "text" --date "2026-12-31T12:00:00Z" -i "<id>"posty posts:create -c "text" -t draft --date "..." -i "<id>"posty posts:create -c "text" -t now -i "<id>"posty posts:create --json file.json
# Managementposty posts:listposty posts:delete <id>posty posts:delete-group <group>posty posts:status <id> --status draftposty posts:find-slot <id>posty upload <file>posty upload:linkposty upload:files <id>
# Analyticsposty analytics:platform <id> -d 30posty analytics:post <id>posty posts:missing <id>posty posts:connect <id> --release-id "<rid>"
# Subscription (the person pays in Stripe Checkout; never with an agent card)posty billing:plansposty billing:subscribe --tier pro --period yearlyposty billing:statusposty billing:manage

When the file is not on this machine

posty upload uploads a file from disk. If the image or video is on your phone, or the agent running the CLI cannot see your filesystem, mint an upload link:

posty upload:link            # {id, url, expiresAt}# open the url anywhere (it works signed out), drop the files on itposty upload:files <id>      # {status, count, files:[{id, name, path, type}]}

Each item's path goes into posts:create -m. The link lives two hours, accepts several files, and can only upload into the one workspace it was made for.

Documentation

• SKILL.md — the full command reference, written for AI agents
• HOW_TO_RUN.md — install and run from source
• PROVIDER_SETTINGS.md — per-channel settings schemas
• SUPPORTED_FILE_TYPES.md — accepted media types

Supported channels

integrations:list shows which channels you can actually use. The table is what Posty supports; the command output is what you have connected.

Contributing

1. Fork the project
2. Create a branch (git checkout -b feature/something)
3. Build, then try it: pnpm run build && node dist/index.js --help
4. Open a pull request

Links

• Website: posty.hu
• npm: posty-cli
• GitHub: norbertlevente/posty-agent

License

AGPL-3.0, see the LICENSE file.

© 2026 Kiss Industries