🏓 @pingpong-js/cli

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


✨ 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 directory for complete working examples of all features:

- Basic Requests - GET, POST, Headers
- Request Chaining - Extract and reuse values
- Collections - Organize and manage requests
- Assertions - Validate responses
- File Operations - Upload files and send from files
- Load Testing - Performance testing
- Advanced Features - Proxies, cookies, interactive mode
- CI/CD Integration - GitHub Actions workflow

See examples/README.md for complete example documentation.

📚 Commands

$3

`bash
pingpong send [options]

Options:
-H, --header Headers (repeatable)
-d, --data Request body (JSON or @file)
-f, --file Upload files
-t, --timeout Request timeout
-x, --proxy HTTP proxy
-a, --assert Response assertions
-e, --extract Extract variables
--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
`

$3

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

$3

`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}}"
`

$3

`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 - Complete CLI guide
- Browser Extension - API testing in your browser
- @pingpong-js/fetch - Universal HTTP client (query params, case-insensitive headers)
- @pingpong-js/core - Core utilities (HTTP types, URL/header utilities)
- Changelog - Version history
- Contributing - Development guide

🐛 Issues & Support

- Bug reports: GitHub Issues
- Questions: GitHub Discussions
- Email: dps.manit@gmail.com

📄 License

MIT License - see LICENSE

🙏 Credits

Built with:
- undici - Fast HTTP client
- commander - CLI framework
- chalk - Terminal colors
- inquirer - Interactive prompts
- ora - Elegant spinners

---

Made with ❤️ by 0xdps

🏓 PingPong CLI - Fast, beautiful API testing 🚀