# ReqNinja
[](https://badge.fury.io/py/reqninja)
[](https://pypi.org/project/reqninja/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/vishal-ravi/reqninja/actions)
[](https://codecov.io/gh/vishal-ravi/reqninja)
ReqNinja is a Python package and CLI tool for API testing, automation, and debugging — blending the simplicity of curl with the power and flexibility of Python's requests.
## 🚀 Features
- **Retries & Backoff**: Automatic retry logic for flaky APIs with customizable policies
- **Fast Timing**: Instantly see how long each request takes
- **Pretty Output**: Syntax-highlighted JSON straight in your terminal
- **Authentication**: Bearer tokens, Basic Auth, OAuth2, and API keys via config
- **Config Profiles**: Quickly switch environments or base URLs
- **Response Saving**: Export results to .json or .txt files
- **Multiple Output Modes**: Raw, pretty JSON, tabular view, show headers
- **Powerful CLI**: Run API calls with a simple command, no Python required
- **Debug Mode**: Print full request/response details with timing breakdowns
- **Productivity Boost**: Pipe support, save/run commands, batch mode
- **Extensible**: Plugin system for custom output or request logic
## 📦 Installation
### From PyPI (recommended)
```bash
pip install reqninja
```
### From Source
```bash
git clone https://github.com/vishal-ravi/reqninja.git
cd reqninja
pip install -e .
```
### Development Installation
```bash
git clone https://github.com/vishal-ravi/reqninja.git
cd reqninja
python setup_dev.py
```
## 🖥️ Quickstart: CLI Mode
### GET Request with Pretty Output
```bash
reqninja http get https://jsonplaceholder.typicode.com/posts/1
```
### POST JSON with Custom Headers
```bash
reqninja http post https://httpbin.org/post \
-j '{"name":"Vishal"}' \
-H "Content-Type: application/json"
```
### Show Raw Output
```bash
reqninja http get https://api.example.com/data --raw
```
### Save Response
```bash
reqninja http get https://api.example.com/users --save results.json
```
### Switch Profile
```bash
reqninja http get https://api.example.com/users --profile prod
```
### View Timing and Debug Info
```bash
reqninja http get https://api.example.com/users --debug
```
## 💻 Quickstart: Python Library
```python
from reqninja import get, post
response = get("https://jsonplaceholder.typicode.com/posts/1", retries=3)
print(response.json()) # Pretty printed automatically
```
## 🛠 Config Example (~/.reqninja/config.yml)
```yaml
default_retries: 3
default_headers:
Content-Type: application/json
profiles:
prod:
base_url: https://api.myapp.com
headers:
Authorization: Bearer ${TOKEN}
staging:
base_url: https://staging.api.myapp.com
retry_policy:
total: 5
status_forcelist: [429, 500, 502, 503, 504]
backoff_factor: 0.5
```
## 🔒 Authentication Made Simple
Pass tokens and credentials via CLI:
- `--auth bearer <TOKEN>`
- `--auth basic user:pass`
Or set them in your config file under the desired profile.
## 🏆 Productivity Shortcuts
- **Pipe**: `cat payload.json | reqninja http POST https://api.com/data`
- **Save a Command**: `reqninja save getUser "GET /users/1"`
- **Run Saved Command**: `reqninja run getUser`
- **Batch Mode**: Send a list of API calls from a file
## 🐞 Debugging
```bash
reqninja http POST /login --debug
```
Prints the full request, headers, body, and a timing breakdown for deeper inspection.
## 📝 Roadmap
- 🔑 Plugin system for custom output/auth logic
- 🎨 Templated payloads for batch/bulk requests
- 💡 Open response in browser (--open)
- 📁 Advanced response export filters
## 🙌 Why Use ReqNinja?
A single, modern tool for both quick API experiments and robust automation — with the polish, safety, and visibility pro devs expect.
## ⚠️ CLI Common Mistakes
### Use `http` for both HTTP and HTTPS
**Wrong:** `reqninja https get https://api.example.com`
**Correct:** `reqninja http get https://api.example.com`
### Use lowercase methods
**Wrong:** `reqninja http GET https://api.example.com`
**Correct:** `reqninja http get https://api.example.com`
ReqNinja provides helpful error messages to guide you to the correct syntax!
## 📚 Documentation
For complete documentation, visit [reqninja.readthedocs.io](https://reqninja.readthedocs.io)
Also see [CLI_USAGE_GUIDE.md](CLI_USAGE_GUIDE.md) for detailed CLI usage examples.
## 🤝 Contributing
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "reqninja",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "api, http, requests, testing, cli, automation, debugging, ninja, reqninja",
"author": null,
"author_email": "vishal-ravi <dev.vishalravi@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/2b/e4/cc98cbb98ed36ba1e91f42e4934e3c692be2c04d1c250b63963d6df327e4/reqninja-1.2.0.tar.gz",
"platform": null,
"description": "# ReqNinja\n\n[](https://badge.fury.io/py/reqninja)\n[](https://pypi.org/project/reqninja/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/vishal-ravi/reqninja/actions)\n[](https://codecov.io/gh/vishal-ravi/reqninja)\n\nReqNinja is a Python package and CLI tool for API testing, automation, and debugging \u2014 blending the simplicity of curl with the power and flexibility of Python's requests.\n\n## \ud83d\ude80 Features\n\n- **Retries & Backoff**: Automatic retry logic for flaky APIs with customizable policies\n- **Fast Timing**: Instantly see how long each request takes\n- **Pretty Output**: Syntax-highlighted JSON straight in your terminal\n- **Authentication**: Bearer tokens, Basic Auth, OAuth2, and API keys via config\n- **Config Profiles**: Quickly switch environments or base URLs\n- **Response Saving**: Export results to .json or .txt files\n- **Multiple Output Modes**: Raw, pretty JSON, tabular view, show headers\n- **Powerful CLI**: Run API calls with a simple command, no Python required\n- **Debug Mode**: Print full request/response details with timing breakdowns\n- **Productivity Boost**: Pipe support, save/run commands, batch mode\n- **Extensible**: Plugin system for custom output or request logic\n\n## \ud83d\udce6 Installation\n\n### From PyPI (recommended)\n```bash\npip install reqninja\n```\n\n### From Source\n```bash\ngit clone https://github.com/vishal-ravi/reqninja.git\ncd reqninja\npip install -e .\n```\n\n### Development Installation\n```bash\ngit clone https://github.com/vishal-ravi/reqninja.git\ncd reqninja\npython setup_dev.py\n```\n\n## \ud83d\udda5\ufe0f Quickstart: CLI Mode\n\n### GET Request with Pretty Output\n\n```bash\nreqninja http get https://jsonplaceholder.typicode.com/posts/1\n```\n\n### POST JSON with Custom Headers\n\n```bash\nreqninja http post https://httpbin.org/post \\\n -j '{\"name\":\"Vishal\"}' \\\n -H \"Content-Type: application/json\"\n```\n\n### Show Raw Output\n\n```bash\nreqninja http get https://api.example.com/data --raw\n```\n\n### Save Response\n\n```bash\nreqninja http get https://api.example.com/users --save results.json\n```\n\n### Switch Profile\n\n```bash\nreqninja http get https://api.example.com/users --profile prod\n```\n\n### View Timing and Debug Info\n\n```bash\nreqninja http get https://api.example.com/users --debug\n```\n\n## \ud83d\udcbb Quickstart: Python Library\n\n```python\nfrom reqninja import get, post\n\nresponse = get(\"https://jsonplaceholder.typicode.com/posts/1\", retries=3)\nprint(response.json()) # Pretty printed automatically\n```\n\n## \ud83d\udee0 Config Example (~/.reqninja/config.yml)\n\n```yaml\ndefault_retries: 3\ndefault_headers:\n Content-Type: application/json\nprofiles:\n prod:\n base_url: https://api.myapp.com\n headers:\n Authorization: Bearer ${TOKEN}\n staging:\n base_url: https://staging.api.myapp.com\nretry_policy:\n total: 5\n status_forcelist: [429, 500, 502, 503, 504]\n backoff_factor: 0.5\n```\n\n## \ud83d\udd12 Authentication Made Simple\n\nPass tokens and credentials via CLI:\n\n- `--auth bearer <TOKEN>`\n- `--auth basic user:pass`\n\nOr set them in your config file under the desired profile.\n\n## \ud83c\udfc6 Productivity Shortcuts\n\n- **Pipe**: `cat payload.json | reqninja http POST https://api.com/data`\n- **Save a Command**: `reqninja save getUser \"GET /users/1\"`\n- **Run Saved Command**: `reqninja run getUser`\n- **Batch Mode**: Send a list of API calls from a file\n\n## \ud83d\udc1e Debugging\n\n```bash\nreqninja http POST /login --debug\n```\n\nPrints the full request, headers, body, and a timing breakdown for deeper inspection.\n\n## \ud83d\udcdd Roadmap\n\n- \ud83d\udd11 Plugin system for custom output/auth logic\n- \ud83c\udfa8 Templated payloads for batch/bulk requests\n- \ud83d\udca1 Open response in browser (--open)\n- \ud83d\udcc1 Advanced response export filters\n\n## \ud83d\ude4c Why Use ReqNinja?\n\nA single, modern tool for both quick API experiments and robust automation \u2014 with the polish, safety, and visibility pro devs expect.\n\n## \u26a0\ufe0f CLI Common Mistakes\n\n### Use `http` for both HTTP and HTTPS\n**Wrong:** `reqninja https get https://api.example.com` \n**Correct:** `reqninja http get https://api.example.com`\n\n### Use lowercase methods\n**Wrong:** `reqninja http GET https://api.example.com` \n**Correct:** `reqninja http get https://api.example.com`\n\nReqNinja provides helpful error messages to guide you to the correct syntax!\n\n## \ud83d\udcda Documentation\n\nFor complete documentation, visit [reqninja.readthedocs.io](https://reqninja.readthedocs.io)\n\nAlso see [CLI_USAGE_GUIDE.md](CLI_USAGE_GUIDE.md) for detailed CLI usage examples.\n\n## \ud83e\udd1d Contributing\n\nContributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "ReqNinja - A Python package and CLI tool for API testing, automation, and debugging",
"version": "1.2.0",
"project_urls": {
"Documentation": "https://reqninja.readthedocs.io",
"Homepage": "https://github.com/vishal-ravi/reqninja",
"Issues": "https://github.com/vishal-ravi/reqninja/issues",
"Repository": "https://github.com/vishal-ravi/reqninja.git"
},
"split_keywords": [
"api",
" http",
" requests",
" testing",
" cli",
" automation",
" debugging",
" ninja",
" reqninja"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "71eadfd16660730cb0a5929fe31ef7c9aefb8c29333f4fc4987362dd7ed52690",
"md5": "b7f56264957a7ddabd51284c4a30c0b8",
"sha256": "5610635bd39cd7c6c3d4f4f8d99b70f6d1620559e6b9fa1f5c691ff42d8bb5f5"
},
"downloads": -1,
"filename": "reqninja-1.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7f56264957a7ddabd51284c4a30c0b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 16489,
"upload_time": "2025-08-10T10:43:30",
"upload_time_iso_8601": "2025-08-10T10:43:30.836399Z",
"url": "https://files.pythonhosted.org/packages/71/ea/dfd16660730cb0a5929fe31ef7c9aefb8c29333f4fc4987362dd7ed52690/reqninja-1.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "2be4cc98cbb98ed36ba1e91f42e4934e3c692be2c04d1c250b63963d6df327e4",
"md5": "7d6a2a45afb10a069c298e564f11f2f8",
"sha256": "e99a602b344c2663a94b1a5f2c85996fbac08ecac39280ba44bdd05770306590"
},
"downloads": -1,
"filename": "reqninja-1.2.0.tar.gz",
"has_sig": false,
"md5_digest": "7d6a2a45afb10a069c298e564f11f2f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 44989,
"upload_time": "2025-08-10T10:43:32",
"upload_time_iso_8601": "2025-08-10T10:43:32.800171Z",
"url": "https://files.pythonhosted.org/packages/2b/e4/cc98cbb98ed36ba1e91f42e4934e3c692be2c04d1c250b63963d6df327e4/reqninja-1.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-10 10:43:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vishal-ravi",
"github_project": "reqninja",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "reqninja"
}
JSON
