Skip to content

How the Postsale CLI Works

What the CLI is for, how direct commands and natural language relate, and how a safe first session unfolds.

Updated September 3, 20262 min readPostsale CLI

Available by invitation

The Postsale CLI is in an invitation-only release. Your invitation includes a signed program for your platform and its checksum, and new versions reach you the same way until the public release channel opens. To request access, email support@postsale.com.

Postsale is built for the work that happens after checkout: orders, rates, labels, and the operations around them. The Postsale CLI (postsale) gives you that same platform from the terminal, with structured results that scripts and AI agents can trust.

This article explains how the CLI is put together, when to use direct commands versus natural language, and how safety and output fit together. We will stay practical.

In this article, we will explain what the CLI is designed for, compare direct commands with postsale run, walk through a safe first session, and point you to deeper articles for auth, safety, shipping, and agents.

What Is the Postsale CLI?

The CLI is an agent-first command-line client for Postsale. In practice that means:

  • JSON on stdout for results you can pipe and parse
  • Structured errors on stderr with stable codes and exit codes
  • Direct commands when you already know the operation (orders, shipments, labels, and more)
  • Natural language via postsale run when the work takes several steps

Same account, different jobs

SurfaceBest for
Web appDay-to-day visual shipping, configuration, investigation with eyes
CLIRepeatable ops, unattended runs, pipes, multi-step plain-language intents, agent hosts with machine contracts

Same Postsale account and carriers. The CLI is not a full replacement for Dock-heavy UX. Product help for the web app: postsale.com/help. Other surfaces (browser Anywhere, MCP) are documented separately when you need them.

Tip

This library is specifically for the CLI.

Two Ways to Work

ApproachYou provideBest when
Direct commandsExact group, subcommand, and flags or JSONScripts, unattended runs, known IDs, pipes
postsale runA plain-language intentMulti-step work, discovery, "cheapest carrier for this order"

Both paths use the same Postsale account, carriers, and safety rules. Natural language does not bypass confirmation for label purchases or deletes.

Before We Begin

This article assumes that:

  • You can run postsale --version (the CLI reports its own semver; postsale doctor adds the build commit under checks.build)
  • You can sign in or set a token
  • (Optional) You have set ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN) or OPENAI_API_KEY if you want to try postsale run

We recommend rehearsing with Test Without Spending while you learn.

How the Pieces Fit Together

text
You, CI, or an AI host
        │
        ├─► Direct commands (orders, shipments, labels, ...)
        │
        └─► postsale run (LLM chooses tools and sequences them)
                    │
                    ▼
           Safety gates + HTTP client
                    │
                    ▼
              Postsale APIs
  1. You sign in once per machine, or give unattended runs and agents an API key.
  2. Direct commands map straight to operations.
  3. postsale run asks a model to pick from the CLI agent tool set (see agent tools reference for the live list), runs them with the same gates, and returns one JSON envelope (or a stream of events).
  4. Money-moving and destructive actions require explicit authorization. parallel batches have an extra batch approval. See Safety.

Try a Safe First Session

Here's how:

  1. Confirm the install:
bash
postsale --version
  1. Check auth and environment:
bash
postsale auth status
postsale account env
  1. Run preflight:
bash
postsale doctor --human
  1. Read a little data (no labels purchased):
bash
postsale account whoami
postsale orders search --query "orders from last 7 days" --page-size 5
  1. (Optional) Ask the agent a read-only question:
bash
postsale run "how many carriers and origin addresses do I have?"

Success looks like this: doctor is healthy enough for your environment, search returns JSON on stdout, and postsale run prints one JSON line on stdout while progress stayed on stderr.

Note

If postsale run fails before it starts (missing LLM key, bad resume id), stdout can be empty. Always check the exit code and stderr in that case.

Good to Know

Install and keeping current

The released CLI is a single signed, self-contained program: nothing else to install and no runtime needed. Install newer signed releases as they ship; pin the exact build you're on with postsale doctor → checks.build.commit.

Output contract in one sentence

stdout is data. stderr is everything human-facing (progress, prompts, error envelopes). Details: Output and Exit Codes.

Domain objects

Orders, shipments, and labels are related but not the same record. Order search does not embed full shipment payloads. Shipment reference holds the parent order id. Details: Orders, shipments, and labels.

Versioning

Document and report the CLI version from postsale --version.

Additional Reading

Related

Keep reading