Command line

Your whole warehouse, from the terminal

One binary, nothing to install alongside it. All 77 commands cover the entire Stockpilot API, and every one of them speaks --json, so it pipes straight into jq or into an agent.

Install Command reference Source ↗

77 commands ·19 groups ·full API coverage ·pre 1.0

zsh

$ stockpilot status

Open orders:     12
Inventory items: 438

$ stockpilot inventory list --json \
    | jq '.[] | select(.quantity < 5)'

{
  "sku": "MUG-WHT-330",
  "quantity": 3,
  "location": "B2-014-03"
}

Install

One line on macOS and Linux

The script detects your OS and architecture, pulls the matching binary from the latest release, and installs it to /usr/local/bin.

$ curl -fsSL https://stockpilot.dev/install | sh

Prefer to read the script first? It is served here, and its source lives in the repository. With Go 1.22 or newer you can build it yourself instead:

$ go install github.com/StockpilotHQ/stockpilot-cli/cmd/stockpilot@latest

Direct downloads

Platform	Architecture	File
macOS	Apple silicon	stockpilot_darwin_arm64
macOS	Intel	stockpilot_darwin_amd64
Linux	x86-64	stockpilot_linux_amd64
Linux	arm64	stockpilot_linux_arm64
Windows	x86-64	stockpilot_windows_amd64.exe

On Windows, download stockpilot_windows_amd64.exe and put it on your PATH. Every build is listed on the releases page.

Authenticate

Log in once

Generate a Client ID and Client Secret in the Stockpilot app under Settings → API. login verifies the pair against /auth/who-is before writing it, so a typo fails at the prompt rather than on your first real command.

Stored in ~/.config/stockpilot/config.json, file mode 0600, directory 0700.
Talks to https://api.stockpilot.dev, the same API as the reference.
One credential pair, no scopes. See Authentication for what that means for multi-tenant tools.

first run

$ stockpilot login
Client ID:     sp_live_a1b2c3d4e5f6
Client secret: ••••••••••••••••
Verifying… ok
Saved to ~/.config/stockpilot/config.json

$ stockpilot whoami
Acme Commerce BV (org 4812)

Access

Read-only, when you want it

A profile can be saved read-only, which refuses every request that is not a GET. Enforcement lives in the API client rather than in each command, so no command can forget it, and a refusal happens before any network call is made.

STOCKPILOT_READ_ONLY=1 tightens a single invocation without touching the saved profile. It can only tighten: a read-only profile cannot be widened by the environment.

This is a guardrail against mistakes, not a security boundary. The config file belongs to whoever runs the CLI and can be edited. For a hard limit on an agent, issue API credentials that lack write permission.

access

# save the profile as read-only from the start
$ stockpilot login --read-only

$ stockpilot access
Access:    read-only
Effective: read-only

$ stockpilot orders cancel 512
refused: profile is read-only

# or tighten one command in a full profile
$ STOCKPILOT_READ_ONLY=1 stockpilot orders cancel 512
refused: read-only forced by environment

$ stockpilot access set full
Access set to full.

Output

Tables for you, JSON for everything else

Commands print an aligned table by default. Add --json and you get the raw API shape: an array for list commands, an object for single-record commands.

Global flags

--json
Raw JSON instead of a table. Available on every command.
-v, --version
Print the version and exit.
-h, --help
Works at every level, including nested groups.

Conventions

--page / --page-size
On list commands. Defaults 1 and 100, maximum 1000.
--sku / --id / --barcode
Product lookup takes exactly one of the three.
--item k=v,k=v
Repeatable, for multi-line payloads such as parcels and fulfilments.
--file -
Reads a JSON body from stdin where a flag would be unwieldy.

Exit code 0 on success and 1 on any failure, with the error written to stderr, so set -e and CI steps behave the way you expect.

Recipes

A few things worth copying

low stock

$ stockpilot inventory list --page-size 1000 --json \
    | jq '.[] | select(.quantity < 10) | .sku'

"MUG-WHT-330"
"TSHIRT-BLK-M"

ship an order

$ stockpilot shipping suggestion 55120
template 8  ·  carrier 3  ·  vvb_parcel

$ stockpilot shipping request-label 55120 \
    --carrier-id 3 --template-id 8
entity_id lbl_88fa2e  ·  queued

$ stockpilot orders fulfil 55120 --tracking-code 3SABC123

book in a delivery

$ stockpilot purchase-orders parcels create 42 \
    --item sku=WIDGET-1,quantity=6 \
    --reference "DHL 4471"

parcel 118 registered · 6 units booked in

watch a webhook

$ stockpilot webhooks create --name "erp bridge" \
    --event inventory.stock_changed \
    --target-url https://erp.example.com/hooks

$ stockpilot webhooks test wh_7f3a91
200 OK · 142ms

$ stockpilot webhooks deliveries wh_7f3a91

Reference

All 77 commands

Generated from the CLI's own help output, so it cannot drift from the binary. Expand any command for its flags.

access analytics brands bundles categories channels customers inventory invoices login orders products purchase-orders returns shipping status warehouses webhooks whoami

stockpilot access Show or change whether this profile may modify data.

stockpilot access set LEVEL Set access to "full" or "read-only"

stockpilot analytics Sales analytics

stockpilot analytics history Order history for a single product

--barcode string: Barcode / EAN
--from string: Start date (YYYY-MM-DD)
--id string: Product ID
--sku string: SKU
--to string: End date (YYYY-MM-DD)

stockpilot analytics sales Sales analytics for a single item

--barcode string: Barcode / EAN
--id string: Product ID
--include-channels: Include a per-channel breakdown
--metrics string: Comma-separated metrics (total_orders, total_items, revenue, forecast, pricing, daily_breakdown)
--range int: Number of days to look back
--sku string: SKU

stockpilot analytics summary Sales summary across all items

--range int: Number of days to look back (default 14)
--top-items int: Number of top selling items to include (default 10)

stockpilot brands Manage brands

stockpilot brands create NAME Create a brand

stockpilot brands list List all brands

stockpilot bundles Manage product bundles

stockpilot bundles create Create a bundle

--active: Whether the bundle is active (default true)
--b2b: Whether the bundle is B2B only
--barcode string: Bundle barcode (required)
--description string: Description
--name string: Bundle name (required)
--purchase-price float: Purchase price
--sku string: Bundle SKU (required)
--wholesale-price float: Wholesale price

stockpilot bundles delete BUNDLE_ID Permanently delete a bundle and its items

stockpilot bundles get BUNDLE_ID Get a bundle and its items

stockpilot bundles items add BUNDLE_ID Add or update products in a bundle

--item stringArray: Product to add, e.g. product_id=12,quantity=3 (repeatable)

stockpilot bundles items remove BUNDLE_ID PRODUCT_ID Remove a product from a bundle

stockpilot bundles items update BUNDLE_ID PRODUCT_ID Update the quantity of a product in a bundle

--quantity int: New quantity (required)

stockpilot bundles list List bundles

--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot bundles update BUNDLE_ID Update a bundle

--active: Whether the bundle is active (default true)
--b2b: Whether the bundle is B2B only
--barcode string: Bundle barcode
--description string: Description
--name string: Bundle name
--purchase-price float: Purchase price
--sku string: Bundle SKU
--wholesale-price float: Wholesale price

stockpilot categories Manage categories

stockpilot categories create NAME Create a category

stockpilot categories list List all categories

stockpilot channels Manage sales channels

stockpilot channels list List all sales channels and integrations

--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot channels sync Queue a listing sync for a connected channel

--channel string: Channel handle, exactly as returned by channels list (required)
--channel-id int: Channel ID (required)
--full-sync: Run a full sync rather than an incremental one

stockpilot customers Manage customers

stockpilot customers list List customers

stockpilot customers update CUSTOMER_ID Update a customer's details

--business-name string: Business name
--invoice-email string: Invoice email address
--notes string: Special notes
--orders-email string: Orders email address
--payment-status string: Payment status
--payment-terms int: Payment terms in days
--phone string: Phone number
--vat-number string: VAT number

stockpilot inventory Manage inventory items

stockpilot inventory create Create a new inventory item

--active: Whether the item is active (default true)
--barcode string: Barcode / EAN (required)
--barcode-type string: Barcode type (e.g. EAN, UPC)
--base-price float: Base price
--condition string: Condition
--height float: Height
--item-name string: Display name (required)
--length float: Length
--moq int: Minimum order quantity
--product-id int: Parent product ID (required)
--purchase-price float: Purchase price
--quantity int: Initial quantity
--sku string: SKU, must be unique (required)
--stock-threshold int: Low stock threshold in units
--vat-class string: VAT class
--weight string: Weight
--wholesale-price float: Wholesale price
--width float: Width

stockpilot inventory get Get a single inventory item by SKU, ID, or barcode

--barcode string: Barcode / EAN
--id string: Product ID
--sku string: SKU

stockpilot inventory list List all inventory items

--created-at string: Filter by creation date (YYYY-MM-DD)
--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot inventory set-image ITEM_ID Set an inventory item's image from a file or URL

--file string: Local image file to upload
--url string: Remote image URL

stockpilot inventory update Update an inventory item's quantity, pricing, location, or threshold

--active: Whether the item is active (default true)
--barcode string: Barcode / EAN
--base-price float: Base price
--condition string: Condition
--height float: Height
--id string: Inventory item ID
--item-name string: Display name
--length float: Length
--location string: Assign bin location (e.g. A1-001-01)
--moq int: Minimum order quantity
--purchase-price float: Purchase price
--quantity int: New quantity (absolute)
--remove-location string: Remove a bin location
--retail-price float: Retail price
--sale-price float: Sale price
--sku string: SKU
--stock-threshold int: Low stock threshold in units
--threshold string: Stock threshold (e.g. 5u or 33w)
--vat-class string: VAT class
--weight string: Weight
--wholesale-price float: Wholesale price
--width float: Width

stockpilot invoices Retrieve and send order invoices

stockpilot invoices get ORDER_PK Download an order's invoice PDF

--output string: Where to write the PDF (default invoice-ORDER_PK.pdf, "-" for stdout)

stockpilot invoices send ORDER_PK Email an order's invoice.

--file string: Your own invoice PDF to send instead of a generated one

stockpilot orders Manage orders

stockpilot orders backorder add ORDER_ID Move order items to backorder

--item stringArray: Item to move, e.g. item_id=5,quantity=2 (repeatable)

stockpilot orders backorder release ORDER_ID Move order items out of backorder once stock is available

--item stringArray: Item to release, e.g. item_id=5,quantity=2 (repeatable)

stockpilot orders cancel ORDER_PK Cancel an order

--reason string: Cancellation reason code

stockpilot orders cancellation-request ORDER_PK Check whether an order has a cancellation request

stockpilot orders cancellation-requests List orders with open cancellation requests

--page int: Page number (default 1)

stockpilot orders create Create a new order.

--file string: JSON file with the order payload, or "-" for stdin

stockpilot orders delete ORDER_ID Delete an entire order and all its items

--book-back: Return all item quantities to inventory

stockpilot orders fulfil [ORDER_PK] Register fulfillment for an order

--carrier-code string: Carrier code
--carrier-name string: Carrier name
--fulfilled-at string: Fulfillment timestamp (ISO 8601)
--item stringArray: Partial fulfillment item, e.g. sku=ABC,quantity=2 (repeatable)
--order-number string: Order number
--order-pk string: Order primary key
--service string: Shipping service
--shipment-type string: Shipment type
--shipping-method string: Shipping method
--tracking-code string: Tracking code
--tracking-url string: Tracking URL

stockpilot orders fulfillment ORDER_PK Show fulfillment and tracking details for an order

stockpilot orders get [ORDER_PK] Get a single order by primary key or order number

--order-number string: Order number
--order-pk string: Order primary key

stockpilot orders items add ORDER_PK Add a product to an existing order

--product-id int: Product ID (required)
--quantity int: Quantity (required)
--retail-price float: Retail price (required)
--vat-rate int: VAT rate

stockpilot orders items delete ORDER_ID ITEM_ID Remove an item from an order

--book-back: Return the item quantity to inventory
--book-back-quantity int: Quantity to return to inventory

stockpilot orders items swap ORDER_PK Replace the product on an order item, keeping quantity and price

--item-id int: Order item ID to swap (required)
--new-product-id int: Replacement product ID (required)

stockpilot orders items update ITEM_ID Update an ordered item's quantity or refund

--file string: JSON file with additional fields, or "-" for stdin
--quantity int: New quantity
--refund float: Refund amount

stockpilot orders list List orders

--commission: Include per-line-item commission
--is-forwarded string: Include forwarded orders (default true)
--page int: Page number (default 1)
--page-size int: Items per page (default 100)
--status string: Filter by status, comma-separated (open, pending, on-hold, cancelled, completed)

stockpilot orders set-status ORDER_ID STATUS Update an order's status

stockpilot orders update-customer ORDER_ID Update billing, shipping, and contact details on an order

--file string: JSON file with customer details, or "-" for stdin

stockpilot orders update-forwarding ORDER_ID Mark an order as forwarded to another system

--register-order-id string: External order ID (required)
--source string: Forwarding source system (required)

stockpilot products Manage products

stockpilot products create Create a new product

--active: Whether the product is active (default true)
--brand int: Brand ID (defaults to "Brandless")
--category int: Category ID (defaults to "Uncategorized")
--description string: Product description
--title string: Product title (required)

stockpilot products get Get a product by ID

--id string: Product ID (required)

stockpilot products list List products

--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot products set-image PRODUCT_ID Set a product's image from a file or URL

--file string: Local image file to upload
--url string: Remote image URL

stockpilot purchase-orders Manage purchase orders and inbound deliveries

stockpilot purchase-orders create Create a purchase order.

--delivery-warehouse-id int: Destination warehouse ID
--expected-delivery string: Expected delivery date (YYYY-MM-DD)
--file string: JSON file with the full payload, or "-" for stdin
--item stringArray: Item to order, e.g. sku=ABC,quantity=10,purchase_price=4.50 (repeatable)
--order-note string: Note on the order
--processed-by string: Who placed the order
--shipping-cost float: Shipping cost
--supplier-id int: Supplier ID (required)

stockpilot purchase-orders get ORDER_ID Get a purchase order with its items and delivery state

stockpilot purchase-orders list List purchase orders

--page int: Page number (default 1)
--page-size int: Items per page (default 100)
--status string: Filter by status
--supplier-id int: Filter by supplier ID

stockpilot purchase-orders parcels create ORDER_ID Register a delivery against a purchase order.

--async: Apply the parcel to stock in the background
--item stringArray: Delivered item, e.g. sku=ABC,quantity=6 (repeatable; omit to book in everything outstanding)
--reference string: Delivery reference

stockpilot purchase-orders parcels delete ORDER_ID PARCEL_ID Remove a parcel that was never applied to stock

stockpilot purchase-orders recommend Start generating purchase order recommendations.

--durability int: Days of stock the order should cover
--file string: JSON file with the full payload, or "-" for stdin
--include-flagged: Include flagged products
--include-inbound: Account for stock already inbound (default true)
--lead-time int: Supplier lead time in days
--scope-days int: Days of sales history to base the forecast on
--supplier-id int: Supplier to generate recommendations for

stockpilot purchase-orders recommend-status TASK_ID Check a recommendations task (PROCESSING, COMPLETED, or FAILED)

stockpilot purchase-orders suppliers List suppliers available for purchase orders

stockpilot returns List customer returns

stockpilot returns List customer returns

--channel-id int: Sales channel ID (use with --handle)
--handle string: Sales channel handle (use with --channel-id)
--page int: Page number (default 1)
--page-size int: Items per page (default 100)
--status string: Filter by status, comma-separated (requested, partly_accepted, accepted)

stockpilot shipping Shipping integrations, templates, and labels

stockpilot shipping integrations List configured shipping integrations

stockpilot shipping request-label ORDER_PK Request a shipping label for an order.

--carrier-id int: Carrier ID (required)
--template-id int: Label template ID (required)

stockpilot shipping retrieve-label ORDER_PK Download a previously requested shipping label

--entity-id string: Entity ID returned by request-label (required)
--output string: Where to write the PDF (default label-ORDER_PK.pdf, "-" for stdout)
--service string: Shipping service (required)

stockpilot shipping suggestion ORDER_PK Get the label template your shipping rules suggest for an order

stockpilot shipping templates List available shipping label templates

--carrier string: Carrier type, e.g. vvb_mailbox, vvb_parcel, or letter
--id string: Template ID (channel ID for vvb, or stamped/unstamped for letter)

stockpilot status Open orders and inventory overview

stockpilot status Open orders and inventory overview

stockpilot warehouses Inspect warehouses and their stock

stockpilot warehouses items UNIQUE_ID List the stock held in a warehouse

--barcode string: Filter by barcode
--page int: Page number (default 1)
--page-size int: Items per page (default 100)
--sku string: Filter by SKU

stockpilot warehouses list List warehouses

--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot webhooks Manage outbound webhooks

stockpilot webhooks create Create a webhook subscription

--event string: Event type, e.g. orders.completed or inventory.stock_changed (required)
--name string: Human readable name (required)
--secret string: Signing secret, minimum 16 characters
--target-url string: HTTPS endpoint that receives deliveries (required)
--warehouse-id string: Restrict deliveries to one warehouse

stockpilot webhooks delete WEBHOOK_ID Deactivate a webhook, keeping its delivery history

stockpilot webhooks deliveries WEBHOOK_ID List recent delivery attempts, newest first

--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot webhooks events List the event types you can subscribe to

stockpilot webhooks get WEBHOOK_ID Get a webhook subscription

stockpilot webhooks list List webhook subscriptions.

--category string: Filter by event category, e.g. orders or inventory
--event string: Filter by exact event type
--page int: Page number (default 1)
--page-size int: Items per page (default 100)

stockpilot webhooks reactivate WEBHOOK_ID Reactivate a deleted or auto-deactivated webhook

stockpilot webhooks test WEBHOOK_ID Send a signed test delivery and show the response

stockpilot webhooks update WEBHOOK_ID Update a webhook subscription.

--event string: Event type, e.g. orders.completed or inventory.stock_changed
--name string: Human readable name
--secret string: Signing secret, minimum 16 characters
--target-url string: HTTPS endpoint that receives deliveries
--warehouse-id string: Restrict deliveries to one warehouse

stockpilot whoami Verify credentials and show your organization

stockpilot whoami Verify credentials and show your organization

Agents

It ships with a skill file

The repository includes skills/SKILL.md, a written brief that teaches Claude, Cursor or Codex how to drive the CLI: which command answers which question, how to chain them, and the data formats it will meet. Drop it into your agent and it stops guessing at flags.

Give an agent warehouse access Read SKILL.md ↗

claude

> Which SKUs run out within two weeks?

$ stockpilot inventory list --json
$ stockpilot analytics summary --range 30 --json

7 SKUs below two weeks of cover:
  TSHIRT-BLK-M  42 units · 9d
  MUG-WHT-330   18 units · 4d

Your whole warehouse, from the terminal

One line on macOS and Linux

Direct downloads

Log in once

Read-only, when you want it

Tables for you, JSON for everything else

Global flags

Conventions

A few things worth copying

All 77 commands

stockpilot access Show or change whether this profile may modify data.

stockpilot analytics Sales analytics

stockpilot brands Manage brands

stockpilot bundles Manage product bundles

stockpilot categories Manage categories

stockpilot channels Manage sales channels

stockpilot customers Manage customers

stockpilot inventory Manage inventory items

stockpilot invoices Retrieve and send order invoices

stockpilot login Save your Stockpilot API credentials

stockpilot orders Manage orders

stockpilot products Manage products

stockpilot purchase-orders Manage purchase orders and inbound deliveries

stockpilot returns List customer returns

stockpilot shipping Shipping integrations, templates, and labels

stockpilot status Open orders and inventory overview

stockpilot warehouses Inspect warehouses and their stock

stockpilot webhooks Manage outbound webhooks

stockpilot whoami Verify credentials and show your organization

It ships with a skill file