@atoship/cli

Your AI-era shipping manager for the terminal. The @atoship/cli puts the full power of atoship on your command line — compare rates across USPS, FedEx, and UPS, buy discounted shipping labels, track packages, and manage shipments without opening a browser.

Before: Open carrier website → enter addresses → compare rates → download label → copy tracking number.

After:

ship rate --from 90001 --to 10001 --weight 2oz --cheapest
ship buy --rate rate_abc123 --from "John|123 Main St|LA|CA|90001" --to "Jane|456 Oak Ave|NY|NY|10001"

Installation

npm install -g @atoship/cli

Or run without installing:

npx @atoship/cli rate --from "LA, CA 90001" --to "NY, NY 10001" --weight 2oz

Setup

Step 1: Sign up free at atoship.com — no credit card required.

Step 2: Get your API key from Dashboard → Settings → API Keys.

Step 3: Save it:

ship config set-key ak_live_your_key_here

Or use an environment variable:

export ATOSHIP_API_KEY=ak_live_your_key_here

Test keys are free: Use ak_test_... keys for development — test labels are never shipped and cost nothing.

Commands

ship rate — Compare shipping rates

# By city/state
ship rate --from "Los Angeles, CA 90001" --to "New York, NY 10001" --weight 2oz

# By ZIP code
ship rate --from-zip 90001 --to-zip 10001 --weight 1lb

# Filter by carrier
ship rate --from "LA, CA" --to "NY, NY" --weight 16oz --carrier USPS,FEDEX

# Show cheapest per carrier only
ship rate --from-zip 90001 --to-zip 10001 --weight 2oz --cheapest

# With package dimensions
ship rate --from "LA, CA" --to "NY, NY" --weight 2oz --length 12 --width 8 --height 6

ship buy — Purchase a shipping label

# From a rate ID (run "ship rate" first to get the rate ID)
ship buy --rate rate_abc123 \
         --from "John Doe|123 Main St|Los Angeles|CA|90001" \
         --to   "Jane Smith|456 Oak Ave|New York|NY|10001" \
         --weight 2oz

# Specify carrier and service directly
ship buy --from "John Doe|123 Main St|Los Angeles|CA|90001" \
         --to   "Jane Smith|456 Oak Ave|New York|NY|10001" \
         --weight 1lb --carrier USPS --service "Priority Mail"

# With signature confirmation and insurance
ship buy --from "..." --to "..." --weight 2oz \
         --signature --insurance 100 --reference "ORDER-123"

Address format: "Name|Street|City|State|ZIP"

ship track — Track a package

ship track 9400111899223456789012
ship track 9400111899223456789012 --carrier USPS
ship track 1Z999AA10123456784 --watch   # Poll every 5min until delivered

ship labels — List labels

ship labels
ship labels --status shipped
ship labels --carrier FEDEX --status delivered
ship labels --limit 50 --page 2

ship balance — Account info

ship balance

ship config — Manage configuration

ship config set-key ak_live_...    # Save API key
ship config set-url https://...    # Custom API URL
ship config show                   # View current config
ship config clear                  # Remove saved config

Output Format

All commands support --json for machine-readable output — perfect for scripts and CI/CD pipelines:

ship rate --from-zip 90001 --to-zip 10001 --weight 2oz --json | jq '.[0]'
ship labels --json | jq '.data[].tracking_number'
ship balance --json | jq '.balance.available'

Why atoship CLI?

• Scriptable — Automate label purchase in CI/CD, cron jobs, or fulfillment scripts
• Fast — No browser, no clicking — one command from order to label
• Cheapest rate — --cheapest flag shows the best price per carrier instantly
• Watch mode — ship track --watch polls until delivered, great for monitoring
• JSON output — Pipe into jq, scripts, or webhooks with --json
• Discounted rates — USPS, FedEx, and UPS at atoship negotiated pricing

Common Use Cases

CI/CD label generation — Automatically buy labels when orders are fulfilled:

TRACKING=$(ship buy --carrier USPS --service "Priority Mail" \
  --from "..." --to "..." --weight 2oz --json | jq -r '.tracking_number')

Batch rate comparison — Check rates for multiple destinations in a loop.

Shipment monitoring — Use --watch to get notified when a package is delivered.

Order management — Use ship labels --json to sync label status back to your system.

Environment Variables

| Variable | Description | |----------|-------------| | ATOSHIP_API_KEY | Your atoship API key (overrides saved config) | | ATOSHIP_BASE_URL | Custom API base URL (default: https://atoship.com) |

Requirements

• Node.js >= 18

Support & Contact

• Email: [email protected]
• Docs: atoship.com/docs
• API Reference: atoship.com/docs/api
• Dashboard: atoship.com/dashboard

For API key issues, billing questions, or carrier integration support, email [email protected] — we respond within one business day.

License

MIT