NetShift CLI

NetShift is a terminal-first API workflow tool for making HTTP requests directly from your shell. It focuses on fast requests, clean output, and readable response metadata so you can inspect APIs without switching tools.

Quick Start

Build the CLI from the cli package and run the binary:

npm run build
ns ping

If the CLI is installed and working, ping prints a simple health check message.

Commands

ping

Checks whether the CLI is available.

ns ping

Expected output:

NetShift is alive and ready to serve! 🚀

HTTP request

The main request flow uses the HTTP method and URL you provide:

ns get https://jsonplaceholder.typicode.com/todos/1

You can also send headers and query parameters:

ns post https://httpbin.org/post \
	-H "Content-Type: application/json" \
	-H "Authorization: Bearer token" \
	-Q "source=netshift" \
	-Q "debug=true"

Request Options

The current CLI supports these request options:

• -H, --header <header...> for repeated Key: Value headers
• -Q, --query <query> for repeated key=value query parameters
• --show-headers to print the response headers after the metadata block

Rules for input parsing:

• Headers must contain a colon.
• Query values are appended in the order you provide them.
• URLs are normalized before the request is sent.

Response Output

Every successful request prints a metadata block first:

Status: 200 OK
Time: 143 ms
Size: 1.42 KB
----------------------------------------

When --show-headers is enabled, the response headers appear next:

Response Headers:

content-type : application/json
date : Fri, 10 May 2026 12:00:00 GMT

JSON and HTML responses are formatted for readability before they are printed to the terminal.

Example Workflows

Inspect a JSON endpoint

ns get https://jsonplaceholder.typicode.com/posts/1

Check headers from an API

ns get https://httpbin.org/headers --show-headers

Send a request with auth and query params

ns get https://api.example.com/items \
	-H "Accept: application/json" \
	-H "Authorization: Bearer your-token" \
	-Q "page=1" \
	-Q "limit=10"

Project Notes

The CLI is organized around a few small pieces:

• request parsing and command wiring in src/cli/commands/request.ts
• request execution in src/services/request-service.ts
• output formatting for metadata, headers, response bodies, and errors
• utility helpers for URL normalization, query parameters, and header parsing

That structure keeps the CLI easy to extend as more commands and request features are added.