Ocapi CLI

Manage Ocapi stores from the terminal: products (with deals and addons), categories, orders and images. It talks to the public API (/api/v1) of the Ocapi dashboard and signs in with OAuth, so it works for people and for AI coding agents alike.

Requires Node.js 20 or newer. There are no dependencies.

Install

npm install -g @rebondi/ocapi   # puts `ocapi` on your PATH
npx @rebondi/ocapi help         # or run it without installing

Sign in

ocapi login              # opens your browser; approve the CLI on the Ocapi consent page
ocapi login --read-only  # only read access
ocapi whoami
ocapi logout             # revokes this CLI's access

Credentials are saved in ~/.config/ocapi/config.json (mode 0600). The access token lasts an hour and is refreshed automatically. Merchants can disconnect the CLI from Settings → Connected apps.

OCAPI_TOKEN=<access token> overrides the saved sign-in, and OCAPI_URL or --url picks the server, e.g. https://dev.ocapi.shop for a local Rails app behind the dev tunnel.

Examples

ocapi stores create --name "Café Nube" --phone +573001234567 --currency COP   # a new account's store
ocapi stores list
ocapi stores use str_01j...                      # default store for later commands
ocapi products list --category Mugs
ocapi products create --name "Blue mug" --price 30000 --sale-price 25000 --category Mugs \
  --inventory 10 --image-url "$(ocapi images import https://example.com/mug.jpg)"
ocapi products update prd_01j... --no-hidden --sale-price none
ocapi products create --name "Tee" --price 50000 --data '{"variant_type":"size1","variants":[{"name":"S"},{"name":"M"}]}'
ocapi products update prd_01j... --combo 2:55000 --bulk-discount 5:10% --bogo none   # deals; "none" removes one
ocapi products update prd_01j... --data '{"addons":[{"name":"Gift wrap","type":"checkbox","options":[{"name":"Wrap","price":2000}]}]}'
ocapi orders list --payment paid --status processing
ocapi orders status ord_01j... shipped
ocapi orders status ord_01j... --payment paid       # record the payment of a manual-payment order
ocapi orders create --name "Carla" --phone 573001112233 --item prd_01j...:Mx2 --item prd_01j... --payment paid
ocapi api GET /api/v1/stores/str_01j.../categories

Run ocapi help for every command. Add --json to any command to get the API's JSON, which is what scripts and agents should parse. Deletes ask for --yes.

Exit codes: 0 success, 1 API or network error, 2 usage error.

Develop

npm link                 # puts this checkout's `ocapi` on your PATH
npm test
node bin/ocapi.js help
script/sync-contract     # refresh contract/ from rebondi/ocapi-app after an API change

contract/ holds the API's OpenAPI spec and example responses, copied from rebondi/ocapi-app; the tests run every command against them. See AGENTS.md.