mayar

name	mayar
display_name	Mayar CLI
version	0.1.9
description	Interact with the Mayar payment platform (invoices, products, payments, customers, transactions, webhooks, QR codes) from any AI agent or shell. Zero dependencies — Node.js 18+ only.
author	Mayar bot
license	MIT
homepage	https://github.com/mayarid/mayar-cli
repository	https://github.com/mayarid/mayar-cli.git
tags	["payments","invoices","mayar","indonesia","cli","tool"]
runtime	node>=18
install_command	npx -y mayar@latest
invoke_prefix	npx -y mayar@latest
env	{"MAYAR_API_KEY":{"description":"Mayar API key. Obtain from web.mayar.id → Integration → API Key.","required":true,"secret":true},"MAYAR_API_URL":{"description":"Override API base URL. Defaults to https://api.mayar.id.","required":false,"default":"https://api.mayar.id"}}
auth	{"type":"bearer","resolution_order":[{"flag":"--api-key"},{"env":"MAYAR_API_KEY"},{"file":"~/.config/mayar/config.json"}]}
capabilities	["invoices","products","payments","customers","transactions","reviews","webhooks","qrcode","balance","whoami"]

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>'
npx -y mayar@latest customer search <email>            # look up by email
npx -y mayar@latest customer update <fromEmail> <toEmail>
npx -y mayar@latest customer magic-link <email>        # email portal login link

Transactions

npx -y mayar@latest tx list   [--page N --pageSize N]   # paid
npx -y mayar@latest tx unpaid [--page N --pageSize N]   # unpaid
npx -y mayar@latest tx daily                            # today's volume + count

Reviews

npx -y mayar@latest review list [--page N --pageSize N]

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

Flag	Description
--json	Output raw JSON (machine-readable, pipe to jq)
--api-key <key>	Override saved key for this invocation
--page N	Pagination page (default 1)
--pageSize N	Items per page (default 10)
-v, --version	Print version
-h, --help	Print help

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"