WARP CLI v0.1.2

A command-line tool for managing freight shipments through the WARP API. Get quotes, book shipments, track deliveries, view invoices and documents — all from your terminal.

Tip

If you prefer a REST API, check out the Freight API Documentation.

Installation

📦

npm

Requires Node.js 18 or later.

$ npm install -g @wearewarp.com/cli

🍺

Homebrew

Standalone binary — no Node.js required.

$ brew tap wearewarp/warp && brew install warp-cli

Verify the installation:

$ warp --version
@wearewarp.com/cli/0.1.2

Supported Platforms (Homebrew)

Platform	Architecture
macOS	Apple Silicon (ARM64)
macOS	Intel (x64)
Linux	x64

Quick Start

Get up and running in under a minute:

1. Authenticate with your API key

$ warp login --api-key YOUR_API_KEY

2. Get a shipping quote

$ warp quote \
    --pickup-date 2026-04-01 \
    --pickup-zip 90210 \
    --delivery-zip 10001 \
    --item-height 48 --item-length 48 --item-width 40 \
    --item-size-unit IN \
    --item-weight 500 --item-weight-unit lbs \
    --item-qty 1

3. Book the shipment

$ warp book --quote-id <QUOTE_ID> --from-file booking.json

4. Track your shipment

$ warp track <TRACKING_NUMBER>

5. View all shipments

$ warp shipments

Authentication

The CLI supports two authentication methods. An API key can be requested from the WARP Engineering team.

Method 1: API Key

Provide your API key directly. The CLI validates it before storing.

$ warp login --api-key YOUR_API_KEY
# ✓ Authenticated successfully

Method 2: Browser Login

Opens the WARP Customer Portal in your browser for a device-based login flow.

$ warp login --browser
# Opens browser → log in → CLI receives API key automatically

Interactive Login

Run warp login without flags to choose the method interactively.

Note

Your API key is stored securely at ~/.config/warp-cli/config.json with restricted permissions (0600). Commands that require authentication will fail with a clear error if you are not logged in.

Public Commands (no auth required)

login, logout, whoami, help, config get, config set, config reset

Commands Reference

All commands are invoked as warp <command> [options].

warp login — Authenticate with the WARP API

Authenticate using an API key or browser-based login. Supports three modes: interactive (default), API key flag, or browser flag.

Flag	Type		Description
`--api-key`	string	optional	API key to authenticate with
`--browser`	boolean	optional	Login via browser (opens customer portal)

Direct API key:

$ warp login --api-key sk_live_abc123

Browser-based auth:

$ warp login --browser

Interactive (choose method):

$ warp login

warp logout — Remove stored credentials

Clears the stored API key from the config file. No flags required.

$ warp logout
# ✓ Logged out successfully

warp whoami — Show current auth status

Displays the current authentication status, masked API key, and configured endpoint.

$ warp whoami
Endpoint: https://gw.wearewarp.com/api/v1
API Key:  sk_li****c123
Status:   Authenticated

warp quote — Get a freight shipping quote

Request a shipping quote. Supports interactive prompts, full flags, or JSON file input.

Flags

Flag	Type		Description
`--pickup-date`	string	required	Pickup date (YYYY-MM-DD)
`--pickup-zip`	string	required	Pickup zipcode
`--pickup-country`	string	optional	Pickup country code (default: US)
`--delivery-zip`	string	required	Delivery zipcode
`--delivery-country`	string	optional	Delivery country code (default: US)
`--item-height`	number	required	Item height
`--item-length`	number	required	Item length
`--item-width`	number	required	Item width
`--item-size-unit`	IN \| FT	required	Size unit (inches or feet)
`--item-weight`	number	required	Item total weight
`--item-weight-unit`	lbs \| kgs	required	Weight unit
`--item-qty`	number	required	Item quantity
`--item-name`	string	optional	Item name
`--shipment-type`	FTL \| LTL	optional	Shipment type (auto-detected if omitted)
`--vehicle-type`	string	optional	Vehicle type code (auto-detected if omitted)
`--from-file`	path	optional	Path to JSON request file
`-o, --output`	string	optional	Output format: table, json, csv

Vehicle Type Codes

CARGO_VAN SMALL_STRAIGHT LARGE_STRAIGHT FLATBED DRY_VAN_48 DRY_VAN_53 REEFER BOX_TRUCK

Example

$ warp quote \
    --pickup-date 2026-04-01 \
    --pickup-zip 90210 \
    --delivery-zip 10001 \
    --item-height 48 --item-length 48 --item-width 40 \
    --item-size-unit IN \
    --item-weight 500 --item-weight-unit lbs \
    --item-qty 1 \
    --shipment-type LTL \
    -o json

Response

{
  "quote_id": "59120da4-c844-4502-a468-cca8e4018bd5",
  "price": {
    "amount": 1000,
    "currency_code": "USD"
  },
  "charges": [
    {
      "code": "TOTAL",
      "description": "Total rate",
      "amount": 1000
    }
  ],
  "expiration_time_utc": 1529107809,
  "status": "ACCEPT",
  "shipmentType": "LTL"
}

warp book — Book a shipment from a quote

Book a shipment using a previous quote ID. Supports interactive prompts, full flags, or JSON file input. When a --quote-id is provided, the CLI fetches quote details to pre-fill item information.

Flags

Flag	Type		Description
`--quote-id`	string	required	Quote ID from a previous quote
`--from-file`	path	optional	JSON file with booking details
`--pickup-contact`	string	required	Pickup contact name
`--pickup-phone`	string	required	Pickup contact phone
`--pickup-email`	string	optional	Pickup contact email
`--pickup-street`	string	required	Pickup street address
`--pickup-city`	string	required	Pickup city
`--pickup-state`	string	required	Pickup state
`--pickup-zip`	string	required	Pickup zipcode
`--pickup-window-from`	string	required	Pickup window start (ISO datetime)
`--pickup-window-to`	string	required	Pickup window end (ISO datetime)
`--pickup-instructions`	string	optional	Pickup special instructions
`--delivery-contact`	string	required	Delivery contact name
`--delivery-phone`	string	required	Delivery contact phone
`--delivery-email`	string	optional	Delivery contact email
`--delivery-street`	string	required	Delivery street address
`--delivery-city`	string	required	Delivery city
`--delivery-state`	string	required	Delivery state
`--delivery-zip`	string	required	Delivery zipcode
`--delivery-window-from`	string	required	Delivery window start (ISO datetime)
`--delivery-window-to`	string	required	Delivery window end (ISO datetime)
`--delivery-instructions`	string	optional	Delivery special instructions
`--ref-num`	string	optional	Your reference number
`-o, --output`	string	optional	Output format: table, json, csv

Tip

For bookings with many fields, use --from-file with a JSON file. See JSON File Input.

Example

$ warp book --quote-id 59120da4-c844-... --from-file booking.json

Response

{
  "message": "Shipment booked successfully",
  "trackingNumber": "WARP-1234567",
  "orderNumber": "ORD-001234",
  "orderId": "6612abc...",
  "shipmentId": "6612def...",
  "shipmentNumber": "SHP-001234"
}

warp track <trackingNumbers> — Track shipments

Track one or more shipments by their tracking numbers (comma-separated).

Argument	Type		Description
`trackingNumbers`	string	required	Comma-separated tracking numbers
`-o, --output`	string	optional	Output format: table, json, csv

Single shipment:

$ warp track WARP-1234567

Multiple shipments:

$ warp track WARP-1234567,WARP-7654321

warp shipments — List all shipments

Retrieve a list of all your freight shipments.

Flag	Type		Description
`-o, --output`	string	optional	Output format: table, json, csv

$ warp shipments

$ warp shipments -o json

warp events <shipmentId> — View shipment events

View the tracking event history for a specific shipment.

Argument	Type		Description
`shipmentId`	string	required	The shipment ID
`-o, --output`	string	optional	Output format: table, json, csv

$ warp events 6612abc123def456

warp invoice <orderId> — View order invoice

Display invoice details for a specific order.

Argument	Type		Description
`orderId`	string	required	The order ID
`-o, --output`	string	optional	Output format: table, json, csv

$ warp invoice 6612abc123def456

warp documents <orderId> — List order documents

Retrieve documents (BOL, POD, etc.) associated with an order.

Argument	Type		Description
`orderId`	string	required	The order ID
`-o, --output`	string	optional	Output format: table, json, csv

$ warp documents 6612abc123def456

warp quote-history — View past quotes

Retrieve your quote history.

Flag	Type		Description
`-o, --output`	string	optional	Output format: table, json, csv

$ warp quote-history

$ warp quote-history -o csv

warp config — Manage CLI configuration

View and manage CLI settings.

config get

Display the current configuration (endpoint, output format, auth status, config file path).

$ warp config get

config set <key> <value>

Set a configuration value.

Key	Valid Values	Description
`endpoint`	Any URL or `default`	API base URL
`output`	`table`, `json`, `csv`	Default output format

$ warp config set endpoint https://stg.wearewarp.com/api/v1

$ warp config set output json

config reset

Reset endpoint and output format to defaults. Your API key is preserved.

$ warp config reset

Output Formats

All freight commands support the -o / --output flag with three formats:

Format	Description
`table`	Human-readable colored table (default)
`json`	Raw JSON — ideal for scripting and piping
`csv`	Comma-separated values for spreadsheets

$ warp shipments -o json

$ warp shipments -o csv > shipments.csv

$ warp quote-history -o json | jq '.[] | .quote_id'

JSON File Input

For complex requests (especially bookings), use --from-file to provide a JSON request body instead of individual flags.

Quote Request Example

Create a file quote-request.json:

{
  "pickupDate": "2026-04-01",
  "pickupInfo": { "zipcode": "90210" },
  "deliveryInfo": { "zipcode": "10001" },
  "listItems": [
    {
      "name": "Palletized Goods",
      "height": 48,
      "length": 48,
      "width": 40,
      "sizeUnit": "IN",
      "totalWeight": 500,
      "weightUnit": "lbs",
      "quantity": 2,
      "stackable": false
    }
  ],
  "shipmentType": "LTL"
}

$ warp quote --from-file quote-request.json

Booking Request Example

Create a file booking.json:

{
  "pickupInfo": {
    "contactName": "John Smith",
    "contactPhone": "555-0100",
    "contactEmail": "john@example.com",
    "address": {
      "street": "123 Warehouse Ave",
      "city": "Los Angeles",
      "state": "CA",
      "zipcode": "90210"
    },
    "windowTime": {
      "from": "2026-04-01T08:00:00Z",
      "to": "2026-04-01T17:00:00Z"
    },
    "instructions": "Dock 3, call on arrival"
  },
  "deliveryInfo": {
    "contactName": "Jane Doe",
    "contactPhone": "555-0200",
    "address": {
      "street": "456 Distribution Blvd",
      "city": "New York",
      "state": "NY",
      "zipcode": "10001"
    },
    "windowTime": {
      "from": "2026-04-05T08:00:00Z",
      "to": "2026-04-05T17:00:00Z"
    }
  },
  "refNum": "PO-2026-001"
}

$ warp book --quote-id 59120da4-c844-... --from-file booking.json

Configuration

Configuration is stored at ~/.config/warp-cli/config.json with restricted file permissions (0600).

Config Schema

{
  "apiKey": "sk_live_...",
  "endpoint": "https://gw.wearewarp.com/api/v1",
  "outputFormat": "table"
}

Key	Default	Description
`apiKey`	—	Your WARP API key (set via `warp login`)
`endpoint`	`https://gw.wearewarp.com/api/v1`	API base URL
`outputFormat`	`table`	Default output format for all commands

Environments

Production

https://gw.wearewarp.com/api/v1

Staging

https://stg.wearewarp.com/api/v1

Switch environments using config set:

Switch to staging:

$ warp config set endpoint https://stg.wearewarp.com/api/v1

Switch back to production:

$ warp config set endpoint default

Warning

Staging and production use separate API keys. After switching environments, you may need to re-authenticate with warp login.

Error Handling

The CLI provides clear error messages for common failures:

HTTP Status	Code	Description
400	`required_field_missing`	Required fields are missing from the request
400	`invalid_field_data`	Invalid field data provided
403	`request_unauthorized`	Authenticated but lacks authorization for this resource
429	`rate_limit_exceeded`	Too many requests — retry after cooldown
500	`internal_server_error`	Server-side error

Automatic Retry

The CLI automatically retries requests on 429 (rate limit) and 5xx (server errors) with exponential backoff, up to 3 retries. The Retry-After header is respected when present.

Request Timeout

All requests have a 30-second timeout. If the server does not respond within this window, the request is aborted.

Need Help?

Contact api-support@wearewarp.com for API key requests and technical support.

Full REST API documentation is available at /docs/freight.