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

# CLI

> Official command-line tool for the PayBridgeNP payment gateway.

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install -g @paybridge-np/cli
  ```

  ```bash bun theme={null}
  bun install -g @paybridge-np/cli
  ```

  ```bash yarn theme={null}
  yarn global add @paybridge-np/cli
  ```
</CodeGroup>

After installing, both `paybridgenp` and `paybridge-np` are available as aliases.

```bash theme={null}
paybridgenp --version
```

***

## Authentication

### `paybridgenp login`

Authenticate with your API key. You can find your keys in the [dashboard](https://dashboard.paybridgenp.com) under **Settings → API Keys**.

```bash theme={null}
paybridgenp login
```

The CLI prompts for your key interactively. For CI/scripts, pass it directly:

```bash theme={null}
paybridgenp login --key sk_test_...
```

Or set the environment variable to skip login entirely:

```bash theme={null}
export PAYBRIDGENP_API_KEY=sk_test_...
```

The `PAYBRIDGENP_API_KEY` environment variable always takes priority over the saved config.

Config is stored at:

* **macOS/Linux:** `~/.config/paybridgenp/config.json`
* **Windows:** `%APPDATA%\paybridgenp\config.json`

The file is written with `0600` permissions - readable only by you.

***

### `paybridgenp status`

Show the current authentication state and API connection.

```bash theme={null}
paybridgenp status
```

```
  PayBridgeNP CLI

  Key           sk_test_abc1...
  Mode          sandbox
  API           https://api.paybridgenp.com
  Source        config file (~/.config/paybridgenp/config.json)
```

***

## Payments

### `paybridgenp payments list`

List recent payments in a table.

```bash theme={null}
paybridgenp payments list
paybridgenp payments list --limit 50
paybridgenp payments list --watch        # live-refresh every 5s
```

| Flag          | Default | Description                     |
| ------------- | ------- | ------------------------------- |
| `--limit <n>` | `20`    | Number of results (max 100)     |
| `--watch`     | off     | Poll and redraw every 5 seconds |

***

### `paybridgenp payments get <id>`

Fetch a single payment with full detail.

```bash theme={null}
paybridgenp payments get pay_abc123
```

```
  Payment pay_abc123

  Amount        NPR 500.00
  Status        success
  Provider      esewa
  Provider ref  1234567890
  Session       cs_abc123
  Created       16 Apr 2026, 12:34 NPT
  Metadata      { "order_id": "123" }
```

***

## Webhooks

### `paybridgenp webhooks list`

List all registered webhook endpoints for the current project.

```bash theme={null}
paybridgenp webhooks list
```

***

### `paybridgenp webhooks listen`

Start a local HTTP server and expose it via an [ngrok](https://ngrok.com) tunnel. Use this during development to receive real webhook events on your machine.

```bash theme={null}
paybridgenp webhooks listen
paybridgenp webhooks listen --port 4242 --secret whsec_...
```

```
  Webhook listener ready

  Local    http://localhost:4242
  Public   https://abc123.ngrok-free.app

  Add this URL to your PayBridgeNP dashboard → Webhooks → Add endpoint
  Listening for events... (Ctrl+C to stop)

  [12:34:56] payment.succeeded
             id:           pay_abc123
             amount:       NPR 100.00
             provider:     esewa
             provider_ref: TX123456
```

| Flag                   | Default | Description                                  |
| ---------------------- | ------- | -------------------------------------------- |
| `--port <n>`           | `4242`  | Local port to listen on                      |
| `--secret <whsec_...>` | none    | Verify incoming HMAC signatures              |
| `--forward <url>`      | none    | Forward verified events to another local URL |

<Note>
  ngrok must be installed. Install it with `brew install ngrok` or from [ngrok.com](https://ngrok.com/download).
</Note>

***

### `paybridgenp webhooks test <url>`

Send a fake signed event to any URL to test your webhook handler.

```bash theme={null}
paybridgenp webhooks test https://yoursite.com/webhooks/paybridgenp
paybridgenp webhooks test http://localhost:4242 --secret whsec_... --event payment.failed
```

| Flag                   | Default             | Description                    |
| ---------------------- | ------------------- | ------------------------------ |
| `--secret <whsec_...>` | none                | Sign the payload (recommended) |
| `--event <type>`       | `payment.succeeded` | Event type to send             |
| `--amount <paisa>`     | `10000`             | Amount in the payload          |

**Supported event types:**

| Event               | Description            |
| ------------------- | ---------------------- |
| `payment.succeeded` | Successful payment     |
| `payment.failed`    | Failed payment attempt |
| `payment.cancelled` | Customer cancelled     |
| `payment.refunded`  | Refund issued          |

***

## Testing

### `paybridgenp test`

Create a real sandbox checkout session and open it in the browser. Complete a test payment end-to-end without writing any code.

```bash theme={null}
paybridgenp test
paybridgenp test --amount 50000    # NPR 500.00
paybridgenp test --no-open         # print URL only
```

```
  Checkout session created

  Session ID    cs_test_abc123
  Amount        NPR 10.00
  URL           https://checkout.paybridgenp.com/checkout/cs_test_abc123

  Sandbox test credentials

  eSewa         merchant code EPAYTEST
  Khalti        phone 9800000001 · MPIN 1111 · OTP 987654
```

| Flag               | Default | Description                           |
| ------------------ | ------- | ------------------------------------- |
| `--amount <paisa>` | `1000`  | Amount in paisa (NPR 10.00)           |
| `--no-open`        | off     | Print URL without opening the browser |

<Warning>
  If you run `paybridgenp test` with a live key (`sk_live_...`), the CLI will warn you and require explicit confirmation before creating a real checkout.
</Warning>

***

## Scaffolding

### `paybridgenp init`

Interactively scaffold a starter project with working checkout and webhook routes.

```bash theme={null}
paybridgenp init

# Non-interactive (for CI or scripts):
paybridgenp init --name my-shop --framework nextjs
```

| Flag                      | Description                 |
| ------------------------- | --------------------------- |
| `--name <name>`           | Project directory name      |
| `--framework <framework>` | `nextjs`, `node`, or `bare` |

**What gets created:**

<AccordionGroup>
  <Accordion title="Next.js (App Router)">
    ```
    my-shop/
      app/
        api/
          checkout/route.ts   ← POST /api/checkout
          webhook/route.ts    ← POST /api/webhook
      .env                    ← pre-filled with your API key
      .env.example
      .gitignore              ← .env added automatically
      package.json
    ```
  </Accordion>

  <Accordion title="Node.js">
    ```
    my-shop/
      index.ts                ← HTTP server with /checkout + /webhook routes
      .env
      .env.example
      .gitignore
      package.json
    ```
  </Accordion>

  <Accordion title="Bare TypeScript">
    ```
    my-shop/
      index.ts                ← minimal SDK usage example
      .env
      .env.example
      .gitignore
      package.json
    ```
  </Accordion>
</AccordionGroup>

***

## Updates

### `paybridgenp update`

Check if a newer version is available on npm.

```bash theme={null}
paybridgenp update
```

```
  Checking for updates...

  Current       v1.0.3
  Latest        v1.0.3

  ✓ You're up to date

  $ npm install -g @paybridge-np/cli@latest
```

***

## Global flags

These flags work with every command:

| Flag        | Description                                                |
| ----------- | ---------------------------------------------------------- |
| `--debug`   | Print full error stack traces instead of friendly messages |
| `--version` | Print the CLI version                                      |
| `--help`    | Show help for any command                                  |

```bash theme={null}
paybridgenp payments list --debug
paybridgenp webhooks listen --debug
```

***

## Configuration reference

| Source                        | Priority    | How to set                          |
| ----------------------------- | ----------- | ----------------------------------- |
| `PAYBRIDGENP_API_KEY` env var | 1 (highest) | `export PAYBRIDGENP_API_KEY=sk_...` |
| Config file                   | 2           | Set by `paybridgenp login`          |