The API client for developers who live in the terminal.

Octopus is built entirely on Node.js and is currently focused on REST API testing. WebSocket, GraphQL and gRPC support are planned for future versions.

npm install -g @mrinmoyxb/octopus

Installation · Quick Start · Commands · Environments · Collections

🛠️ Tech Stack

| Layer | Technology | Purpose | |---|---|---| | Runtime | Node.js 18+ | JavaScript runtime | | HTTP Client | Axios | Sending HTTP requests | | CLI Framework | Commander.js | Commands & flags parsing | | Interactivity | Ora + Chalk | Spinners & colored output | | ASCII Art | Figlet | Terminal banner | | Storage | Lowdb (JSON) | Collections, logs, environments |

✨ Why Octopus?

| | Postman | octopus | |---|---|---| | Account required | ✅ | ❌ | | Opens in terminal | ❌ | ✅ | | Pipeable output | ❌ | ✅ | | Git-friendly | ❌ | ✅ | | Instant startup | ❌ | ✅ | | Works in scripts | ❌ | ✅ |

📦 Installation

npm install -g @mrinmoyxb/octopus

Verify it works:

octopus --help

⚡ Quick Start

# GET request
octopus get https://api.example.com/users

# POST with a JSON body
octopus post https://api.example.com/users --body '{"name":"John","age":30}'

# With an auth token
octopus get https://api.example.com/me --token your-token-here

# With custom headers
octopus get https://api.example.com/users --header "X-Api-Key: abc123"

# With query params
octopus get https://api.example.com/posts --param page=1 --param limit=10

📖 Commands

HTTP Methods

| Command | Description | |---|---| | octopus get <url> | Send a GET request | | octopus post <url> | Send a POST request | | octopus put <url> | Send a PUT request (full update) | | octopus patch <url> | Send a PATCH request (partial update) | | octopus delete <url> | Send a DELETE request |

Flags (available on all methods)

| Flag | Short | Description | |---|---|---| | --token <token> | -t | Bearer token shorthand | | --header <header> | -H | Custom header e.g. "X-Key: value" | | --param <param> | -p | Query param e.g. page=1 | | --body <json> | -b | JSON request body |

Examples

# PUT — full update
octopus put https://api.example.com/users/1 \
  --body '{"name":"John","age":31}' \
  --token mytoken

# PATCH — partial update
octopus patch https://api.example.com/users/1 \
  --body '{"age":31}' \
  --token mytoken

# DELETE
octopus delete https://api.example.com/users/1 --token mytoken

# Multiple headers
octopus get https://api.example.com/users \
  --header "X-Api-Key: abc123" \
  --header "Accept: application/json"

🌍 Environments

Stop hardcoding URLs and tokens. Use environments to switch between development, staging, and production with a single command.

Setup

# Create a development environment
octopus env set base_url http://localhost:3000 --env development
octopus env set token dev-token-abc --env development

# Create a staging environment
octopus env set base_url https://staging.myapi.com --env staging
octopus env set token staging-token-xyz --env staging

Switch environments

octopus env use development
octopus env use staging
octopus env use production

Use variables in requests

Wrap variable names in {{ }}:

octopus get {{base_url}}/users --token {{token}}

Octopus replaces {{base_url}} and {{token}} with values from the active environment before sending the request.

Manage environments

# List all environments and their variables
octopus env list

# Delete a specific environment
octopus env delete --env development

# Delete all environments
octopus env delete --all

💾 Collections

Save requests you use frequently and run them by name.

# Save a request
octopus save "get-users" --method GET --url https://api.example.com/users
octopus save "create-user" --method POST \
  --url https://api.example.com/users \
  --body '{"name":"John"}' \
  --token mytoken

# List all saved requests
octopus list

# Run a saved request
octopus run "get-users"
octopus run "create-user"

Collections are stored in octopus.json in your project folder — commit it to Git and your whole team shares the same requests automatically.

📜 History

Every request you fire is automatically logged with its response.

# Show all history
octopus history

# Show last 10 entries
octopus history --limit 10

# Filter by method
octopus history --method GET
octopus history --method POST --limit 5

Logs are stored in octopus_logs.json in your current directory.

🔧 Tips & Tricks

Pipe output to a file:

octopus get https://api.example.com/users > users.json

Chain with jq for powerful JSON processing:

# Get all user names from a list
octopus get https://api.example.com/users | jq '.[].name'

# Get a specific field
octopus get https://api.example.com/users/1 | jq '.email'

Use in shell scripts:

#!/bin/bash
if octopus get https://api.example.com/health; then
  echo "API is up ✅"
else
  echo "API is down ❌"
fi

Combine environments + collections:

# Save once using variables
octopus save "get-users" --method GET --url "{{base_url}}/users"

# Run against any environment
octopus env use development && octopus run "get-users"
octopus env use production  && octopus run "get-users"

📁 Local Files

Octopus creates these files in your current directory:

| File | Contains | |---|---| | octopus.json | Saved request collections | | octopus_env.json | Environments and variables | | octopus_logs.json | Request/response history |

All files are plain JSON — human-readable and Git-friendly.

🛠️ Development

# Clone the repo
git clone https://github.com/yourusername/octopus-cli
cd octopus-cli

# Install dependencies
npm install

# Link globally for local development
npm link

# Run directly
node bin/index.js get https://jsonplaceholder.typicode.com/posts/1

📄 License

GPL v3 © Mrinmoy Borah

Made with 🐙 by developers, for developers.

⭐ Leave a star on GitHub if you find it useful!