> ## 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

<CardGroup cols={3}>
  <Card title="Account & Payments" icon="wallet">
    Manage payment requests, charges, refunds, customers, invoices, subscriptions, beneficiaries, and transfers with a consistent `hitpay <resource> <action>` syntax.
  </Card>

  <Card title="Webhook Testing" icon="webhook">
    `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.
  </Card>

  <Card title="QR Codes in Terminal" icon="qrcode">
    `hitpay qr create` renders scannable QR codes directly in your terminal for PayNow, QRIS, PromptPay, GCash, DuitNow, and 50+ other methods across Southeast Asia.
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="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**.
  </Step>

  <Step title="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**.
  </Step>

  <Step title="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
    ```
  </Step>
</Steps>

<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
  ```
</Warning>

## 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.
</Warning>

## 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
```

<Info>
  `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.
</Info>

## Usage Examples

<Tabs>
  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>

  <Tab title="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.
  </Tab>
</Tabs>

## 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

<CardGroup cols={2}>
  <Card title="GitHub Repository" icon="github" href="https://github.com/hit-pay/cli">
    View source, report issues, and contribute
  </Card>

  <Card title="HitPay MCP Server" icon="plug" href="/apis/guide/mcp-server">
    Query your business data from an AI assistant
  </Card>

  <Card title="Claude Code Plugin" icon="microchip-ai" href="/apis/guide/claude-code-plugin">
    Live API access from inside Claude Code
  </Card>

  <Card title="Agent Skills" icon="wand-magic-sparkles" href="/apis/guide/ai-skills">
    Skills for Cursor, Copilot, and Windsurf
  </Card>

  <Card title="API Reference" icon="code" href="/apis/payment-request/create-request">
    Full API documentation
  </Card>

  <Card title="Webhook Events" icon="bell" href="/apis/guide/events">
    Handle payment notifications
  </Card>

  <Card title="Sandbox Guide" icon="flask" href="/apis/guide/sandbox">
    Test your integration
  </Card>
</CardGroup>

## Feedback

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