Pp Shipsgo

<!-- GENERATED FILE — DO NOT EDIT.
     This file is a verbatim mirror of library/commerce/shipsgo/SKILL.md,
     regenerated post-merge by tools/generate-skills/. Hand-edits here are
     silently overwritten on the next regen. Edit the library/ source instead.
     See the repository agent guide, section "Generated artifacts: registry.json, cli-skills/". -->

ShipsGo — Printing Press CLI

Prerequisites: Install the CLI

This skill drives the shipsgo-pp-cli binary. You must verify the CLI is installed before invoking any command from this skill. If it is missing, install it first:

1. Install via the Printing Press installer:

   npx -y @mvanhorn/printing-press-library install shipsgo --cli-only

2. Verify: shipsgo-pp-cli --version
3. Ensure $GOPATH/bin (or $HOME/go/bin) is on $PATH.

If the npx install fails (no Node, offline, etc.), fall back to a direct Go install (requires Go 1.26.6 or newer):

go install github.com/mvanhorn/printing-press-library/library/commerce/shipsgo/cmd/shipsgo-pp-cli@latest

If --version reports "command not found" after install, the install step did not put the binary on $PATH. Do not proceed with skill commands until verification succeeds.

shipsgo wraps the full ShipsGo v2 API (ocean + air, 16 endpoints, all CRUD verbs) and layers on top a freight-RFQ workflow that lives entirely in your local SQLite store. Use rfq compare to score carriers against your own shipment history, eta-drift to catch slipping voyages before customers do, and credit-budget to never burn a free-tier credit on a duplicate container.

When to Use This CLI

Use shipsgo whenever an agent is asked to evaluate, monitor, or report on freight shipments tracked through ShipsGo. It is the right tool for RFQ comparison (carrier scoring on real shipment history), ETA drift watches, port/lane analytics, and unified ocean+air shipment views. It is NOT the right tool for booking new shipments with carriers (use a TMS) or for parcel/last-mile shipping (use Shippo or ShipEngine).

Unique Capabilities

These capabilities aren't available in any other tool for this API.

RFQ workflow

• rfq new — Create, populate, and inspect an RFQ workspace that groups multiple tracked shipments under one quote slug.

  Reach for this when an agent needs to evaluate a freight quote against actual shipments — the RFQ slug becomes the join key for compare, digest, and follower fan-out.

  shipsgo-pp-cli rfq new Q3-LCL-Asia --lane SHA-LAX --carriers COSCO,ONE,MSC

• rfq compare — For one RFQ slug, group its shipments by carrier and emit mean actual transit days, ETA-vs-actual delta, and shipment count.

  This is the literal RFQ question: which carrier actually performs best on this lane. Use when an agent has to pick or recommend a carrier from a quote.

  shipsgo-pp-cli rfq compare Q3-LCL-Asia --format md --agent

• digest — Emit a structured table of shipment id, last milestone, current ETA, and ETA-delta since last digest, scoped to an RFQ or a time window.

  Use Friday afternoons to assemble the importer's weekly status update without screenshotting the dashboard.

  shipsgo-pp-cli digest --rfq Q3-LCL-Asia --since 7d --format md

• followers-broadcast — Add or remove one follower email across every shipment in an RFQ in one command, gated by credit-budget and --dry-run.

  Use when a new stakeholder joins an RFQ — saves dozens of dashboard clicks.

  shipsgo-pp-cli followers-broadcast Q3-LCL-Asia importer@example.com --dry-run

Analytics

• lane stats — Across all locally tracked shipments on an origin→destination lane, report p50/p90 transit days with per-carrier breakdown.

  Lane analytics are paywalled on commercial alternatives (Freightify, GoComet). Use when planning carrier mix on a specific port pair.

  shipsgo-pp-cli lane stats SHA LAX --since 90d --json

• eta-drift — List shipments whose ETA shifted by more than N days since the last sync — sorted by drift magnitude.

  Drift is the earliest signal of voyage trouble. Use as a watch query before customer-facing status digests.

  shipsgo-pp-cli eta-drift --threshold 2 --since 7d --json

• reliability — Median(actual_delivery − original_eta) and on-time percentage for a carrier, optionally scoped to a specific lane.

  This is the single number that should decide every RFQ. Use when ranking carriers in a quote response.

  shipsgo-pp-cli reliability COSCO --lane SHA-LAX --json

Reachability mitigation

• credit-budget — Read ShipsGo X-RateLimit-* headers from the last response, combine with local dedupe state, and refuse new POSTs when the reserve would be breached.

  Free tier is 3 credits and the rate limit is 100/min collective. Use before any batch POST loop.

  shipsgo-pp-cli credit-budget --reserve 5 --json

• dupe-check — Look up a container number or AWB in the local store and exit non-zero with the existing shipment id if already tracked.

  Use in any script that may POST a new shipment — saves a credit on every re-run.

  shipsgo-pp-cli dupe-check MSCU1234567 --json

Local state that compounds

• book — Single view across ocean + air shipments, filterable by ETA window, status, tag, port, or carrier — backed by FTS5 and local indices.

  Replaces the dashboard's daily 'what's arriving this week' query with a sub-second, agent-pipeable command.

  shipsgo-pp-cli book --eta-within 7d --status sailing --json

• webhook tail — Tail the locally stored webhook_events table chronologically; supports --since, --shipment, and --watch.

  Use to audit milestone history when a customer disputes an ETA change.

  shipsgo-pp-cli webhook tail --since 24h --shipment ship_abc123 --json

Command Reference

air — Manage air

• shipsgo-pp-cli air create — This endpoint allows you to create a new shipment by providing the necessary shipment details.
• shipsgo-pp-cli air create-shipments — This endpoint allows users to add a new follower to an existing air shipment.
• shipsgo-pp-cli air create-shipments-2 — This endpoint allows users to add a tag to an existing air shipment.
• shipsgo-pp-cli air delete — This endpoint allows users to delete an existing air shipment.
• shipsgo-pp-cli air delete-shipments — This endpoint allows users to remove an existing follower from an existing air shipment.
• shipsgo-pp-cli air delete-shipments-2 — This endpoint allows users to remove an existing tag from an existing air shipment.
• shipsgo-pp-cli air get — This endpoint retrieves the details of an existing air shipment.
• shipsgo-pp-cli air get-shipments — This endpoint provides a GeoJSON FeatureCollection with all map-related data for a shipment, including airport locations
• shipsgo-pp-cli air list — The shipments list endpoint allows you to retrieve a list of airlines.
• shipsgo-pp-cli air list-shipments — The shipments list endpoint allows you to retrieve a list of your shipments (basic information).
• shipsgo-pp-cli air update — This endpoint allows users to update the fields of an existing air shipment.

ocean — Manage ocean

• shipsgo-pp-cli ocean create — This endpoint allows you to create a new shipment by providing the necessary shipment details.
• shipsgo-pp-cli ocean create-shipments — This endpoint allows users to add a new follower to an existing ocean shipment.
• shipsgo-pp-cli ocean create-shipments-2 — This endpoint allows users to add a tag to an existing ocean shipment.
• shipsgo-pp-cli ocean delete — This endpoint allows users to delete an existing ocean shipment.
• shipsgo-pp-cli ocean delete-shipments — This endpoint allows users to remove an existing follower from an existing ocean shipment.
• shipsgo-pp-cli ocean delete-shipments-2 — This endpoint allows users to remove an existing tag from an existing ocean shipment.
• shipsgo-pp-cli ocean get — This endpoint retrieves the details of an existing ocean shipment.
• shipsgo-pp-cli ocean get-shipments — This endpoint provides a GeoJSON FeatureCollection with all map-related data for a shipment, including port locations
• shipsgo-pp-cli ocean list — The shipments list endpoint allows you to retrieve a list of carriers.
• shipsgo-pp-cli ocean list-shipments — The shipments list endpoint allows you to retrieve a list of your shipments (basic information)
• shipsgo-pp-cli ocean update — This endpoint allows users to update the fields of an existing ocean shipment.