Redesigning the Postonus CLI: Terminal Ergonomics for Humans and Agents

How we redesigned the Postonus CLI with strict stream separation, independent consent, directory linking, and structured error recovery inspired by Vercel design principles.

6 min read

Scheduling social posts from a terminal or giving an AI coding agent access to your content calendar should feel predictable and safe. When you pipe a command into jq or awk, you want raw data without status spinners corrupting the stream. When an autonomous agent deletes a post, you need strict proof of intent so it cannot wipe live campaigns by accident.

We recently overhauled @postonus/cli from the ground up, adopting the principles laid out in Vercel's CLI Design Guidelines. Here is what changed, why we structured it this way, and how it improves publishing workflows for solo builders, agency teams, and coding assistants alike.

The Postonus CLI and the local MCP server (postonus mcp) are available on every plan with no enterprise paywall. Install the binary globally with npm install -g @postonus/cli.


The Four Core Questions

Every command in the updated CLI must answer four questions cleanly—both for the person sitting at the terminal and for a script or AI agent parsing the transcript:

  1. What will it act on? When a command infers a workspace or target channel from configuration, it names the resolved target on stderr before performing consequential work.
  2. What will change? Destructive operations and batch schedules preview affected items before execution. Commands also support --dry-run to rehearse writes against server validation rules.
  3. What happened? Clear, past-tense receipts (✓ Scheduled, ✓ Deleted, ✓ Draft saved) with standard visual gutter glyphs.
  4. What next? Every successful creation, draft, or empty state displays one exact, working command for the next logical step.
$ postonus post "Announcing our new CLI release" --to x,linkedin --optimal
✓ Scheduled       post_01j7abc
  linkedin        Acme Corp           scheduled   Tomorrow at 09:30 AM  sch_01
  x               @acme               scheduled   Tomorrow at 09:30 AM  sch_02

Post URL: https://app.postonus.com/posts/post_01j7abc

Next: inspect your queue:
  postonus queue list

One common pitfall in command-line tooling is conflating machine output (--json) with permission to act, or assuming that running inside CI means automatic approval.

We adopted Vercel's rule: Interaction, consent, and format are orthogonal axes.

  • Interaction (TTY): Prompts only run when standard input and standard output are attached to an interactive terminal. When running in CI, in background subshells, or under detected AI agents (CLAUDE_CODE, CURSOR_AGENT), the CLI automatically enters --non-interactive mode so processes never hang waiting for inputs they cannot see.
  • Consent (-y, --yes): Destructive actions like postonus post delete <postId> require explicit confirmation. In interactive mode, the CLI asks ? Delete post post_123 and its platform copies? (y/N). In non-interactive mode or automated scripts, -y or --yes is mandatory.
  • Format (--json): Passing --json selects structured JSON output on stdout and suppresses terminal animations, but it grants zero consent. A script calling postonus post delete post_123 --json without --yes is safely refused with exit code 2.
# Non-interactive script missing confirmation:
$ postonus post delete post_01j7abc --non-interactive
✗ Cannot delete post post_01j7abc in non-interactive mode without confirmation.
  - Pass -y or --yes to confirm deletion in non-interactive mode.

  Next steps:
  Confirm deletion of post and schedules:
    postonus post delete post_01j7abc --yes

Stream Discipline: stdout is the Answer

To make the CLI genuinely composable with standard Unix utilities (cut, grep, awk, xargs), we enforced strict separation between standard output and standard error:

  • stdout carries the answer:
    • When querying (queue list, channels list), stdout contains the tabular data. When piped to another process (!stdout.isTTY), tables switch to tab-separated values without truncation, padding, or ANSI color codes.
    • In mutation commands (post, queue move), running in a pipe prints the created resource ID directly to stdout, enabling clean shell composition:
      POST_ID=$(postonus post "Draft announcement" --draft)
      postonus queue schedule "$POST_ID" --optimal
      
  • stderr carries everything else: Progress spinners, workspace headers, human receipts, warnings, and next-step recovery advice live exclusively on stderr. Your shell scripts will never find a spinner frame inside a piped JSON payload.

If you manage social accounts across multiple brands or client workspaces, typing -w, --workspace <id> on every command is tedious, and relying on a single global default config risks posting to the wrong client by mistake.

With the new postonus link command, you can link a local directory or repository (such as a marketing docs folder or software repo) directly to a Postonus workspace:

$ cd ~/code/acme-marketing
$ postonus link
? Which workspace would you like to link to this directory?
❯ Acme Corp (owner)
  Personal (member)

✓ Linked directory to Acme Corp (ws_01j7abc)
  Configuration saved to .postonus/config.json

All commands executed inside that folder (or its subdirectories) automatically route to that workspace. When you want to disconnect, run postonus unlink.

The CLI resolves settings in strict priority order:

  1. Command option (-w, --workspace <id>)
  2. Environment variable (POSTONUS_WORKSPACE)
  3. Linked folder configuration (.postonus/config.json)
  4. Global configuration (~/.config/postonus/config.json)
  5. Default user workspace

Structured Errors as Recovery

Errors are designed as actionable recovery paths rather than dead ends. Both human and JSON errors classify the failure and provide the exact command to resolve it.

When character limits are exceeded or authentication expires, the output does not simply say what went wrong—it tells you how to fix it:

✗ Cannot schedule post. Character limit exceeded for X.
  - X: 305 of 280

  Next steps:
  Split long text into a thread:
    postonus post --thread-file <path>

Under --json, errors follow a typed contract with an actionable next array:

{
  "code": "CONTENT_TOO_LONG",
  "status": "error",
  "reason": "content_too_long",
  "message": "Too long for 2 channels.",
  "next": [
    {
      "command": "postonus post --thread-file <path>",
      "when": "Split long text into a thread"
    }
  ],
  "data": {
    "violations": [{ "message": "X: 305 of 280" }]
  }
}

Built on One Shared API Contract

Unlike tools that bolt on a separate CLI or wrap private browser endpoints, @postonus/cli talks to the exact same contract-first /api/v1 routes as the web dashboard and the native MCP server.

  • Simulation with --dry-run: Rehearse complex multi-platform posts, thread segments, or channel overrides against server validations without saving a draft or spending credits.
  • 16 Supported Platforms: Target accounts across Bluesky, Threads, LinkedIn, X, Discord, Reddit, and Pinterest with platform-native character checks and optimal time recommendations.
  • Coding Agent Integration: The CLI shares authentication credentials with postonus mcp, letting editors like Claude Desktop and Cursor connect over stdio without running separate OAuth handshakes.

Get Started

Upgrade or install the latest CLI release:

npm install -g @postonus/cli
postonus login

Link your content repository with postonus link, schedule your first post with postonus post, or inspect your upcoming publishing calendar with postonus queue list.

Try Postonus free for 14 days with full access across all 16 platforms—no credit card required.