npm package: @pingpong-js/cli
Description: Fast & Beautiful CLI API Testing Tool
Author: Devendra Pratap
Latest version: 1.1.2

# 🏓 @pingpong-js/cli

Fast, beautiful, and powerful command-line API testing tool.

[![npm version](https://img.shields.io/npm/v/@pingpong-js/cli.svg)](https://www.npmjs.com/package/@pingpong-js/cli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🚀 **Blazing fast** - Built with @pingpong-js/fetch and Undici (2-3x faster than native fetch), ~42KB gzipped
- 🔗 **Query parameters** - Built-in support for clean query param handling
- 📋 **Case-insensitive headers** - RFC 2616 compliant header access
- 🎨 **Beautiful output** - Colorful responses with syntax highlighting
- 📝 **Interactive mode** - Build requests with guided prompts
- 📁 **Collections** - Organize and reuse requests
- 🌍 **Environments** - Switch between dev/staging/prod with variables
- 🔗 **Request chaining** - Extract values from responses, use in next requests
- 🍪 **Cookie management** - Automatic cookie handling with persistent storage
- ✅ **Assertions** - Validate responses for CI/CD pipelines
- ⚡ **Load testing** - Performance testing with concurrent requests and detailed metrics
- 📤 **File uploads** - Multipart form data support
- 🔒 **Proxy support** - Route requests through HTTP proxies

## 📦 Installation

```bash
# Install globally
npm install -g @pingpong-js/cli

# Or use with npx (no install needed)
npx pingpong-cli send GET https://api.mockly.codes/users
```

## ⚡ Performance

- **Bundle Size**: ~42KB gzipped (optimized with minification)
- **Build Time**: Fast compilation with TypeScript
- **Runtime Speed**: Built on Undici for maximum performance
- **Memory Usage**: Efficient multipart/form-data handling

## 🚀 Quick Start

```bash
# Simple GET request
pingpong send GET https://api.mockly.codes/users

# POST with JSON
pingpong send POST https://api.mockly.codes/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"john@example.com"}'

# Interactive mode
pingpong request

# Load testing
pingpong load https://api.mockly.codes/health -n 100 -c 10
```

## 📖 Examples

Check out the [examples](./examples) directory for complete working examples of all features:

- **[Basic Requests](./examples/simple-get.sh)** - GET, POST, Headers
- **[Request Chaining](./examples/request-chaining.sh)** - Extract and reuse values
- **[Collections](./examples/collection-create.sh)** - Organize and manage requests
- **[Assertions](./examples/assertions-basic.sh)** - Validate responses
- **[File Operations](./examples/file-upload.sh)** - Upload files and send from files
- **[Load Testing](./examples/load-test-basic.sh)** - Performance testing
- **[Advanced Features](./examples/proxy-support.sh)** - Proxies, cookies, interactive mode
- **[CI/CD Integration](./examples/ci-cd-integration.sh)** - GitHub Actions workflow

See [examples/README.md](./examples/README.md) for complete example documentation.

## 📚 Commands

### `send` - Send HTTP Request

```bash
pingpong send <METHOD> <URL> [options]

Options:
  -H, --header <key:value>   Headers (repeatable)
  -d, --data <body>          Request body (JSON or @file)
  -f, --file <name=@path>    Upload files
  -t, --timeout <ms>         Request timeout
  -x, --proxy <url>          HTTP proxy
  -a, --assert <assertion>   Response assertions
  -e, --extract <var=path>   Extract variables
  -c, --concurrent <number>  Send N requests concurrently
  --no-redirect              Don't follow redirects
  --no-cookies               Disable cookies
  --no-save                  Don't save to history
  --show-headers             Display response headers (hidden by default)

Examples:
  pingpong send GET https://httpbin.org/get
  pingpong send POST https://api.mockly.codes/users -d @body.json
  pingpong send POST https://api.mockly.codes/upload -f "avatar=@photo.jpg"
  pingpong send GET https://api.mockly.codes/users --show-headers
```

### `collection` - Manage Collections

```bash
# Create collection
pingpong collection:create my-api --base-url https://api.mockly.codes

# Add requests with chaining
pingpong collection:add my-api login \
  -m POST -u /auth/login \
  -d '{"email":"user@example.com","password":"pass"}' \
  -e "token=$.token" \
  -a "status == 200"

pingpong collection:add my-api get-profile \
  -m GET -u /users/me \
  -H "Authorization: Bearer {{token}}" \
  -e "userId=$.id"

# Run collection
pingpong collection:run my-api -e dev

# Run from JSON file
pingpong collection:run collection.json --file

# Show response headers
pingpong collection:run my-api --show-headers
```

### `env` - Manage Environments

```bash
# Create environment
pingpong env:create dev
pingpong env:set dev BASE_URL https://pingpong.codes/
pingpong env:set dev API_KEY dev_key_123

# Use in requests
pingpong env:use dev
pingpong send GET "{{BASE_URL}}/users" -H "X-API-Key: {{API_KEY}}"
```

### `load` - Load Testing

```bash
# Simple load test
pingpong load https://api.mockly.codes/users -n 100 -c 10

# Duration-based test
pingpong load https://api.mockly.codes/health \
  --duration 60 \
  --rate 20 \
  -c 20

# Collection load test
pingpong collection:run my-api --load -n 50 -c 5
```

**Metrics Provided:**
- Latency: min, mean, median, p95, p99, max
- Throughput: requests/sec, bytes/sec
- Status code distribution
- Virtual user statistics

## 🔗 Request Chaining

Extract values from responses and use them in subsequent requests:

```bash
# Extract token from login
pingpong send POST https://api.mockly.codes/auth/login \
  -d '{"email":"user@example.com","password":"pass"}' \
  --extract "token=$.token"

# Use token in next request
pingpong send GET https://api.mockly.codes/users/me \
  -H "Authorization: Bearer {{token}}"
```

**JSONPath Syntax:**
- `$.property` - Root property
- `$.nested.value` - Nested property
- `$.array[0]` - Array element
- `$.items[*]` - All array items

## ✅ Assertions

Validate responses for CI/CD:

```bash
# Status and timing
pingpong send GET https://api.mockly.codes/health \
  -a "status == 200" \
  -a "time < 1000"

# Headers
pingpong send GET https://api.mockly.codes \
  -a "header.content-type == 'application/json'"

# JSON body
pingpong send GET https://api.mockly.codes/users/1 \
  -a "body.id == 1" \
  -a "body.email exists"
```

## 🍪 Cookie Management

```bash
# List cookies
pingpong cookies

# Clear cookies
pingpong cookies:clear [domain]

# Export/Import
pingpong cookies:export cookies.json
pingpong cookies:import cookies.json
```

## 🎯 Complete Example

```bash
# 1. Create collection
pingpong collection:create my-api --base-url https://api.mockly.codes

# 2. Add login (extracts token)
pingpong collection:add my-api login \
  -m POST -u /auth/login \
  -d '{"email":"user@example.com","password":"pass"}' \
  -e "token=$.token" \
  -a "status == 200"

# 3. Add profile request (uses token)
pingpong collection:add my-api get-profile \
  -m GET -u /users/me \
  -H "Authorization: Bearer {{token}}" \
  -e "userId=$.id"

# 4. Run entire flow
pingpong collection:run my-api -e dev

# 5. Load test the flow
pingpong collection:run my-api --load -n 50 -c 5

# 6. Export and share
pingpong collection:export my-api my-api.json
```

## 🔄 CI/CD Integration

```yaml
# .github/workflows/api-tests.yml
name: API Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      
      - name: Install PingPong CLI
        run: npm install -g @pingpong-js/cli
      
      - name: Run API tests
        run: |
          pingpong send GET ${{ secrets.API_URL }}/health \
            --assert "status == 200" \
            --assert "time < 2000" \
            --no-save
```

## 🆚 Why PingPong CLI?

| Feature | PingPong | curl | httpie | Postman CLI |
|---------|-----------|------|--------|-------------|
| Speed | ⚡⚡⚡ | ⚡⚡ | ⚡⚡ | ⚡⚡ |
| Beautiful output | ✅ | ❌ | ✅ | ✅ |
| Interactive mode | ✅ | ❌ | ❌ | ❌ |
| Collections | ✅ | ❌ | ❌ | ✅ |
| Load testing | ✅ | ❌ | ❌ | ⚠️ |
| Request chaining | ✅ | ❌ | ❌ | ✅ |
| Assertions | ✅ | ❌ | ❌ | ✅ |
| Free & Open Source | ✅ | ✅ | ✅ | ⚠️ Limited |

## 💡 Tips & Tricks

```bash
# Load body from file
pingpong send POST https://api.mockly.codes/data -d @body.json

# Multiple headers
pingpong send GET https://api.mockly.codes \
  -H "Accept: application/json" \
  -H "User-Agent: MyApp/1.0"

# Custom timeout
pingpong send GET https://slow-api.example.com --timeout 60000

# Don't save sensitive requests
pingpong send POST https://api.mockly.codes/auth --no-save

# Use proxy for debugging
pingpong send GET https://api.mockly.codes -x http://localhost:8888
```

## 🔧 Configuration

```bash
# View config
pingpong config

# Set timeout
pingpong config --set defaultTimeout=5000

# Set max history
pingpong config --set maxHistoryItems=200
```

**Storage Location:**
All data is stored in `~/.config/pingpong/`:
- `collections.json` - Request collections
- `environments.json` - Environment variables
- `history.json` - Request history
- `cookies.json` - Cookie storage
- `config.json` - CLI configuration

## 📖 More Resources

- **[Full Documentation](https://github.com/0xdps/pingpong-extension#-cli-tool)** - Complete CLI guide
- **[Browser Extension](https://github.com/0xdps/pingpong-extension)** - API testing in your browser
- **[@pingpong-js/fetch](https://www.npmjs.com/package/@pingpong-js/fetch)** - Universal HTTP client (query params, case-insensitive headers)
- **[@pingpong-js/core](https://www.npmjs.com/package/@pingpong-js/core)** - Core utilities (HTTP types, URL/header utilities)
- **[Changelog](https://github.com/0xdps/pingpong-extension/blob/trunk/CHANGELOG.md)** - Version history
- **[Contributing](https://github.com/0xdps/pingpong-extension/blob/trunk/CONTRIBUTING.md)** - Development guide

## 🐛 Issues & Support

- **Bug reports**: [GitHub Issues](https://github.com/0xdps/pingpong-extension/issues)
- **Questions**: [GitHub Discussions](https://github.com/0xdps/pingpong-extension/discussions)
- **Email**: dps.manit@gmail.com

## 📄 License

MIT License - see [LICENSE](https://github.com/0xdps/pingpong-extension/blob/trunk/LICENSE)

## 🙏 Credits

Built with:
- [undici](https://github.com/nodejs/undici) - Fast HTTP client
- [commander](https://github.com/tj/commander.js) - CLI framework
- [chalk](https://github.com/chalk/chalk) - Terminal colors
- [inquirer](https://github.com/SBoudrias/Inquirer.js) - Interactive prompts
- [ora](https://github.com/sindresorhus/ora) - Elegant spinners

---

**Made with ❤️ by [0xdps](https://0xdps.xyz)**

🏓 **PingPong CLI - Fast, beautiful API testing** 🚀