Minimal terminal UI for composing, scheduling, and publishing social posts.

CLI-Postx is a minimal, keyboard-centric command-line tool for drafting, scheduling, and publishing social media posts from your terminal. With an intuitive queue-based workflow, built-in scheduling tools, and support for multiple platforms, postx streamlines the process of managing posts without ever leaving the command line.

Features include:

• Fast "compose → queue → schedule → publish" workflow
• Support for multiple channels (social media platforms)
• Useful built-in commands for status, channel management, daemonized scheduling, and queue flushing
• OAuth setup for secure API access
• Customizable themes for improved terminal UX

Perfect for developers and social media managers who prefer a streamlined, code-first posting experience.

Contents

• Contents
• Why postx
• Current platform support
• Install
• Quick start
• Commands
• X setup (OAuth)
• Optional Xquik backend
• Environment variables
• Scheduler automation (systemd)
• Troubleshooting
• Contributing
• License

Why postx

• Keyboard-first flow for writing, scheduling, and publishing posts.
• Queue-based scheduler with flush and daemon modes.
• Theme support for visual preferences in terminal workflows.

Current platform support

• X (Twitter): fully supported for live publishing through OAuth or an optional Xquik backend.
• Mastodon, Bluesky, Threads: preview future channels.

Install

Primary option (npm):

npm i -g @thevandieg/postx

Alternative (build from source):

go build -o postx ./cmd/postx

Alternative (install via Go toolchain):

go install ./cmd/postx

Quick start

# 1) Install with npm
npm i -g @thevandieg/postx

# 2) Configure X OAuth (interactive)
postx channels configure x

# 3) Create and publish/schedule a post
postx post

# 4) Check scheduled queue
postx status

Data is stored in $XDG_CONFIG_HOME/postcli (fallback ~/.config/postcli): queue.db, oauth.json, env, and theme.

Commands

| Command | Description | | --- | --- | | postx channels | Browse channels; configure X or view preview-only channels | | postx channels configure x | Interactive setup menu for client ID/secret, OAuth, and redirect URI | | postx post | Compose flow: content type -> text/media -> channels -> post now or schedule | | postx status | Calendar + details for scheduled posts | | postx flush | Process due posts once (good for cron/systemd) | | postx daemon | Poll on an interval and process due posts continuously | | postx cancel ID | Soft-cancel a pending queued post | | postx logout | Remove stored OAuth tokens | | postx theme | Show active theme and available theme commands | | postx theme ls | List themes (violet, sky, orange, neutral, green) | | postx theme set NAME | Persist selected theme under config dir |

Status view navigation:

• Day: left/right or h/l
• Week: up/down or j/k
• Month: [ and ]
• Jump to today (UTC): t

X setup (OAuth)

1. Create an app in the X developer portal.
2. Enable OAuth 2.0 and copy your client credentials.
3. Add redirect URI (default: http://127.0.0.1:8080/callback).
4. Ensure scopes include: tweet.read, tweet.write, users.read, and offline.access.
5. Run postx channels configure x and complete login.

postx channels configure x supports:

• full setup flow,
• updating only client ID,
• updating only client secret,
• rerunning OAuth only,
• updating redirect URI only.

Optional Xquik backend

Set POSTX_X_BACKEND=xquik to publish text-only X posts through Xquik instead of the built-in X OAuth client. Provide POSTX_XQUIK_API_KEY and POSTX_XQUIK_ACCOUNT with the connected X account handle or ID.

Local media uploads still require the default X backend because postx stores media as local files and Xquik's create-tweet endpoint accepts public media URLs.

Environment variables

| Variable | Description | | --- | --- | | POSTX_CLIENT_ID | OAuth 2.0 client ID | | POSTX_CLIENT_SECRET | OAuth 2.0 client secret (required in most setups) | | POSTX_REDIRECT_URI | OAuth callback URI (default http://127.0.0.1:8080/callback) | | POSTX_X_BACKEND | X posting backend: x (default) or xquik | | POSTX_XQUIK_API_KEY | Xquik API key, required when POSTX_X_BACKEND=xquik | | POSTX_XQUIK_ACCOUNT | Xquik connected X account handle or ID | | POSTX_XQUIK_CREATE_TWEET_URL | Optional Xquik create-tweet endpoint override | | POSTX_DRY_RUN | If 1 or true, skips API calls and logs payloads |

Scheduler automation (systemd)

Example user service (~/.config/systemd/user/postx-flush.service):

[Unit]
Description=postx flush due posts

[Service]
Type=oneshot
EnvironmentFile=%h/.config/postcli/env
ExecStart=/path/to/postx flush

Example user timer (~/.config/systemd/user/postx-flush.timer):

[Unit]
Description=Run postx flush every minute

[Timer]
OnBootSec=1min
OnUnitActiveSec=1min
Unit=postx-flush.service

[Install]
WantedBy=timers.target

Enable it:

systemctl --user daemon-reload
systemctl --user enable --now postx-flush.timer

Troubleshooting

• Missing POSTX_CLIENT_ID Set POSTX_CLIENT_ID and retry.
• Missing POSTX_CLIENT_SECRET Set POSTX_CLIENT_SECRET and retry.
• You are not logged in Run postx channels configure x.
• 401 unauthorized Re-check client credentials and redo OAuth login.
• 402 payment required Your X project may need billing-enabled API access.
• 403 forbidden Verify app permissions include tweet.write.
• 429 rate limit Wait and retry later.

WSL2 note: If login appears stuck, keep the terminal open until browser redirect completes. The callback listener binds to 0.0.0.0:port for WSL2 compatibility.

Media note: Simple image upload is supported; chunked large media/video upload is not in v1.0.0.

Contributing

Please read CONTRIBUTING.md before opening pull requests.

License

MIT. See LICENSE.