Mayar CLI — Agent Skill

This document describes how AI agents (Claude Code, OpenClaw, and others) should install, authenticate, and use the mayar CLI tool.

Quick start for agents

# Always use the latest version — no install step required
npx -y mayar@latest whoami

Authentication flow

Step 1 — detect active user

Run whoami to check if a valid API key is already configured:

npx -y mayar@latest whoami --json

Successful output contains "valid": true and the merchant's name, email, and accountId. If the key is valid, proceed directly to the requested task.

Step 2 — handle missing or invalid key

If whoami exits non-zero or returns "valid": false, the agent MUST stop and ask the user for their API key using one of the following options:

Option A — environment variable (recommended for non-interactive agents):

Ask the user to set:

export MAYAR_API_KEY=<their_key>

Then re-run the original command.

Option B — one-time flag (single command):

Ask the user to provide the key and pass it as:

npx -y mayar@latest --api-key <their_key> whoami

Option C — interactive setup (terminal agents only):

If the agent has access to an interactive TTY:

npx -y mayar@latest init

Agents must NEVER fabricate or guess an API key. Always stop and ask the user.

Get a key at: https://web.mayar.id → Integration → API Key

Usage reference

All commands use the pattern:

npx -y mayar@latest <command> [subcommand] [args] [flags]

Account

npx -y mayar@latest whoami              # verify key + show merchant identity
npx -y mayar@latest balance             # account balance

Invoices

npx -y mayar@latest invoice list [--page N --pageSize N]
npx -y mayar@latest invoice get <id>
npx -y mayar@latest invoice close <id>
npx -y mayar@latest invoice reopen <id>
npx -y mayar@latest invoice create --data '<json>'
npx -y mayar@latest invoice create --data @file.json

Products

npx -y mayar@latest product list [--page N --pageSize N]
npx -y mayar@latest product search <keyword>
npx -y mayar@latest product type <ebook|course|membership|saas|event|webinar>
npx -y mayar@latest product get <id>
npx -y mayar@latest product close <id>
npx -y mayar@latest product reopen <id>

Payments

npx -y mayar@latest payment list
npx -y mayar@latest payment get <id>
npx -y mayar@latest payment close <id>
npx -y mayar@latest payment reopen <id>
npx -y mayar@latest payment create --data '<json>'

Customers

npx -y mayar@latest customer list [--page N --pageSize N]
npx -y mayar@latest customer create --data '<json>'

Transactions

npx -y mayar@latest tx list   [--page N --pageSize N]   # paid
npx -y mayar@latest tx unpaid [--page N --pageSize N]   # unpaid

Dynamic QR

npx -y mayar@latest qrcode <amount_in_idr>

Webhooks

npx -y mayar@latest webhook register <url>
npx -y mayar@latest webhook test <url>
npx -y mayar@latest webhook history [--page N --pageSize N]

Global flags

JSON output

Always use --json when the agent needs to parse the response:

npx -y mayar@latest invoice list --json | jq '.data[] | {id, status}'
npx -y mayar@latest whoami --json | jq '{valid, name: .decoded.name}'

Error handling

• Non-zero exit code = command failed
• "valid": false in whoami --json = invalid or expired API key
• HTTP errors print API <status> — <message> on stderr

Agent decision tree

START
  └─ run: npx -y mayar@latest whoami --json
        ├─ exit 0 + valid=true  →  proceed with task
        └─ exit non-zero or valid=false
              └─ ask user:
                    "Please provide your Mayar API key.
                     You can either:
                     (A) set the MAYAR_API_KEY environment variable, or
                     (B) run: npx -y mayar@latest init
                     Get your key from https://web.mayar.id → Integration → API Key"