WooPayments CLI

wcpay gives you a terminal-native way to understand what is happening on a WooPayments store without opening wp-admin or writing one-off REST scripts.

Use it when you need to answer questions like:

• Is this store connected and running in live, test, or dev mode?
• What are the latest transactions, deposits, disputes, or charges?
• What request would a refund, authorization capture, or test payment send?
• Can an agent or script safely inspect this store with structured JSON output?

The CLI works with local and remote stores, stores credentials keychain-first, and treats live stores as read-only. Write-capable commands are only allowed when WooPayments is in test/dev mode, and they require either --dry-run or --yes.

How it works

Running wcpay without a command gives a short, terminal-native starting point:

The login flow guides you through WooCommerce REST API key entry, verifies the connection, and suggests useful next commands:

Installation

Install the latest packaged release from GitHub:

npm install -g https://github.com/Automattic/wcpay-cli/releases/download/v0.2.4/automattic-wcpay-cli-0.2.4.tgz

Or, clone the repo and build it manually:

git clone git@github.com:Automattic/wcpay-cli.git && cd wcpay-git
npm install
npm run build
npm link

Connect a store with the guided login flow:

wcpay login --site https://store.example --name staging

The wizard saves credentials in your OS keychain when available. Create a WooCommerce REST API key for a user with manage_woocommerce capability; use read-only keys for read-only inspection and read/write keys only for write-capable test/dev workflows.

Then check that the CLI can talk to WooPayments:

wcpay doctor
wcpay mode
wcpay account status

For local development stores, HTTP is supported for localhost-style URLs:

wcpay login --site http://localhost:8082 --name local --no-verify

Common workflows

Check store health

wcpay doctor
wcpay doctor --json --redact

Use doctor before debugging a store. It verifies the selected profile, site URL, credentials, and WooPayments mode.

Inspect money movement

wcpay transactions list --limit 25
wcpay transactions summary
wcpay deposits list
wcpay deposits get po_...
wcpay deposits overview
wcpay disputes list
wcpay disputes get dp_...
wcpay disputes summary
wcpay charges get ch_...
wcpay authorizations list
wcpay timeline get pi_...
wcpay orders get 123

These commands are read-only and safe to run against live stores. Amounts are formatted as currency in human output; pass --all to a list command to fetch every page, and --verbose to see redacted request/response logs.

Try a write safely

wcpay refunds create --order 123 --amount 500 --dry-run
wcpay authorizations capture --order 123 --intent pi_... --dry-run
wcpay disputes close dp_... --dry-run

--dry-run resolves the request, checks the store mode, redacts secrets, and prints what would be sent without making the write request.

Use the underlying REST API

wcpay api get /wc/v3/payments/accounts --json
wcpay api get /wc/v3/payments/transactions page:=1 pagesize:=25 --json

The raw API command is useful when a curated command does not exist yet. Non-read methods still use the same live-mode guard and are limited to reviewed WooPayments/WooCommerce paths unless --allow-unsafe-path is passed explicitly.

Work with agents

wcpay mcp

wcpay mcp starts a local stdio MCP server with read-only WooPayments tools. It uses the same profiles, credentials, and safety model as the CLI.

Authentication and storage

wcpay login stores WooCommerce REST API consumer keys/secrets. Secrets are stored in the OS keychain when available:

• macOS: Keychain via security
• Linux: Secret Service via secret-tool

If the OS keychain is unavailable, the CLI fails with instructions instead of silently writing secrets to disk. Set WCPAY_KEYRING=0 to explicitly use file-backed secret storage for CI/containers.

For ephemeral environments you can skip profiles entirely with environment variables:

export WCPAY_SITE_URL=https://store.example
export WCPAY_CONSUMER_KEY=ck_...
export WCPAY_CONSUMER_SECRET=cs_...
wcpay doctor --json

Commands exit with category codes (2 usage, 3 auth, 4 API failure, 5 live-mode write blocked) so scripts and agents can branch on failure type — see the command guide for the full table.

Documentation

A rendered docs site is available at https://automattic.github.io/wcpay-cli/.

• Getting started
• Authentication
• Safety model
• Command guide
• Generated command reference
• API command syntax
• MCP
• Packaging and release

Package identity

• Repository: Automattic/wcpay-cli
• npm package: @automattic/wcpay-cli
• binary: wcpay