CLI Commands

Posts

Create a Post

chirpie post "Your post text here"

# Schedule a post
chirpie post "Launching tomorrow!" -s "2026-04-01T14:00:00Z"

# Save a draft to finish later
chirpie post "Half an idea" --draft

# Post with an image
chirpie post "Check this out!" -m https://example.com/screenshot.png

# Post to a specific account
chirpie post "Hello!" -a 550e8400-e29b-41d4-a716-446655440000

# Post to several accounts in one call
chirpie post "Hello everywhere!" -a ACCOUNT_A -a ACCOUNT_B

# Give one account its own text
chirpie post "Hello everywhere!" -a ACCOUNT_A -a ACCOUNT_B \
  --config '{"ACCOUNT_B":{"text":"Hello, longer version for this one."}}'

Put the link in the first comment:

chirpie post "We rebuilt scheduling this week." \
  --first-comment "Full write-up: https://example.com/blog/scheduling"

A multi-account post prints one line per account, and the call reports a failure for any account the platform refused while the others stay published. See Post to several accounts at once.

Create a Thread

chirpie thread "First post" "Second post" "Third post"

Minimum 2 posts, maximum 25, or 1 to 25 with --draft.

A thread is atomic: if any part fails, every part that had already published is deleted from the platform and the whole thread's quota is refunded. In the rare case a part could not be removed, the CLI prints it under "Still live on the platform, delete these yourself" with its link, and the error code is thread_rollback_incomplete rather than upstream_error, because retrying would publish it twice.

# The same thread to two accounts, with a longer version for the second
chirpie thread "First post" "Second post" -a ACCOUNT_A -a ACCOUNT_B \
  --config '{"ACCOUNT_B":{"posts":[{"text":"a"},{"text":"b"},{"text":"c"}]}}'

List Posts

chirpie posts

A post you deleted stays in the listing, with status deleted: a delete takes the post down from the platform and never removes your record of it.

Get Post Details

chirpie posts get <post_id>

Update a Post

Edit a post that has not published yet, or finish a draft.

chirpie posts update <post_id> --text "Now with the typo fixed"
chirpie posts update <post_id> --schedule-at 2027-04-02T09:00:00Z

Only a post that has not gone out can be edited. Rescheduling one post of a thread moves every part of it.

Publish a Draft

chirpie posts publish <post_id>
chirpie posts publish <post_id> --text "The final wording"

Every rule and the monthly quota apply at this point, so a draft that would be refused stays a draft, unchanged. A draft thread publishes whole.

Delete a Post

chirpie posts delete <post_id>

On a published post, delete takes it down from the platform and succeeds only once the platform confirms it is gone. Nothing reaches a platform for a post that has not gone out: a queued one is cancelled and its quota returned, and a draft is simply marked deleted, since a draft never counted against anything. Chirpie keeps the post in every case, marked deleted, so it stays in your history and in chirpie posts --status deleted. A published TikTok post, a Facebook Page story, or a post on an Instagram account connected through Instagram rather than via Facebook, cannot be deleted, so it is refused with delete_unsupported: delete it in the platform's own app, and hide it here if you do not want to see it. See the delete table.

Retry a First Comment

Post a first comment that failed, again. It re-sends the text the post already carries. That text cannot be changed once the post is out, so set it while the post is still a draft or still queued with chirpie posts update <post_id> --first-comment "..." instead.

chirpie posts first-comment <post_id>

A first comment never fails its post, so a published post can be carrying one that did not go out. A retry that works counts as one post against your monthly quota, exactly as the first attempt would have.

Hide a Post

chirpie posts hide <post_id>
chirpie posts unhide <post_id>

Hiding takes a post out of your Chirpie listings and nothing else. Nothing reaches the platform: the post stays exactly as it is, keeps its analytics and its comments, and unhide puts it back. A thread, or a multi-account send, is hidden as the one thing it was made as.

Hiding a queued post does not stop it publishing: the scheduler pays no attention to it. Use chirpie posts delete to stop a scheduled post going out.

List them again with chirpie posts --include-hidden.

Drafts

A draft is saved and nothing else: nothing reaches the platform and nothing counts against your quota until you promote it. Saving one prints, one per line, anything that would go wrong if it were sent as it stands.

# Save it
chirpie post "Half an idea" --draft

# See what is saved
chirpie posts --status draft

# Change the time it remembers, still a draft
chirpie posts update <post_id> --schedule-at 2027-04-02T09:00:00Z --keep-draft

# Queue it
chirpie posts update <post_id> --schedule-at 2027-04-02T09:00:00Z

# Or send it now
chirpie posts publish <post_id>

Comments

List Comments on a Post

chirpie comments list <post_id>

The table shows a short comment ID, the author, the time, the comment text, its state (hidden or deleted, blank for a live comment), and a tick under replied for a comment you have already answered. The author is the display name, falling back to the handle; your own replies show the connected account's name. A deleted comment keeps its text. When the stored comments could not be refreshed, the reason is printed above the table.

Reply to a Comment

chirpie comments reply <post_id> <comment_id> --text "Yes, that works."

A reply is published to the platform like any other post, so it counts as one post against your monthly quota.

Hide a Comment

chirpie comments hide <post_id> <comment_id>
chirpie comments hide <post_id> <comment_id> --unhide

Facebook, Instagram and Threads support hiding. Everywhere else the command reports that the platform has no hide rather than pretending it worked.

Delete a Comment

chirpie comments delete <post_id> <comment_id>

On Facebook and Instagram you can delete any comment on a post you published. Everywhere else you can delete only replies you wrote. On Facebook, Instagram, Threads and LinkedIn the replies under a deleted comment are deleted with it; see what happens to the replies.

A delete cannot be undone, so it asks first. In a script or any other non-interactive shell there is nobody to ask, so pass -y or the command stops without deleting anything.

The post and comment IDs can be the short ones the tables show, or the full ones from --json. See IDs.

Accounts

List Accounts

chirpie accounts

Shows a table of all connected accounts with platform, username, display name, scheduled post count, and active status.

Inactive accounts are listed too, with a ✗ under active. An account marked over plan limit is connected but not publishing because your plan's account limit was already full when it was connected. Activate it below, or upgrade.

Activate or Deactivate an Account

chirpie accounts activate <id>
chirpie accounts deactivate <id>

Use the short account ID chirpie accounts shows, or the full one from chirpie accounts --json. --json may go before or after the account ID: chirpie accounts deactivate <id> --json and chirpie accounts --json deactivate <id> are equivalent.

Chirpie never discards a connected account when your plan runs out of room. One Facebook authorization can grant several Pages at once; Chirpie stores every Page and switches on as many as your plan allows, leaving the rest inactive. These two commands choose which ones publish. Deactivating keeps the account connected and frees a plan slot, so you can activate a different one without reauthorizing.

# Park one Page and switch on another
chirpie accounts deactivate 550e8400-e29b-41d4-a716-446655440000
chirpie accounts activate 7c9e6679-7425-40de-944b-e07fc1f90ae7

# Read the result from a script
chirpie accounts deactivate 550e8400-e29b-41d4-a716-446655440000 --json | jq '.canceled_posts'

Activating past your plan's account limit fails with a plan-limit error.

Disconnect an Account

chirpie accounts disconnect <id>

Ends the connection. The account stops publishing immediately and stops counting against your plan's account limit, and Chirpie lets go of the credential it stored for it.

A disconnect cannot be undone, so it asks first. In a script or any other non-interactive shell there is nobody to ask, so pass -y or the command stops without disconnecting anything.

# Ask first, then disconnect
chirpie accounts disconnect 550e8400-e29b-41d4-a716-446655440000

# From a script
chirpie accounts disconnect 550e8400-e29b-41d4-a716-446655440000 -y --json | jq '.canceled_posts'

Disconnect when you are done with the account. Deactivate instead when you mean to switch it on again: deactivating keeps the stored credential, so activating needs no reauthorization, while connecting a disconnected account again means authorizing it on the platform again. Posts the account already published are kept either way.

Connect an X Account

chirpie accounts connect-x

Prints an authorization URL. Open it in your browser to complete the X OAuth flow.

Every connect-* command accepts --json, which prints the raw result instead of the human-readable line.

Connect a Bluesky Account

chirpie accounts connect-bluesky --handle <handle> --app-password <password>

# Example
chirpie accounts connect-bluesky --handle mybot --app-password xxxx-xxxx-xxxx-xxxx

Anything not shaped like an app password, your account password included, is refused before any request is made, with bluesky_app_password_required and the same message the API gives. The value is never printed.

Connect a LinkedIn Account

chirpie accounts connect-linkedin
chirpie accounts connect-linkedin --pages   # the LinkedIn Pages you administer (coming soon)

Prints an authorization URL. Open it in your browser to complete the LinkedIn OAuth flow.

Connect a Threads Account

chirpie accounts connect-threads

Prints an authorization URL. Open it in your browser to complete the Meta OAuth flow for Threads.

Connect a Mastodon Account

chirpie accounts connect-mastodon --instance <instance>

# Examples: all three connect you on mastodon.social
chirpie accounts connect-mastodon --instance mastodon.social
chirpie accounts connect-mastodon --instance @you@mastodon.social
chirpie accounts connect-mastodon --instance https://mastodon.social/@you

A value naming no server is refused before any request with mastodon_instance_invalid.

Prints an authorization URL. Open it in your browser to complete the Mastodon OAuth flow.

Connect an Instagram Account

chirpie accounts connect-instagram
chirpie accounts connect-instagram --via facebook
chirpie accounts connect-instagram --via facebook --reconnect

Prints an authorization URL. Open it in your browser to finish the flow.

Both routes need an Instagram professional account (Business or Creator), and both publish, thread, schedule and report analytics identically. They differ in one way: on an account connected with --via facebook, chirpie posts delete <id> really takes a published post down, and on an account connected the default way it is refused with delete_unsupported. --via facebook also needs the Instagram account to be linked to a Facebook Page, and one run can connect several accounts at once, one per linked Page; anything past your plan's account limit is stored inactive (shown as over plan limit) rather than dropped, so use chirpie accounts activate <id> to pick.

Connecting an account you already have through the other route moves it rather than adding a second one: it keeps its id and everything it has published, and only what it can do changes, so going to --via facebook adds deleting and coming back takes it away again. Where the two routes report different Instagram accounts you get a second account instead, so run chirpie accounts afterwards to see what you have. See switching between the two routes.

Connect a Facebook Page

chirpie accounts connect-facebook
chirpie accounts connect-facebook --reconnect

Prints an authorization URL. Open it in your browser to complete the Facebook OAuth flow. You choose which Pages to grant.

Use --reconnect when the account has authorized Facebook before, so Facebook asks again about anything that was turned down last time.

If the flow finishes and no Page was imported, Facebook did not share one. Run it again and, in the Facebook window, choose Edit settings, tick every Page you want Chirpie to post to, and leave Show a list of the Pages you manage and Create and manage content on your Page turned on. Pages already connected stay connected while you retry.

Every granted Page is imported as its own account. If you grant more Pages than your plan's account limit allows, Chirpie switches on as many as it can and stores the rest inactive (shown as over plan limit in chirpie accounts), so nothing is dropped. Use chirpie accounts activate <id> to pick which Pages publish. Running this command again re-runs the import, so Pages added later are picked up without disconnecting anything.

Connect a Telegram Bot

chirpie accounts connect-telegram --bot-token <token> --chat-id <id>

More Platforms

Pinterest, TikTok, YouTube, and Google Business Profile are coming soon.

Use Your Own X Developer App

Connect X accounts through your own X app so posts use your X API credits. See Bring your own X keys for the full walkthrough.

# Set or replace your keys (prompts for the secret if --client-secret is omitted)
chirpie accounts x-keys set --client-id "YOUR_CLIENT_ID" --label "Acme social app"

# Check whether your own app is configured
chirpie accounts x-keys status

# Remove your keys
chirpie accounts x-keys remove

After setting keys, run chirpie accounts connect-x to move an account onto your app. Accounts you don't reconnect keep using whichever app connected them.

API Keys

List Keys

chirpie keys

Create a Key

chirpie keys create
chirpie keys create -n "My Bot Key"

# A narrower key: repeat --scope once per permission
chirpie keys create -n "Publishing bot" --scope posts:write --scope media:write

Allowed scopes: posts:read, posts:write, accounts:read, accounts:write, analytics:read, comments:read, comments:write, media:write, keys:write.

A key can never grant a scope it does not itself hold. chirpie keys prints each key's scopes, or all for a key with full access.

Revoke a Key

chirpie keys revoke <key_id>

Analytics

Get Post Metrics

chirpie analytics <post_id>
chirpie analytics <post_id> --refresh

Displays engagement metrics for a post. Available metrics vary by platform:

• X: impressions, likes, retweets, replies, quotes, bookmarks, and clicks
• Bluesky: likes, reposts, replies, and quotes
• LinkedIn: likes, comments, and shares
• Threads: views, likes, replies, reposts, and quotes
• Mastodon: favourites, reblogs, and replies
• Instagram: views, likes, comments, shares, and saves
• Facebook: views, reactions, comments, shares, and clicks
• Telegram: No analytics available