@koyweforest/cli

CLI for the Koywe Treasury API. Manage organizations, merchants, orders, deals, contacts, webhooks, wallets, 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
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"}'

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
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
koywe merchant select mrc_xxx      # Set active merchant
koywe merchant info                # Current merchant details
koywe merchant create --data '{...}'
koywe merchant update --data '{...}'
koywe merchant features            # Merchant feature flags

Orders

# List with filters
koywe orders list
koywe orders list --status PENDING --type PAYIN
koywe orders list --start-date 2025-01-01 --end-date 2025-12-31 --sort createdAt:desc

# Details
koywe orders info ord_xxxxxxxxx
koywe orders get-by-external-id my-external-reference

# 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":"0x..."}'

# Send notification
koywe orders notify ord_xxx --type EMAIL

Deals

koywe deals list
koywe deals info deal_xxx
koywe deals create --data '{"quoteId":"quo_xxx","destinationAccountId":"acc_xxx"}'
koywe deals transfer deal_xxx --data '{"scheduledDealId":"...","destinationEmail":"..."}'
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 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
koywe webhooks pause whk_xxx
koywe webhooks resume whk_xxx
koywe webhooks delete whk_xxx

# Events
koywe webhooks events list
koywe webhooks events info evt_xxx
koywe webhooks events deliveries evt_xxx
koywe webhooks events replay evt_xxx

Wallets

koywe wallets info
koywe wallets addresses --data '{"evmAddress":"0x...","solanaAddress":"..."}'
koywe wallets request-otp
koywe wallets transaction --data '{"account_id":"...","amount":"100",...}'

Reports

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 --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
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 role1 role2
koywe users org-update-roles --user-id usr_xxx --roles role1

# Merchant-level invitations
koywe users invitations list
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 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 --data '{"currencySymbol":"CLP"}'
koywe bank-accounts virtual update-alias acc_xxx --data '{"alias":"my-alias"}'

Policies & Approvals

koywe policy info
koywe policy create --data '{"name":"My Policy"}'
koywe policy delete
koywe policy audit

# Rules
koywe policy rules create --data '{"ruleOrder":1,"principalMatch":"*",...}'
koywe policy rules update rule_xxx --data '{"description":"Updated"}'
koywe policy rules delete rule_xxx
koywe policy rules reorder --data '{"ruleOrders":["rule_1","rule_2"]}'

# 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

Notifications

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

Onboarding

koywe onboarding me                            # Your onboarding status

# KYB (Know Your Business)
koywe onboarding kyb list                      # List KYB processes
koywe onboarding kyb trigger                   # Trigger KYB process
koywe onboarding kyb trigger --force-retrigger # Force re-trigger
koywe onboarding kyb status kyb_xxx            # Check KYB process status

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"
  }
}

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

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:

# 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