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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://pingpay.gitbook.io/docs/pingpay-cli/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.