@postonus/cli
Schedule and publish social posts from your terminal.
npm install -g @postonus/cli
postonus login
postonus post "shipping today" --to x,linkedin --optimal
Requires Node.js 22.12 or newer. Needs a Postonus account.
Run without installing: npx @postonus/cli whoami
Commands
| Command | What it does |
|---|---|
login / logout / whoami | Browser-approved sign in, and who you are |
channels list | Connected channels and their health |
channels connect | Connect a new channel over OAuth |
post <text> | Schedule a post (never publishes immediately) |
queue list | Upcoming scheduled posts |
queue move <scheduleId> --at | Reschedule one queued post |
media upload <path…> | Upload images or video for use in posts |
best-times --to <platforms> | Recommended posting windows |
postonus <command> --help for the flags on any of them.
Scheduling a post
postonus post "shipping today" --to x,linkedin --optimal
postonus post --file draft.md --to linkedin --at 2026-08-01T09:30:00Z
postonus post --editor --to x --draft
postonus post "with a video" --to x --media ./demo.mp4 --optimal
cat draft.md | postonus post --to x --optimal
post always schedules; it never publishes on the spot. Pick a time with
--at <ISO timestamp> or --optimal for the next recommended window, or use
--draft to save without a time. --dry-run shows what would happen and stops.
Scripting
Every command takes --json, which prints machine-readable JSON on stdout and
skips all interactive rendering:
postonus queue list --json | jq -r '.queue[] | "\(.scheduledAt) \(.platform)"'
postonus post --file draft.md --to linkedin --at 2026-08-01T09:30:00Z --json
Data goes to stdout, progress and errors to stderr, so pipes stay clean. Exit
codes are 0 success, 1 failure, 2 usage error. With no TTY the CLI never
prompts — pass the flags instead, and use --no-input to make a missing one an
error rather than a wait.
CI
Set POSTONUS_API_KEY to an API key from the dashboard. It takes precedence over
a stored session, so no login step is needed:
- run: npx @postonus/cli post "$MESSAGE" --to x --optimal
env:
POSTONUS_API_KEY: ${{ secrets.POSTONUS_API_KEY }}
Environment
| Variable | Purpose |
|---|---|
POSTONUS_API_KEY | API key for non-interactive use; overrides login |
POSTONUS_API_URL | Dashboard to talk to; defaults to production |
EDITOR/VISUAL | Editor opened by post --editor |
NO_COLOR | Disable coloured output |
XDG_CONFIG_HOME | Where the session is stored; defaults to ~/.config |
postonus logout removes the stored credentials.