Koywe CLI

The Koywe CLI (@koyweforest/cli) is a command-line tool that covers every operation in the Koywe Platform API: accounts, orders, quotes, deals, contacts, webhooks, policy, reports, and more.

It’s designed for both human developers and AI agents (Claude Code and similar). Every command returns a structured JSON envelope, most mutating commands accept a --schema flag that prints the full request-body JSON schema, and the CLI exposes its own command catalog via --commands.

Looking for the full command catalog? Every command is listed on the CLI Command Reference page, generated directly from the CLI’s own metadata — run npx @koyweforest/cli --commands for the raw JSON. Or flip the index: the API ↔ CLI Cross-Reference lets you look up a CLI command by REST endpoint.

Install or run

The fastest way to get started — no install needed:

npx @koyweforest/cli --help

npx is what you’ll usually want in CI, sandboxed agents, and one-off terminals — it pins the version per invocation and leaves nothing behind.

For regular local use, install globally and use the short koywe alias:

npm install -g @koyweforest/cli
koywe --help

Requires Node.js >= 18.

The rest of this page uses koywe … to keep examples readable. If you haven’t installed globally, read every koywe as npx @koyweforest/cli.

Quick start for agents

Zero-to-first-order in three commands:

koywe init                 # Browser login + auto-create API credentials
koywe config set organizationId <org>
koywe flow order           # Guided: quote → create order → wait for approval

init and setup both open a browser to sign you in on localhost and then provision credentials via the API — no copying secrets out of a dashboard. Use setup if you don’t yet have a merchant; use init if you already do.

Authentication

Three lanes, pick one:

Browser login (humans)

koywe auth browser-login

1. 1

   CLI starts a local listener

   The CLI binds a short-lived HTTP server on 127.0.0.1:<random-port> and generates a CSRF state nonce.

2. 2

   CLI opens the browser

   It opens https://api.koywe.com/api/v1/cli-auth?callback=<loopback-url>&state=<nonce> in your default browser.

3. 3

   API validates and redirects

   GET /api/v1/cli-auth verifies that callback is a http://127.0.0.1:<port>/... URL and redirects the browser to the Koywe dashboard’s /cli-auth page, carrying the callback and state through.

4. 4

   Dashboard authorizes and posts back

   If you’re already signed in, the dashboard page posts a short-lived token to the loopback callback, echoing the state so the CLI can verify it matches the one it generated.

5. 5

   CLI caches the token

   On match, the CLI writes ~/.koywe/.cache/token.json and the HTTP listener shuts down. You’re signed in.

API key + secret (CI, agents, scripts)

koywe auth login --api-key YOUR_KEY --secret YOUR_SECRET
# target production explicitly:
koywe auth login --api-key YOUR_KEY --secret YOUR_SECRET --env production

Environment variables (zero-config CI / agents)

The token is cached at ~/.koywe/.cache/token.json and refreshed automatically.

Command groups at a glance

See the full command reference →

Schema-first discovery for agents

26 of the 142 commands in CLI v0.14.1 are --schema-capable (look for the 📐 marker in the full command reference). Among them:

koywe orders create --schema
koywe contacts create --schema
koywe bank-accounts create --schema
koywe policy rules create --schema

Note that not every create accepts --schema — for example, auth credentials create and users invitations create don’t (they have bespoke option flags instead). Run npx @koyweforest/cli --commands | jq '.data.commands[] | select(.hasSchema) | .name' for the authoritative list.

The output includes field names, types, required flags, enums, and per-field descriptions — it’s the same shape the API validates against. If the schema disagrees with the OpenAPI spec, the schema is authoritative (and that’s a bug worth reporting).

Machine-readable command catalog

koywe --commands

Emits the full command tree as JSON, with every command’s underlying api.method and api.path, its options, and whether it supports --schema. This is the same JSON used to generate the CLI Command Reference page, and it’s also published at /cli-commands.json.

Use it to translate between CLI invocations and direct REST calls, or to auto-generate tooling around the CLI.

Guided flows

flow chains multiple API calls into a single invocation. Two flows today:

flow order — quote + create + wait

# PAYIN: receive CLP via Khipu
koywe flow order \
  --type PAYIN \
  --origin CLP --destination CLP \
  --amount-in 100000 \
  --payment-method KHIPU
 
# PAYOUT: send CLP to a pre-registered bank account
koywe flow order \
  --type PAYOUT \
  --origin CLP --destination CLP \
  --amount-out 50000 \
  --destination-account-id bacc_...
 
# BALANCE_TRANSFER: convert between currencies inside a merchant
koywe flow order \
  --type BALANCE_TRANSFER \
  --origin CLP --destination USDC \
  --amount-in 50000 \
  --wait

Pass --wait to poll until the order leaves ON_HOLD (useful when a policy rule sends the order into approval). Pass --mfa-token <token> to confirm immediately instead of waiting.

flow deal — crypto ONRAMP/OFFRAMP in one go

koywe flow deal \
  --type ONRAMP \
  --origin USD --destination USDC \
  --network ETHEREUM \
  --amount-in 100 \
  --transfer \
  --destination-address 0x...

Policy — required for BALANCE_TRANSFER and MFA-gated operations

Many mutating operations (BALANCE_TRANSFER, transferring funds, sensitive config changes) require an active policy with at least one matching rule. Without a policy, the API returns POL00002 (zero-privilege deny) or POL00007 (approval required).

Minimum viable setup:

# Create an organization-level policy
koywe policy create --data '{"name":"default"}'
 
# Add a rule that allows BALANCE_TRANSFER orders
koywe policy rules create --schema   # see the exact schema
koywe policy rules create --data '{
  "name": "allow-balance-transfer",
  "scope": "ORDER",
  "match": { "orderType": ["BALANCE_TRANSFER"] },
  "decision": { "action": "ALLOW" }
}'

Operations gated by MFA_REQUIRED approvals return a pending approval ID. Approve via koywe policy approvals approve <id> or with a pre-minted --mfa-token.

Usage patterns

Create an order from inline JSON

koywe orders create --data '{
  "type": "PAYIN",
  "originCurrencySymbol": "CLP",
  "destinationCurrencySymbol": "USDC",
  "amountIn": 100000,
  "paymentMethods": [{ "method": "KHIPU" }]
}'

From a file

koywe orders create --file order.json

From stdin (pipe-friendly)

cat order.json | koywe orders create

List with filters

koywe orders list \
  --status COMPLETED --type PAYIN \
  --start-date 2025-01-01 \
  --format table

Output formats

JSON output follows a consistent envelope:

{
  "ok": true,
  "data": { ... },
  "meta": { "page": 1, "limit": 20, "total": 42 }
}

On error, the process exits non-zero and writes a JSON error envelope to stderr:

{
  "ok": false,
  "error": { "code": "BAA00008", "message": "The destination account currency does not match the order destination currency." }
}

See Error codes for the full catalog.

Exit codes

Global flags

Profile management

Switch between environments without re-authenticating:

koywe config profile add staging --env sandbox
koywe config profile add prod --env production
koywe config profile use staging
koywe config profile list