> For the complete documentation index, see [llms.txt](https://pingpay.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pingpay.gitbook.io/docs/pingpay-cli/overview.md).

# Overview

## Overview

Ping CLI is agent-native crypto payment infrastructure for the terminal. It lets AI agents and developers create checkout sessions, generate payment links, manage wallets, and execute payments - all without a browser.

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

### Why Ping CLI?

Traditional payment APIs assume a human behind a browser. Ping CLI is built for a world where AI agents act on behalf of users - paying invoices, accepting payments, and settling between each other autonomously.

* **JSON-first output:** every command returns structured JSON to stdout, ready for agents to parse
* **Zero-browser auth:** API key stored locally, no OAuth redirects
* **Composable:** pipe outputs between commands, chain workflows
* **Idempotent:** safe to retry, same input produces same result
* **Meaningful exit codes:** `0` success, `1` user error, `2` server error

> **Note:** Wallet payments (`ping-cli pay`) currently support **USDC on Base** only. Checkout sessions and payment links support additional assets and chains.

### What You Can Do

| Capability             | Commands                                                                           | Description                                                        |
| ---------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Setup**              | `init`, `status`, `whoami`                                                         | Authenticate and verify your connection                            |
| **Wallet**             | `wallet create`, `wallet connect`, `wallet balance`                                | Create or connect an AgentWallet to hold and send funds            |
| **Checkout**           | `checkout create`, `checkout get`                                                  | Create payment sessions for merchants or agents to accept payments |
| **Pay**                | `pay`                                                                              | Execute a payment against a checkout session in one command        |
| **Payment Management** | `payment prepare`, `payment get`, `payment list`, `payment status`, `payment wait` | Fine-grained control over payment lifecycle                        |
| **Payment Links**      | `link create`, `link get`, `link list`, `link delete`                              | Reusable or one-off shareable payment URLs                         |

### Quick Start

```bash
# 1. Install
npm install -g @pingpay/cli

# 2. Authenticate with your API key
ping-cli init --api-key sk_live_your_key

# 3. Create an agent wallet
ping-cli wallet create --email you@example.com

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

# 5. Pay the checkout
ping-cli pay --session-id cs_abc123
```

### How It Works

```
+--------------+    checkout create    +--------------+
|  Merchant /  | ------------------>>  |   Ping API   |
|  Agent A     | <<------------------  |              |
+--------------+    session ID         +------+-------+
                                              |
+--------------+    pay --session-id   +------v-------+
|  Payer /     | ------------------>>  |   Ping API   |
|  Agent B     | <<------------------  | + on-chain   |
+--------------+    tx hash            +--------------+
```

One agent creates a checkout. Another agent (or the same one) pays it. The CLI handles deposit address resolution, asset routing, and on-chain transfer.

### Configuration

The CLI stores config at `~/.ping/config.json`. You can override any value with environment variables or flags.

| Priority    | Source                                                 |
| ----------- | ------------------------------------------------------ |
| 1 (highest) | CLI flags (`--api-key`, `--api-url`)                   |
| 2           | Environment variables (`PING_API_KEY`, `PING_API_URL`) |
| 3           | Config file (`~/.ping/config.json`)                    |
| 4 (lowest)  | Defaults                                               |