> 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/getting-started.md).

# Getting Started

### Installation

Install the CLI globally using your preferred package manager:

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

# bun
bun install -g @pingpay/cli

# or run directly without installing
npx @pingpay/cli <command>
```

After installation, the `ping-cli` command is available globally.

### Authentication

#### Initialize with your API key

```bash
ping-cli init --api-key sk_live_your_key
```

This validates the key against the Ping API and stores it at `~/.ping/config.json`. You only need to do this once.

**Output:**

```json
{
  "success": true,
  "keyPreview": "sk_live_abc...xyz",
  "configPath": "/Users/you/.ping/config.json"
}
```

#### Verify your connection

```bash
ping-cli whoami
```

Returns your authentication status, key preview, environment, and total payment count.

**Output:**

```json
{
  "authenticated": true,
  "keyPreview": "sk_live_abc...xyz",
  "env": "production",
  "apiUrl": "https://app.pingpay.io/api/rpc",
  "totalPayments": 42
}
```

#### Check API status

No authentication required - useful for verifying that the Ping API is reachable.

```bash
ping-cli status
```

**Output:**

```json
{
  "status": "ok",
  "timestamp": "2025-06-01T12:00:00.000Z"
}
```

#### Check CLI version

```bash
ping-cli version
```

```
ping-cli v0.1.2
```

### Configuration Reference

#### Config file

Stored at `~/.ping/config.json`:

```json
{
  "apiKey": "sk_live_...",
  "apiUrl": "https://pay.pingpay.io/api/rpc",
  "env": "production",
  "output": "json",
  "wallet": {
    "token": "mf_...",
    "username": "agent123",
    "evmAddress": "0x..."
  }
}
```

#### Environment variables

Override any config value with environment variables:

| Variable       | Description                   | Default                          |
| -------------- | ----------------------------- | -------------------------------- |
| `PING_API_KEY` | API key                       | from config file                 |
| `PING_API_URL` | API endpoint                  | `https://app.pingpay.io/api/rpc` |
| `PING_ENV`     | `production` or `development` | `production`                     |
| `PING_OUTPUT`  | `json` or `pretty`            | `json`                           |

#### Global flags

Available on every command:

| Flag                    | Description                    |
| ----------------------- | ------------------------------ |
| `--api-key <key>`       | Override API key for this call |
| `--api-url <url>`       | Override API URL for this call |
| `--output json\|pretty` | Output format                  |

#### Priority order

Flags > Environment variables > Config file > Defaults

### Exit Codes

| Code | Meaning      | Example                                     |
| ---- | ------------ | ------------------------------------------- |
| `0`  | Success      | Command completed successfully              |
| `1`  | User error   | Bad input, missing auth, resource not found |
| `2`  | Server error | API down, network failure                   |

Agents can use exit codes to determine whether to retry or surface an error.