@koyweforest/cli

CLI for the Koywe Treasury API. Manage organizations, merchants, orders, deals, contacts, webhooks, and more from your terminal.

Designed for both humans and AI agents (Claude Code, etc.) with structured JSON output, predictable command patterns, and machine-parseable exit codes.

Installation

npm install -g @koyweforest/cli

Quick Start

# 1. Authenticate with API key and secret
koywe auth login --api-key YOUR_API_KEY --secret YOUR_SECRET

# 2. Select your organization and merchant
koywe org list
koywe org select org3_xxxxxxxxx

koywe merchant list
koywe merchant select mrc_xxxxxxxxx

# 3. Done — all commands use that context automatically
koywe orders list
koywe deals list
koywe contacts list

Authentication

The CLI authenticates via API key + secret against POST /api/v1/auth/sign-in. The token is cached locally at ~/.koywe/.cache/token.json and refreshed automatically before expiry.

# Login with API key
koywe auth login --api-key KEY --secret SECRET

# Login via browser (interactive)
koywe auth browser-login

# Switch to production
koywe auth login --api-key KEY --secret SECRET --env production

# Environment variables also work (useful for CI/agents)
export KOYWE_API_KEY=your_key
export KOYWE_SECRET=your_secret
export KOYWE_BASE_URL=https://api.koywe.com

Commands

Auth & Configuration

koywe auth login --api-key KEY --secret SECRET   # Authenticate
koywe auth browser-login                          # Authenticate via browser
koywe auth me                                     # Current user info
koywe auth rotate-secret                          # Rotate API secret (saves the new one in the active profile)
koywe auth credentials create --name "My API" --roles role1 role2
koywe auth credentials create-org --name "Org Key" --roles role1
koywe auth credentials create-pos --data '{"alias":"store-1","password":"pass"}'

# MFA step-up via email OTP (human users only — API users use `auth mfa challenge-sign`; policy approvals only)
koywe auth mfa otp request                        # Emails a 6-digit code
koywe auth mfa otp verify --code 042915           # → { mfaToken } for --mfa-token

koywe config show                                 # Show current config
koywe config set environment production           # Switch environment
koywe config set baseUrl http://localhost:3000    # Point to local server
koywe config reset                                # Clear config and tokens

# Profiles — manage multiple environments with named configs
koywe config profile add production --env production --api-key KEY --secret SECRET
koywe config profile add staging --copy-from production --env sandbox
koywe config profile add dev --env sandbox --org-id ORG --merchant-id MRC
koywe config profile use production               # Switch active profile
koywe config profile list                          # List all profiles
koywe config profile remove staging                # Remove a profile

Organizations & Merchants

koywe org list                     # List organizations (legacy array)
koywe org list --search acme --page 1 --limit 20 --sort-by name --order asc
                                   # Paginated/searchable mode → { data, pagination } envelope
koywe org list --include authorization             # Add caller's effective roles/permissions per org (paginated)
koywe org info                     # Selected org details
koywe org info org3_xxx            # Specific org details (deep-link)
koywe org info org3_xxx --include authorization    # Add caller's effective roles/permissions in this org
koywe org select org3_xxx          # Set active org
koywe org balances                 # Organization balances
koywe org feature-flags            # Organization feature flags

koywe merchant list                # List merchants (legacy array)
koywe merchant list --search acme --page 1 --limit 20 --sort-by name --order asc
                                   # Paginated/searchable mode → { data, pagination } envelope
koywe merchant list --include authorization        # Add effective roles/permissions per merchant
koywe merchant select mrc_xxx      # Set active merchant
koywe merchant info                # Current merchant details
koywe merchant info --include authorization        # Add caller's roles/permissions in this merchant
koywe merchant create --data '{...}'
koywe merchant update --data '{"profile":{"supportEmail":"[email protected]"}}'   # Partial: the CLI completes the fields the PUT requires
koywe merchant features            # Merchant feature flags
koywe merchant list --is-credit-line true          # Only merchants with a credit line
koywe merchant credit-line --currency CLP          # Credit line capacity (USD): limit, committed, available

Orders

# List with filters
koywe orders list
koywe orders list --status ON_HOLD --type PAYIN
koywe orders list --start-date 2025-01-01 --end-date 2025-12-31 --sort createdAt:desc
koywe orders list --waiting-funds true --page-size 50
koywe orders get-by-tx-hash 0x5d3f9a1c2b7e4d6f8a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f --network POLYGON

# Details
koywe orders info ord_xxxxxxxxx
koywe orders get-by-external-id my-external-reference
koywe orders get-by-tx-hash 0x5d3f9a1c2b7e4d6f8a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f --network POLYGON
koywe orders list --waiting-funds true             # Payouts waiting for the merchant to fund them
koywe orders list --used-credit-line true          # Orders that drew on the credit line

# Create order (body as inline JSON, file, or stdin)
koywe orders create --data '{"type":"PAYIN","originCurrencySymbol":"CLP",...}'
koywe orders create --file order.json
cat order.json | koywe orders create

# Confirm order with MFA
koywe orders confirm ord_xxx --mfa-token 123456

# Update order
koywe orders update ord_xxx --data '{"txHash":"0x5d3f9a1c2b7e4d6f8a0b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f"}'

# Re-send the payment email of a PENDING payment link to its contact
koywe orders notify ord_xxx

Deals

koywe deals list --page 1 --page-size 20 --sort desc --start-date 2026-01-01
koywe deals info deal_xxx
koywe deals create --data '{"quoteId":"quo_xxx","destinationAccountId":"acc_xxx"}'
koywe deals confirm deal_xxx --pending-approval-id appr_xxx --mfa-token 123456

Quotes

koywe quotes info quo_xxx
koywe quotes create --data '{"originCurrencySymbol":"CLP","destinationCurrencySymbol":"USDC","executable":true,"orderType":"ONRAMP","amountIn":100000}'

Contacts

koywe contacts list
koywe contacts list --search "John" --page 1 --limit 20
koywe contacts list --country CL --business-type COMPANY --sort-by updatedAt --sort desc
koywe contacts info cnt_xxx
koywe contacts create --data '{"firstName":"John","countrySymbol":"CL","businessType":"PERSON","type":"PERSON"}'
koywe contacts update cnt_xxx --data '{"firstName":"Jane"}'
koywe contacts delete cnt_xxx

# Contact accounts
koywe contacts accounts list cnt_xxx
koywe contacts accounts info cnt_xxx acc_xxx
koywe contacts accounts create cnt_xxx --data '{"kind":"BANK","currencySymbol":"CLP",...}'
koywe contacts accounts update cnt_xxx acc_xxx --data '{"name":"Updated"}'
koywe contacts accounts delete cnt_xxx acc_xxx
koywe contacts accounts confirm-mfa cnt_xxx --pending-approval-id appr_xxx --mfa-token 123456

# Contact documents
koywe contacts documents delete cnt_xxx --data '{"documents":["doc_1","doc_2"]}'

Webhooks

koywe webhooks list
koywe webhooks info whk_xxx
koywe webhooks create --data '{"url":"https://my-server.com/webhook","secret":"my-secret"}'
koywe webhooks ping whk_xxx                  # Send test ping
koywe webhooks rotate-secret whk_xxx --secret "$(openssl rand -hex 32)"
koywe webhooks pause whk_xxx
koywe webhooks resume whk_xxx
koywe webhooks delete whk_xxx

# Event types — discover what you can subscribe to
koywe webhooks event-types

# Subscriptions — pick which events an endpoint receives
koywe webhooks subscriptions update whk_xxx --events order.created order.completed
koywe webhooks subscriptions update whk_xxx --events            # subscribe to all
koywe webhooks subscriptions update whk_xxx --data '{"subscribedEvents":["order.created"]}'

# Events — inspect deliveries with filters (type / date range / resource)
koywe webhooks events list
koywe webhooks events list --type order.created --limit 50
koywe webhooks events list --from 2026-01-01 --to 2026-01-31 --merchant-id mer_xxx
koywe webhooks events list --resource-type order --resource-id ord_xxx
koywe webhooks events info evt_xxx
koywe webhooks events deliveries evt_xxx
koywe webhooks events replay evt_xxx                          # To every active endpoint
koywe webhooks events replay evt_xxx --endpoint-id whk_xxx    # To one endpoint

Reports

# --account-id must be a virtual (balance) account; --from/--to span at most 365 days
koywe reports ledger --account-id acc_xxx --from 2025-01-01 --to 2025-12-31
koywe reports ledger --account-id acc_xxx --from 2025-01-01 --to 2025-01-31 --granularity monthly --order desc --limit 50
koywe reports ledger --account-id acc_xxx --from 2025-01-01 --to 2025-01-31 --cursor next_cursor_here --limit 50
koywe reports orders --account-id acc_xxx --from 2025-01-01 --to 2025-01-31 --type PAYOUT --status COMPLETED
koywe reports orders --account-id acc_xxx --from 2025-01-01 --to 2025-01-31 --cursor CURSOR
koywe reports orders --account-id acc_xxx
koywe reports ledger --account-id acc_xxx --from 2025-01-01 --to 2025-01-31 --order desc
koywe reports ledger-entry entry_xxx --account-id acc_xxx

Users & Invitations

koywe users me                       # Authenticated user profile
koywe users list                     # List merchant users
koywe users org-list                 # List org-level users
koywe users update-roles --user-id usr_xxx --roles k3r_operator k3r_viewer   # Role IDs; replaces current roles
koywe users org-update-roles --user-id usr_xxx --roles k3r_admin

# Merchant-level invitations (--page-size: 10|20|50|100; --status PENDING|ACCEPTED|EXPIRED|REVOKED)
koywe users invitations list --status PENDING
koywe users invitations create --data '{"email":"[email protected]","roles":["role1"]}'

# Org-level invitations
koywe users org-invitations list
koywe users org-invitations create --data '{"email":"[email protected]","roles":["role1"]}'

Bank Accounts

koywe bank-accounts list
koywe bank-accounts info acc_xxx
koywe bank-accounts create --data '{"name":"Main","kind":"BANK","currencySymbol":"CLP",...}'
koywe bank-accounts update acc_xxx --data '{"name":"Updated"}'
koywe bank-accounts delete acc_xxx
koywe bank-accounts balances
koywe bank-accounts balances --include-credit-line  # → { balances, creditLine? }
koywe bank-accounts balance acc_xxx
koywe bank-accounts search --kind BANK --country-symbol CL
koywe bank-accounts confirm-mfa --pending-approval-id appr_xxx --mfa-token 123456
koywe bank-accounts deposit-info              # Deposit account info (bank income)

# Virtual accounts
koywe bank-accounts virtual list
koywe bank-accounts virtual create --country AR                 # AR/ARS, MX/MXN or US/USD; US needs the onboarding started
koywe bank-accounts virtual update-alias pivba_xxx --alias john.doe.koywe   # 6-20 chars: letters, digits, dots

Policies & Approvals

koywe policy info
koywe policy create --mfa-token MFA_TOKEN     # No body; creates the org's single policy
koywe policy delete --mfa-token MFA_TOKEN
koywe policy audit

# Rules
# Without --mfa-token the change is left PENDING_APPROVAL (complete it with approvals approve)
koywe policy rules create --data '{"ruleOrder":1,"principalMatch":"*",...}' --mfa-token MFA_TOKEN
koywe policy rules update rule_xxx --data '{"description":"Updated"}' --mfa-token MFA_TOKEN
koywe policy rules delete rule_xxx --mfa-token MFA_TOKEN
koywe policy rules reorder --data '{"ruleOrders":[{"ruleId":"rule_1","ruleOrder":0},{"ruleId":"rule_2","ruleOrder":1}]}' --mfa-token MFA_TOKEN

# Approvals
koywe policy approvals list
koywe policy approvals info appr_xxx
koywe policy approvals approve appr_xxx --mfa-token 123456
koywe policy approvals reject appr_xxx --mfa-token 123456

# OTC deal authorization (lets Koywe create OTC deals on the org's behalf)
koywe policy otc-authorization info --mfa-token <token>
koywe policy otc-authorization activate --mfa-token <token>
koywe policy otc-authorization revoke --mfa-token <token>

Notifications

koywe notifications send --data '{"type":"EMAIL","template":"order_created",...}'
koywe notifications send-personal --data '{"type":"PUSH","message":"Hello"}'

# In-app inbox
koywe notifications inbox list --page 1 --limit 20
koywe notifications inbox unread-count
koywe notifications inbox read ntf_xxx
koywe notifications inbox read-all

# Real-time stream (SSE → NDJSON on stdout; Ctrl-C to stop)
koywe notifications stream
koywe notifications stream --max-events 1 --timeout 60   # Wait for the next event

Wallet

koywe wallet status                                      # Embedded wallet provisioning status
koywe wallet terms status --terms-version wallet-2026-07 # Does the user still need to accept?
koywe wallet terms accept --terms-version wallet-2026-07

Crypto deposits

koywe crypto-deposits addresses                        # Deposit address per token + network (pending ones are provisioned in background)
koywe crypto-deposits unallocated                      # Deposits received without an order, waiting to be credited
koywe crypto-deposits allocate dep_xxx --currency USD  # Credit a deposit to a balance now

Sandbox

Test helpers that only work in sandbox (the CLI refuses them when environment is production).

koywe sandbox bank-income --currency USD --amount 1000
koywe sandbox bank-income --currency ARS --amount 500000 --document-type CUIT --document-number 30712345678
koywe sandbox notification --event-type order.completed --title "Test"    # In-app + SSE only
koywe sandbox emit-event --type order.completed                           # Webhooks + in-app + SSE

Onboarding

koywe onboarding me                            # Your onboarding status

# KYB (Know Your Business)
koywe onboarding kyb catalog --country CL      # Codes for select fields (+ document types for CL)
koywe onboarding kyb open --file kyb.json      # Open the KYB file (signatory required)
koywe onboarding kyb upload estatuto.pdf --field incorporationCertificate
koywe onboarding kyb upload ubo2.jpg --field beneficialOwnerIdentity --slot 1 --person-document-number 76111222-8
koywe onboarding kyb status                    # status, completionPercentage, missingFields
koywe onboarding kyb update --file fixes.json  # Corrections — objects merge, arrays replace
koywe onboarding kyb open --schema             # Body fields

Pre-Onboarding

koywe pre-onboarding drafts create --data '{"applicant":{...},"company":{...}}'
koywe pre-onboarding drafts info draft_xxx
koywe pre-onboarding drafts update draft_xxx --data '{"applicant":{...}}'
koywe pre-onboarding drafts submit draft_xxx
koywe pre-onboarding registrations list
koywe pre-onboarding registrations status reg_xxx

Reference Data

koywe currencies list
koywe currencies list --is-fiat true --country CL
koywe currencies info cur_xxx
koywe currencies by-symbol USDC

koywe banks list
koywe banks list --country-symbol CL

koywe countries list
koywe countries states CL
koywe countries state-info CL state_xxx
koywe countries counties CL state_xxx
koywe countries county-info CL state_xxx county_xxx
koywe countries economic-activities CL
koywe countries economic-activities-all        # Global (all countries)

koywe documents list
koywe payment-methods list --country CL --currency CLP
koywe reference company-roles
koywe reference feature-flags

Guided Flows

koywe setup                       # New user: browser sign-up + pre-onboarding
koywe init                        # Existing user: browser login + API key creation
koywe flow order                  # Interactive order creation

Body Input

Commands that accept a request body support three input methods:

# Inline JSON
koywe orders create --data '{"type":"PAYIN",...}'

# From file
koywe orders create --file order.json

# From stdin (pipe)
cat order.json | koywe orders create

# Show expected schema for a command
koywe orders create --schema

Output

JSON (default) — ideal for agents and scripts

$ koywe orders list
{
  "ok": true,
  "data": [...],
  "meta": {
    "timestamp": "2025-02-19T10:00:00Z"
  }
}

Paginated list commands

merchant list and org list support pagination/search flags (--page, --limit, --search, --sort-by, --order, --include). Whether or not you pass them, .data is always the list — when paginating, the CLI lifts pagination to the top level instead of nesting a second data:

$ koywe org list                       # no flags
{ "ok": true, "data": [ ... ] }

$ koywe org list --page 1 --limit 20   # any pagination flag
{ "ok": true, "data": [ ... ], "pagination": { "page": 1, "totalPages": 10, "totalItems": 199 } }

--include authorization adds an authorization block (the caller's effective roles + permissions for that scope) to each item / to the detail response.

Table — for human use

$ koywe orders list --format table
┌──────────┬──────────┬─────────┐
│ id       │ status   │ type    │
├──────────┼──────────┼─────────┤
│ ord_001  │ PENDING  │ PAYIN   │
│ ord_002  │ COMPLETED│ PAYOUT  │
└──────────┴──────────┴─────────┘

Errors — always JSON to stderr

$ koywe orders list  # without context configured
{
  "ok": false,
  "error": {
    "code": "NO_ORG_CONTEXT",
    "message": "No organization selected. Run: koywe org select <id>  or pass --org-id <id>"
  }
}
# exit code: 5

Machine-readable command list

koywe --commands                   # JSON list of all commands with API metadata

Each command entry carries its options, help (the examples and caveats from --help), and api (method, path, required context, and auth: mfa-required|mfa-optional). The output also lists command groups (with their own notes) and available guides.

Exit Codes

| Code | Meaning | |------|---------| | 0 | Success | | 1 | General error | | 2 | Authentication error | | 3 | Validation error | | 4 | Resource not found | | 5 | Config/context error |

Global Flags

| Flag | Description | |------|-------------| | --format json\|table | Output format (default: json) | | --commands | Print all commands as JSON | | --org-id <id> | Organization override | | --merchant-id <id> | Merchant override |

Environment Variables

| Variable | Description | |----------|-------------| | KOYWE_API_KEY | API key (overrides config) | | KOYWE_SECRET | Secret (overrides config) | | KOYWE_BASE_URL | Full API base URL override | | KOYWE_ENV | Environment: sandbox or production | | KOYWE_ORG_ID | Organization ID | | KOYWE_MERCHANT_ID | Merchant ID |

Agent Usage (Claude Code, etc.)

The CLI is designed to be invoked by AI agents. Structured JSON output and exit codes make it easy for agents to execute commands and parse results.

Recommended discovery path for an agent:

koywe --commands                 # what exists, which flags, which context / MFA each command needs
koywe guide                      # list workflow tutorials
koywe guide getting-started      # output + exit-code contract, context, idempotency tips
koywe guide kyb                  # also: mfa, approvals, payouts, events, sandbox-testing
koywe orders create --schema     # body fields before sending --data

Guides return { topic, title, summary, steps: [{ run, note }], pitfalls, related }; --format table renders them as readable text.

# An agent can chain commands easily
koywe orders list | jq '.data[] | select(.status == "PENDING") | .id'

# Or use environment variables without interactive login
KOYWE_API_KEY=key KOYWE_SECRET=secret KOYWE_ORG_ID=org KOYWE_MERCHANT_ID=mrc \
  koywe orders list

License

MIT