Posty: Social Media Scheduler

AI エージェントでの使用

このパッケージには、エージェント向けに作成されたコマンドの完全なリファレンス SKILL.md が含まれています。インストール後、エージェントにこれを見せれば、追加の説明なしで CLI 全体を使用できます。

このリポジトリには Claude Code プラグインが 2 つ同梱されています。意図的に別々にしています。

• posty：会話用の MCP コネクター（Claude アプリ、Cowork、Claude Code）。ブラウザーからサインインでき、キーは不要です。Posty の MCP ツールを使用し、マシンには何もインストールしません。
• posty-cli：ターミナルを作業画面とするコーディングエージェント（Claude Code、Codex、OpenClaw、Hermes）向けのコマンドラインツールと完全なリファレンスです。

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

ChatGPT では、同じ MCP サーバーが公式プラグインです：https://posty.hu/ai/chatgpt

---

Posty CLI

コマンドラインから、または AI エージェントからソーシャルメディアの投稿をスケジュールできます。

Posty はソーシャルメディアのスケジューラーで、この CLI はそのコマンドラインインターフェースです。ウェブアプリと同じパブリック API を使用します。ここでスケジュールした投稿は Posty のカレンダーに表示され、ウェブアプリでスケジュールした投稿もこちらから確認できます。

Posty には意図的に AI ライターを組み込んでいません。すでに優れたモデルに料金を支払っているのであれば、CLI を使うことで、そのモデルから直接カレンダーに投稿を登録でき、2 つのウィンドウ間でコピーする必要がありません。SKILL.md は AI エージェント向けに作成されています。Claude、ChatGPT、Codex、Muse、OpenClaw、Hermes に見せれば、追加の説明なしで CLI 全体を使用できます。

コマンド、フラグ、出力が英語なのは意図的です。コマンドラインは開発者とエージェント向けです。アプリ内の製品自体は引き続きハンガリー語です。

インストール

npm install -g posty-cli
# or
pnpm install -g posty-cli

パッケージ名は posty-cli、コマンド名は posty です。 この 2 つの名前が異なるのは意図的です。npm では単独の名前 posty は無関係なプロジェクトが使用しているため、npm install -g posty を実行すると、気付かないうちに他者のパッケージがインストールされます。

認証

オプション 1：OAuth2（推奨）

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

CLI は認証情報を ~/.posty/credentials.json に、モード 0600 の 0700 ディレクトリ内に保存します。このファイルは設定とは別なので、logout を実行すると秘密情報だけが消去され、設定はそのまま残ります。

オプション 2：API キー — サーバー、CI、またはエージェント向けです。

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

アカウントをまだお持ちでない場合：ターミナルから作成できます

posty auth:signup --email [email protected]            # e-mails a code, asks for it and for the terms
posty auth:signup --email [email protected] --code 123456 --accept-terms --workspace-name "Anna Kávézó"

Posty はそのアドレスに 6 桁のコードをメールで送信します。本人がコードをあなたに伝えるか、プロンプトに入力します。本人は利用規約（https://posty.hu/aszf）とプライバシー通知（https://posty.hu/adatvedelem）に同意する必要があります。本人が同意したことを --accept-terms で示すか、コマンドの実行時にターミナルで確認します。新しいアカウントの全ワークスペースキーは auth:login と同じ方法で保存され、表示されることはありません。この方法で作成したアカウントには無料トライアルがありません。本人が支払いを行うまでは billing:* コマンドしか使えないため、次の手順は posty billing:plans と posty billing:subscribe です。すでにアカウントがあるアドレスは拒否されます（posty auth:login でサインインしてください）。ターミナル以外で初回実行した場合、コードの送信のみが行われ、次に実行するコマンドが表示されます。そのコマンドには初回実行時のすべてのオプション（--api-url、--language、--workspace-name、--timezone）が含まれます。タイムゾーンは、config:set で保存した値があればそれを使用し、なければこのマシンのタイムゾーンを使用します。支払い後、API アクセスがあるプラン（billing:plans の apiAndMcpAccess: true）でのみ、すべてのコマンドにキーを使用できます。Alap には API アクセスがないため、本人が選ぶ前にその点を伝えてください。--workspace は引き続きグローバルなワークスペース ID のフラグです。新しいワークスペースの名前には --workspace-name を使用します。

ワークスペース

認証情報は、1つまたは複数のワークスペースにアクセスできます（承認ページで「All my workspaces」にチェックを入れるか、設定で複数ワークスペース用のキーを作成します）。チャンネル ID はワークスペースに属するため、CLI はどのワークスペースを使うか把握する必要があります。

posty workspaces:list          # what this credential can act on; "current" marks the active one
posty workspaces:use <id>      # every following command acts on that workspace
posty workspaces:current       # the one commands act on now
posty posts:list --workspace <id>   # one command in another workspace

キーが複数のワークスペースにまたがる場合、auth:login では使用するワークスペースを選択します。選択内容はログイン情報とともに（または環境変数のキーの場合は ~/.posty/config.json に）保存されます。POSTY_WORKSPACE と --workspace を指定すると、1つのシェルまたはコマンドで選択内容を上書きできます。ワークスペースが選択されていない複数ワークスペース用キーは、workspaces:list を除くすべてのルートで API から 403 で拒否されるため、推測したワークスペースに投稿されることはありません。

コマンド

チャンネルを見つける

posty integrations:list                      # connected channels and their ids
posty integrations:list --group <group-id>   # one customer's channels
posty integrations:groups                    # groups (customers)
posty integrations:settings <id>             # settings schema, rules, character limit
posty integrations:trigger <id> <method>     # channel-specific lookup

投稿を作成する

# Simple scheduled post
posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i "<id>"

# Draft
posty 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 first
IMG=$(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 once
posty posts:create -c "Content" --date "2026-12-31T12:00:00Z" -i "<id1>,<id2>"

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

# Complex post from JSON
posty posts:create --json post.json

posts:create を実行すると、毎回 Idempotency-Key（実行ごとに新しい UUID）が送信されます。ネットワーク障害または 5xx エラーの後は、同じキーで1回再試行するため、サーバーは投稿を重複して作成せず、すでに作成した投稿を返します。コマンドをもう一度実行すると新しい投稿になります。エラーが発生した場合は、まず posts:list を確認してください。

投稿を管理する

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

分析

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

analytics:post が {"missing": true} を返した場合、投稿はすでに公開されていますが、プラットフォームから有効な ID が返されていません。その場合は、次の手順を実行します。

posty posts:missing <post-id>                     # available content from the provider
posty posts:connect <post-id> --release-id "<id>" # connect it
posty analytics:post <post-id>                    # works now

メディア

posty upload file.jpg

**-m に指定できるのは、posty upload が返したパスだけです。**ファイル名のみ（photo.jpg）や外部 URL（https://...）は使えません。プラットフォームが受け付けるのは、Posty が提供するアドレスだけだからです。

設定

posty config:set timezone Europe/Budapest
posty config:get
posty workspaces:use <id>          # see "Workspaces" above

FotoAI の画像と動画

キー所有者自身の FotoAI アカウントとクレジットを使って画像や動画を生成し、ワークスペースのメディアライブラリに保存できます。保存されたメディアは posts:create ですぐに使用できます。Posty で FotoAI に接続するのは1回だけです（/integraciok/fotoai）。未接続の場合、コマンドにそのリンクが表示されます。キーには 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 <id> --wait 60                                  # status, and the outputs saved in the media library

fotoai:generate は --yes を指定した場合にのみクレジットを消費し、直前に提示された価格を超えることはありません（FotoAI が代わりに PRICE_CHANGED を返します）。生成に失敗した場合、料金はかかりません。fotoai:get は fotoai.hu 自体で作成した生成結果もインポートできます。同じものを2回インポートした場合は、同じメディアが返されます。

サブスクリプション

エージェントは、「Pro の年間プランに登録して」という依頼から、有効なサブスクリプションの作成まで進められます。人が行う必要がある唯一の手順は、Stripe Checkout で本人の Link ウォレットまたはカードを使って支払うことです。

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)

**使い切りカードやエージェントが発行したカードで決済しないでください。**Posty のサブスクリプションは月次または年次で更新されます。使い切りカードでは最初の更新時に決済に失敗し、プランが終了します。リンクを契約者に渡して決済してもらい、設定を続ける前に posty billing:status を実行して確認してください。

billing:subscribe と billing:manage を使うには、フルワークスペースキー（posty auth:login の承認ページで「the whole workspace」にチェックを入れる）または OAuth トークンが必要です。これらは、ワークスペースの料金を支払う本人（または、まだ支払い担当者がいない場合はワークスペースのオーナー）が保持する必要があります。スコープ付きキーを使用すると、その旨を示すメッセージとともに拒否されます。4つのコマンドは、ワークスペースに API アクセス付きプランがない場合でもすべて使用できます。プランを利用可能にするためのコマンドです。

チャンネル固有の設定

正確なスキーマは常に posty integrations:settings <id> に表示される内容です。 概要は次のとおりです。

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 は 必須です。値は 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 または story です。投稿先にできるのはページであり、個人プロフィールには投稿できません。

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 は 必須です。値は post または story です。

Threads — threads、Bluesky — bluesky

設定はありません。--settings フラグは省略してください。

完全なスキーマ：PROVIDER_SETTINGS.md。

AI エージェント向け

検出。 エージェントに推測させないでください。integrations:list で実際に接続されているチャンネルが確認でき、integrations:settings <id> で受け付けられる設定が確認できます。integrations:list にないチャンネルには投稿できません。

出力の仕様。 コマンドは結果を JSON として stdout に出力し、ステータス行とエラーは stderr に出力します。失敗すると、0 以外の終了コードで終了します。

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

JSON モード。 複雑なキャンペーンでは、投稿内容をファイルに書き込み、--json とともに渡してください。動作する例は examples/ にあります。

スレッド。 -c を繰り返してスレッドを作成します。最初の項目が投稿で、残りはコメントです。各 -m は、その直前の -c に対応します。

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 の単位は 分 であり、秒ではありません。

よくあるワークフロー

チャンネルごとに異なるテキストで、複数のチャンネルにキャンペーンを投稿する — JSON ファイルに書き込み、--json とともに渡してください。詳しくは examples/multi-platform-with-settings.json を参照してください。

スクリプトから毎週スケジュールする：

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

公開前に文字数制限を確認する：

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

環境変数

変数	必須	デフォルト	用途
POSTY_API_KEY	いいえ	—	auth:login の代わりに使用する API キー
POSTY_API_URL	いいえ	https://posty.hu/api	API エンドポイントを上書きします
POSTY_TIMEZONE	いいえ	—	オフセットのない日時に使う IANA タイムゾーン
POSTY_WORKSPACE	いいえ	—	複数のワークスペースにまたがるキーのワークスペース ID（workspaces:use を参照）
POSTY_AUTH_SERVER	いいえ	https://posty.hu	OAuth2 サーバー（セルフホストの場合）
POSTY_CLIENT_NAME	いいえ	posty-cli	デバイス承認時に表示されるクライアント名

日付とタイムゾーン

単独の "2026-12-31 12:00" は曖昧です。CLI は 時刻がずれたまま気付かず公開するのではなく、エラーで終了します。次の順にタイムゾーンを確認します。

1. 日付に明示されたオフセット — 2026-12-31T12:00:00Z または +01:00
2. --timezone Europe/Budapest
3. POSTY_TIMEZONE
4. posty config:set timezone Europe/Budapest

いずれも設定されていない場合、コマンドはエラーで終了し、解決方法を4つすべて表示します。タイムゾーン値に数値オフセットは指定できません。

エラー処理

CLI はすべてのエラーを stderr に出力し、0 以外の終了コードで終了します。stdout はクリーンで、機械可読な状態を保ちます。

エラー	意味
--date is required...	スケジュールには日付が必要です。または -t now を使用してください
--integrations is required...	チャンネルが指定されていません。integrations:list を実行してください
naive date error	タイムゾーンがどこにも設定されていません。上記を参照してください
Integration not found	ID が正しくないか、チャンネルがすでに接続されていません
401 "no plan with API access"	キーに問題はありませんが、ワークスペースにプランが必要です：billing:plans、billing:subscribe
403 "missing the required permission"	キーは有効ですが、そのスコープがありません。必要なスコープを持つキーを作成してください。再ログインしても解決しません
401 / 403 otherwise	認証の期限切れ、または取り消しです。posty auth:login

開発

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.git
cd posty-agent
pnpm install
pnpm run build          # tsup → dist/index.js
node dist/index.js --help

スクリプト	動作
pnpm run build	dist/ にコンパイルします
pnpm run dev	変更を監視して再コンパイルします
pnpm run release:check	パッケージと公開設定を確認します（公開はしません）

クイックリファレンス

# Authentication
posty auth:status
posty auth:login
posty auth:signup --email <address>
posty auth:logout

# Workspaces
posty workspaces:list
posty workspaces:use <id>

# Discovery
posty integrations:list
posty integrations:settings <id>
posty integrations:trigger <id> <method>

# Posting
posty 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

# Management
posty posts:list
posty posts:delete <id>
posty posts:delete-group <group>
posty posts:status <id> --status draft
posty posts:find-slot <id>
posty upload <file>
posty upload:link
posty upload:files <id>

# Analytics
posty analytics:platform <id> -d 30
posty 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:plans
posty billing:subscribe --tier pro --period yearly
posty billing:status
posty billing:manage

ファイルがこのマシンにない場合

posty upload はディスク上のファイルをアップロードします。画像や動画がスマートフォン上にある場合、または CLI を実行するエージェントからファイルシステムが見えない場合は、アップロードリンクを作成します。

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

各項目の path を posts:create -m に渡します。リンクの有効期間は2時間で、複数のファイルをアップロードでき、作成時に指定した1つのワークスペースにのみアップロードできます。

ドキュメント

• SKILL.md — AI エージェント向けに書かれたコマンドの完全なリファレンス
• HOW_TO_RUN.md — ソースからのインストールと実行方法
• PROVIDER_SETTINGS.md — チャンネルごとの設定スキーマ
• SUPPORTED_FILE_TYPES.md — 受け付けられるメディアタイプ

サポートされているチャネル

チャネル	identifier	設定
X (Twitter)	x	who_can_reply_post が必須
Facebook (Pages)	facebook	post_type
Instagram	instagram	post_type が必須
LinkedIn	linkedin	必須項目なし
TikTok	tiktok	privacy_level、content_posting_method が必須
YouTube	youtube	title、type が必須
Threads	threads	なし
Bluesky	bluesky	なし
Telegram	telegram	なし
Discord	discord	channel が必須（channels ツールから取得）
Slack	slack	channel が必須（channels ツールから取得）

integrations:list では、実際に利用できるチャネルを確認できます。この表は Posty がサポートするチャネルを示し、コマンドの出力には接続済みのチャネルが表示されます。

貢献

1. プロジェクトをフォークします
2. ブランチを作成します（git checkout -b feature/something）
3. ビルドして、動作を確認します：pnpm run build && node dist/index.js --help
4. プルリクエストを作成します

リンク

• ウェブサイト：posty.hu
• npm：posty-cli
• GitHub：norbertlevente/posty-agent

ライセンス

AGPL-3.0。LICENSE ファイルを参照してください。

© 2026 Kiss Industries