Shipmondo CLI

The Shipmondo CLI is a command line interface to the Shipmondo API. It is built to be operated by AI coding agents like Claude Code, Cursor, GitHub Copilot and Gemini, but it works just as well in your own shell scripts and CI jobs.

• Single binary: The CLI is a statically-linked binary for macOS, Linux and Windows with no runtime dependencies.
• Generated from the API spec: Every command is derived from our OpenAPI specification at runtime, so the CLI covers every endpoint in the API.
• Self-describing: The CLI can print a machine-readable catalog of all commands and the exact schema of each one, so an agent never has to guess parameters.
• JSON in, JSON out: All output is raw JSON, ready to be piped into other tools or read by an agent.

The source code is available on GitHub.

Installation

The install scripts download the correct binary for your platform from GitHub Releases and place it on your PATH.

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/shipmondo/shipmondo-cli/main/install.sh | bash

Windows (PowerShell)

irm https://raw.githubusercontent.com/shipmondo/shipmondo-cli/main/install.ps1 | iex

You can also download a binary directly from the Releases page and put it anywhere on your PATH. Restart your terminal if the shipmondo command is not recognized right away.

Configuration

The CLI authenticates with an API user and API key, the same as any other API integration. See Getting Started for how to generate a set of credentials.

Set the credentials as environment variables, for example in your .zshrc or .bashrc:

export SHIPMONDO_API_USER="your_api_user"
export SHIPMONDO_API_KEY="your_api_key"

Variable	Description
SHIPMONDO_API_USER	Your API user. Required.
SHIPMONDO_API_KEY	Your API key. Required.
SHIPMONDO_BASE_URL	The API base URL. Defaults to https://app.shipmondo.com/api/public/v3.
SHIPMONDO_SPEC_URL	Where to download the OpenAPI specification from. Defaults to https://app.shipmondo.com/api/public/v3/openapi.json.

Using the Sandbox

To point the CLI at the Sandbox instead of production, set the base URL and use the API credentials from your sandbox account:

export SHIPMONDO_BASE_URL="https://sandbox.shipmondo.com/api/public/v3"

Command structure

All commands follow the same pattern:

shipmondo <resource> <action> [arguments] [options]

The resource is the first part of the API path, for example shipments, sales_orders or shipment_drafts. The action is derived from the HTTP method and the rest of the path:

Endpoint	Command
GET /shipments	shipmondo shipments list
POST /shipments	shipmondo shipments create
GET /shipments/{id}	shipmondo shipments get <id>
GET /shipments/{id}/labels	shipmondo shipments labels <id>
PUT /sales_orders/{id}	shipmondo sales_orders update <id>
DELETE /webhooks/{id}	shipmondo webhooks delete <id>

Arguments and options map to the request like this:

• Path parameters are passed as positional arguments, in the order they appear in the path.
• Query parameters are passed as kebab-case flags, for example receiver_country_code becomes --receiver-country-code.
• Request bodies for POST, PUT and PATCH requests are passed as a JSON string with --data.
• Raw query parameters can be passed as a JSON object with --query. Values in --query take precedence over individual flags.

Discovering commands

You don't need to look up commands in the documentation. List every resource and action, along with its HTTP method and endpoint:

shipmondo commands

Print the machine-readable schema for a single action, including its positional arguments, flags and the JSON schema for --data:

shipmondo shipments create --help-json

Examples

Fetch account information

shipmondo account get

List carriers for a route

shipmondo carriers list --sender-country-code DK --receiver-country-code SE

List products for a carrier

shipmondo products list --carrier-code gls --sender-country-code DK --receiver-country-code DK

List shipments with pagination

shipmondo shipments list --receiver-country SE --per-page 50 --page 2

Create a webhook

shipmondo webhooks create --data '{"name":"Shipments","endpoint":"https://example.com/webhooks","key":"secret","action":"create","resource_name":"Shipments"}'

See Webhooks for the available resources and actions.

Open a shipping label

shipmondo shipments labels 12345 --open-pdf

Options

The following options work on every action:

Option	Description
--data <json>	JSON request body for POST, PUT and PATCH requests.
--query <json>	JSON object of query parameters.
--help-json	Print the machine-readable schema for the action instead of calling the API.
--debug	Print the raw HTTP request and response to stderr.
--open-pdf	Find base64-encoded PDFs in the response (e.g. labels and customs documents), save them to a temporary file and open them in your default PDF viewer.
--text	Print a short success message instead of the JSON response.

Output and errors

On success, the CLI prints the API response as JSON to stdout and exits with code 0.

On failure, the CLI prints a JSON error to stderr and exits with code 1. Errors from the API include the HTTP status code and the error message returned by the API:

{"error": "API Request Failed", "status_code": 422, "details": "..."}

Because errors go to stderr, piped output stays clean, and both scripts and agents can rely on the exit code.

The CLI uses the same API as any other integration, so the same rate limits apply.

Using the CLI with AI agents

The CLI ships with an Agent Skill: a SKILL.md file that teaches an agent how to use the CLI, how to discover commands, and the domain rules for the Shipmondo API, such as using parties when creating shipments.

Export the skill to a shipmondo folder in the current directory:

shipmondo setup export

Then place the folder where your agent looks for skills:

Tool	Location
Claude Code	.claude/skills/shipmondo/ (project) or ~/.claude/skills/shipmondo/ (all projects)
GitHub Copilot (VS Code)	.github/skills/shipmondo/
Cursor	.cursor/skills/shipmondo/
Windsurf	.windsurf/skills/shipmondo/

These locations are defined by each tool and can change. Check your tool's documentation if a path doesn't work.

tip

Symlink the folder instead of copying it, for example ln -s "$(pwd)/shipmondo" .claude/skills/shipmondo. Then you only need to run shipmondo setup export again after an update to refresh the skill everywhere.

Keeping the CLI up to date

The CLI downloads the OpenAPI specification the first time it runs and caches it locally. New endpoints in the API therefore don't require a new version of the CLI. Clear the cache and fetch the latest specification with:

shipmondo reload

If the specification can't be downloaded and no cache exists, the CLI falls back to a copy bundled into the binary, so it also works offline.

To update the CLI itself to the latest release:

shipmondo update

Command	Description
shipmondo commands	Print the catalog of all resources and actions.
shipmondo openapi	Print the OpenAPI specification the CLI is using.
shipmondo setup export	Export the Agent Skill to ./shipmondo/SKILL.md.
shipmondo reload	Clear the cached specification and fetch a fresh copy.
shipmondo update	Update the CLI to the latest release.
shipmondo version	Print the CLI version.