npm package: @pingpay/cli
Description: Agent-native crypto payments from the terminal
Latest version: 0.1.3

# ping-cli

CLI for [Ping Checkout](https://pingpay.io) — crypto payments for AI agents and developers.

JSON-first output, env var overrides, and meaningful exit codes make it native to automation pipelines and AI agent workflows.

## Install

```bash
# npm
npm install -g @pingpay/cli

# bun
bun install -g @pingpay/cli

# or run directly
npx @pingpay/cli status
```

## Quick Start

```bash
# 1. Check the API is reachable
ping-cli status

# 2. Authenticate with your API key (get one from the Ping dashboard)
ping-cli init --api-key <your-key>

# 3. Verify auth
ping-cli whoami

# 4. Create a checkout session
ping-cli checkout create --amount 1000000 --asset-symbol USDC --asset-chain near

# 5. Create a payment link
ping-cli link create --name "My Store" --recipient-address "you.near" --asset-symbol USDC --asset-chain near
```

## Commands

### `ping-cli init --api-key <key>`

Store your API key in `~/.ping/config.json`. Validates the key against the API before saving.

```bash
ping-cli init --api-key sk_live_abc123...
```

### `ping-cli status`

Health check — no auth required. Returns `{ "status": "ok", "timestamp": "..." }`.

```bash
ping-cli status
# Pipe to jq:
ping-cli status | jq .status
```

### `ping-cli whoami`

Show current authentication info and payment count.

```bash
ping-cli whoami
```

### `ping-cli version`

Print the CLI version.

### `ping-cli checkout create`

Create a checkout session. Requires auth.

```bash
ping-cli checkout create \
  --amount 1000000 \
  --asset-symbol USDC \
  --asset-chain near \
  --success-url "https://example.com/success" \
  --cancel-url "https://example.com/cancel" \
  --metadata '{"orderId": "123"}'
```

**Flags:**
| Flag | Required | Description |
|------|----------|-------------|
| `--amount` | Yes | Amount in smallest units (e.g. `1000000` = 1 USDC) |
| `--asset-symbol` | Yes | Token symbol: `USDC`, `USDT`, `wnear`, etc. |
| `--asset-chain` | Yes | Blockchain: `near`, `eth`, etc. |
| `--success-url` | No | Redirect URL on payment success |
| `--cancel-url` | No | Redirect URL on cancel |
| `--metadata` | No | JSON string of arbitrary metadata |

### `ping-cli checkout get <session-id>`

Get a checkout session by ID. No auth required.

```bash
ping-cli checkout get cs_abc123
```

### `ping-cli payment get <payment-id>`

Get payment details. Requires auth.

```bash
ping-cli payment get pay_abc123
```

### `ping-cli payment list`

List payments with optional filters. Requires auth.

```bash
ping-cli payment list
ping-cli payment list --status SUCCESS --limit 10
ping-cli payment list --offset 50 --limit 25
```

**Flags:**
| Flag | Default | Description |
|------|---------|-------------|
| `--limit` | 50 | Max results (1-100) |
| `--offset` | 0 | Pagination offset |
| `--status` | — | Filter: `CREATED`, `PENDING`, `PROCESSING`, `SUCCESS`, `FAILED` |

### `ping-cli payment wait <payment-id>`

Poll a payment until it reaches a terminal state (`SUCCESS`, `FAILED`, `REFUNDED`). Requires auth.

```bash
# Wait up to 5 minutes (default)
ping-cli payment wait pay_abc123

# Custom timeout
ping-cli payment wait pay_abc123 --timeout 60
```

### `ping-cli link create`

Create a payment link. Requires auth.

```bash
# Open amount — donors choose how much
ping-cli link create \
  --name "My Tip Jar" \
  --recipient-address "you.near" \
  --asset-symbol USDC \
  --asset-chain near

# Fixed amount
ping-cli link create \
  --name "Conference Ticket" \
  --description "Entry pass for the event" \
  --recipient-address "you.near" \
  --asset-symbol USDC \
  --asset-chain near \
  --amount-type fixed \
  --fixed-amount 50000000
```

**Flags:**
| Flag | Required | Description |
|------|----------|-------------|
| `--name` | Yes | Link name (1-100 chars) |
| `--recipient-address` | Yes | Wallet address to receive funds |
| `--asset-symbol` | Yes | Token symbol: `USDC`, `USDT`, `wnear`, etc. |
| `--asset-chain` | Yes | Blockchain: `near`, `eth`, etc. |
| `--amount-type` | No | `open` (default) or `fixed` |
| `--fixed-amount` | No | Amount in smallest units (required if `fixed`) |
| `--description` | No | Link description (max 500 chars) |

### `ping-cli link list`

List your payment links. Requires auth.

```bash
ping-cli link list
ping-cli link list --active true --limit 10
```

### `ping-cli link get <link-id>`

Get a payment link by ID. Requires auth.

```bash
ping-cli link get pl_abc123
```

### `ping-cli link delete <link-id>`

Delete a payment link. Requires auth.

```bash
ping-cli link delete pl_abc123
```

## Configuration

### Config file

`ping-cli init` saves to `~/.ping/config.json`:

```json
{
  "apiKey": "sk_live_...",
  "apiUrl": "https://pay.pingpay.io/api/rpc",
  "env": "production"
}
```

### Environment variables

Override config file values:

| Variable | Description |
|----------|-------------|
| `PING_API_KEY` | API key |
| `PING_API_URL` | API endpoint URL |
| `PING_ENV` | `production` or `development` |
| `PING_OUTPUT` | `json` (default) or `pretty` |

### Priority

Flags > Environment variables > Config file > Defaults

### Global flags

Every command accepts these flags:

| Flag | Description |
|------|-------------|
| `--api-key` | Override API key for this call |
| `--api-url` | Override API URL for this call |
| `--output` | `json` (default) or `pretty` |

## Output

**JSON mode** (default): Machine-readable JSON to stdout. Errors to stderr.

```bash
ping-cli status
# {"status":"ok","timestamp":"2025-01-01T00:00:00Z"}
```

**Pretty mode**: Human-readable colored output.

```bash
ping-cli status --output pretty
```

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | User error (bad input, auth failure, not found) |
| `2` | Server error (API down, network failure) |

### `ping-cli wallet create --email <email>`

Create an [AgentWallet](https://agentwallet.ai) — a crypto wallet your agent can use to send payments. A 6-digit OTP is sent to your email for verification.

```bash
# Interactive — prompts for OTP
ping-cli wallet create --email you@example.com

# Non-interactive — pass OTP directly
ping-cli wallet create --email you@example.com --otp 123456
```

Credentials are saved to `~/.ping/config.json`. After creation, fund your wallet by sending USDC on Base to the returned `evmAddress`.

### `ping-cli wallet connect`

Connect an existing AgentWallet. Auto-detects credentials from `~/.agentwallet/config.json` if available, or pass them manually:

```bash
ping-cli wallet connect --token mf_... --username agent123 --evm-address 0x...
```

### `ping-cli wallet balance`

Check wallet balances across chains.

```bash
ping-cli wallet balance
```

### `ping-cli pay --session-id <id>`

Pay a checkout session in one command. Prepares the payment, sends funds from your connected wallet, and returns the transaction hash.

> **Currently supports USDC on Base only.**

```bash
ping-cli pay --session-id cs_abc123
```

**Flags:**
| Flag | Required | Default | Description |
|------|----------|---------|-------------|
| `--session-id` | Yes | — | Checkout session ID to pay |
| `--asset-symbol` | No | `USDC` | Asset to pay with |
| `--asset-chain` | No | `base` | Chain to pay on |

## AI Agent Usage

ping-cli is designed for AI agents. Key patterns:

```bash
# Create a checkout and extract the session URL
SESSION_URL=$(ping-cli checkout create \
  --amount 1000000 \
  --asset-symbol USDC \
  --asset-chain base | jq -r '.sessionUrl')

# Pay a checkout session
ping-cli pay --session-id cs_abc123

# Create a payment link and get the link URL
LINK_URL=$(ping-cli link create \
  --name "Payment" \
  --recipient-address "0xmerchant" \
  --asset-symbol USDC \
  --asset-chain base | jq -r '.linkUrl')

# Wait for payment completion in a script
ping-cli payment wait pay_abc123 --timeout 120
if [ $? -eq 0 ]; then
  echo "Payment succeeded"
fi
```

## Development

```bash
# Run locally
bun run src/index.ts status

# Run tests
bun run test

# Type check
bun run typecheck

# Build for npm
bun run build

# Build standalone binary
bun run build:binary
```