> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitpayapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HitPay CLI

> Command-line tool to manage payments, test webhooks, and generate QR codes from your terminal. Available for macOS, Linux, and Windows via npm.

The HitPay CLI is a command-line client for the HitPay API. Create payment requests, list charges, generate QR codes, and test webhooks end-to-end from your shell, scripts, and CI pipelines.

## What's Included

> **Account & Payments**
>
> Manage payment requests, charges, refunds, customers, invoices, subscriptions, beneficiaries, and transfers with a consistent `hitpay <resource> <action>` syntax.

> **Webhook Testing**
>
> `hitpay listen` tunnels your local server to the public internet and auto-registers a webhook endpoint. `hitpay trigger` simulates events without waiting for live traffic.

> **QR Codes in Terminal**
>
> `hitpay qr create` renders scannable QR codes directly in your terminal for PayNow, QRIS, PromptPay, GCash, DuitNow, and 50+ other methods across Southeast Asia.

## Installation

**1. Install the CLI**

Install globally with npm:

```bash theme={"system"}
npm install -g @hit-pay/cli
```

Or run without installing:

```bash theme={"system"}
npx @hit-pay/cli --help
```

Requires **Node.js 18 or later**.

**2. Log in**

Interactive login (prompts for API key):

```bash theme={"system"}
hitpay login
```

Or provide the key directly for non-interactive environments like CI:

```bash theme={"system"}
hitpay login --api-key sk-live-xxxxxxxxxxxx
```

Get your API key from **Dashboard → Settings → Payment Gateway → API Keys**.

**3. Verify**

Check you're logged in and on the right environment:

```bash theme={"system"}
hitpay whoami
```

Then run any command. For example, list recent charges:

```bash theme={"system"}
hitpay charge list
```

> [!WARNING]
>
> The CLI is in **Beta** (v0.1.0). If `npm install -g @hit-pay/cli` fails with a 404, install from source until the first npm publish:
>
> ```bash theme={"system"}
> git clone https://github.com/hit-pay/cli.git
> cd cli && npm install && npm run build && npm link
> ```

## Authentication & Config

Credentials are stored locally at `~/.hitpay/config.json` with `0600` permissions. Inspect or update them with the `config` command:

```bash theme={"system"}
hitpay config list
hitpay config set environment sandbox
hitpay config get currency
```

### Environment variables

Override any stored config with env vars, useful for CI:

| Variable | Description |
| - | - |
| `HITPAY_API_KEY` | API key; overrides `~/.hitpay/config.json` |
| `HITPAY_ENVIRONMENT` | `sandbox` or `production` |

### Global flags

Available on every command:

| Flag | Description |
| - | - |
| `--env <environment>` | One-shot environment override (e.g. `--env production`) |
| `--json` | Output raw JSON for piping to `jq`, scripts, or CI |
| `--help` | Show command help |
| `--version` | Print CLI version |

> [!WARNING]
>
> The CLI defaults to `sandbox`. Run `hitpay config set environment production` (or pass `--env production`) only when you are ready to move real money.

## Commands

| Category | Commands |
| - | - |
| **Account** | `login`, `logout`, `whoami`, `config set/get/list` |
| **Payment Requests** | `payment create`, `payment get`, `payment list`, `payment cancel` |
| **Charges** | `charge list`, `charge get`, `charge export` |
| **Refunds** | `refund` |
| **Customers** | `customer create/list/get/update/delete` |
| **Invoices** | `invoice create/list/delete` |
| **Subscriptions** | `plan create/list/get/delete`, `subscription create/list/get/cancel` |
| **Payouts** | `beneficiary create/list/delete`, `transfer estimate/create/list/get` |
| **QR Codes** | `qr create`, `methods` |
| **Webhooks (dev)** | `listen`, `trigger` |

Run `hitpay <command> --help` for full argument details on any command.

## Webhook development flow

The CLI's webhook tooling lets you build and test webhook handlers locally without ngrok setup or manual endpoint registration.

### Forward live events to localhost

```bash theme={"system"}
hitpay listen --forward-to http://localhost:3000/api/webhooks
```

This opens a secure tunnel, registers a temporary webhook endpoint with HitPay, and forwards every event to your local server. When you press `Ctrl+C`, the endpoint is cleaned up automatically.

### Simulate events without live traffic

```bash theme={"system"}
hitpay trigger charge.created
hitpay trigger --list   # show all supported event types
```

> [!NOTE]
>
> `trigger` posts a signed payload to whichever endpoint `listen` is currently forwarding, so you can exercise your handler's signature verification, idempotency, and event routing without waiting for a real payment.

## Usage Examples

**Create a payment request**

```bash theme={"system"}
hitpay payment create \
  --amount 49.90 \
  --currency SGD \
  --email customer@example.com \
  --reference INV-2026-001
```

Returns the checkout URL and payment request ID. Add `--json` to parse the result in a script.

**List & filter charges**

```bash theme={"system"}
hitpay charge list --status completed --limit 25 --json | jq '.data[].amount'
```

Combine with `--env production` to query the live account from a sandbox-configured machine without changing config.

**Test a webhook handler**

```bash theme={"system"}
# Terminal 1: tunnel + auto-register endpoint
hitpay listen --forward-to http://localhost:3000/api/webhooks

# Terminal 2: simulate an event
hitpay trigger charge.created
```

Inspect the forwarded payload in your local server logs. The handler receives a real signed payload identical to production.

**Generate a QR code**

```bash theme={"system"}
hitpay qr create --amount 100 --currency SGD --methods paynow
```

Renders the QR directly in your terminal. Scan with any PayNow-compatible banking app in Singapore.

## Prerequisites

1. **HitPay Account**: [create an account](https://dashboard.hit-pay.com) or use the [sandbox environment](https://dashboard.sandbox.hit-pay.com)
2. **API Key**: found in **Settings → Payment Gateway → API Keys**
3. **Node.js 18 or later**: check with `node --version`

## Which AI tool should I use?

HitPay offers four AI tooling options that can be used together.

| Tool | Use when you want to… |
| - | - |
| [**MCP Server**](/apis/guide/mcp-server) | Query your sales, payouts, and transactions from Claude, signed in with your HitPay account |
| [**Claude Code Plugin**](/apis/guide/claude-code-plugin) | Build payment integrations with Claude Code using live API access and auto-triggered skills |
| [**Agent Skills**](/apis/guide/ai-skills) | Generate HitPay integration code with Cursor, Copilot, Windsurf, or any AI assistant |
| **CLI** (this page) | Drive the API from your terminal, scripts, and CI pipelines, including webhook testing |

## Resources

> **[GitHub Repository](https://github.com/hit-pay/cli)**
>
> View source, report issues, and contribute

> **[HitPay MCP Server](/apis/guide/mcp-server)**
>
> Query your business data from an AI assistant

> **[Claude Code Plugin](/apis/guide/claude-code-plugin)**
>
> Live API access from inside Claude Code

> **[Agent Skills](/apis/guide/ai-skills)**
>
> Skills for Cursor, Copilot, and Windsurf

> **[API Reference](/apis/payment-request/create-request)**
>
> Full API documentation

> **[Webhook Events](/apis/guide/events)**
>
> Handle payment notifications

> **[Sandbox Guide](/apis/guide/sandbox)**
>
> Test your integration

## Feedback

Have suggestions or found an issue? [Open an issue](https://github.com/hit-pay/cli/issues) on GitHub.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.