diff --git a/README.md b/README.md index 2da03de..79521fb 100644 --- a/README.md +++ b/README.md @@ -1,101 +1,121 @@ httpcat =============== -A netcat like tool for analysing/mocking HTTP requests (from both server and client perspective). My first experiment with Go. +A netcat-like tool for analysing or mocking HTTP requests. My first experiment with Go. ## Usage ``` -httpcat [OPTIONS] +httpcat [OPTIONS] -Application Options: - -v, --verbose Show additional details - --headers Show headers and request/status line only (default is everything) - --bodies Show bodies only (default is everything) - --nocolour Don't use colours (default is requests are blue and responses are red) - --notimestamps Don't show timestamps +Commands: -Help Options: - -h, --help Show this help message + client Send an HTTP request + proxy Start a reverse HTTP logging proxy + server Start a mock HTTP server + version Display version -Available commands: - client Send an HTTP request - proxy Start a reverse HTTP logging proxy - server Start a mock HTTP server - version Display version +Command specific help: + + httpcat --help ``` -Get help about a specific command by adding `--help` after the command. Example: +### Global Options + +The following options apply to all commands. ``` -httpcat client --help +-v, --verbose Show additional details. + + --headers Show headers and request/status line only (default is + everything). + + --bodies Show bodies only (default is everything). + + --nocolour Don't use colours (default is requests in blue and + responses in red). + + --notimestamps Don't show timestamps. + + --noindent Don't indent bodies (currently, only application/json + bodies are indented). ``` ## Client Mode -Sends a request to the specified server and displays the response. +Sends an HTTP request to the specified server and displays the response. ### Usage ``` -httpcat [OPTIONS] client [client-OPTIONS] +httpcat client [OPTIONS] +``` +### Client Specific Options +``` +-u, --url= The URL to send the request to. -Application Options: - -v, --verbose Show additional details - --headers Show headers and request/status line only (default is everything) - --bodies Show bodies only (default is everything) - --nocolour Don't use colours (default is requests are blue and responses are red) - --notimestamps Don't show timestamps +-H, --header= A header to add to request in the form name:value. Use + multiple times for multiple headers. -Help Options: - -h, --help Show this help message +-m, --method=[GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS] + HTTP method for request (default: GET). -[client command options] - -u, --uri= The URI to send the request to - --header= A header to add to request in the form name:value. Use multiple times for multiple headers. - -m, --method= HTTP method for request (default: GET) - -b, --body= Request body to send +-b, --body= Request body to send. ``` ### Example ``` -httpcat client --method POST --body TESTING --uri http://localhost:8080/api/testing +httpcat client \ + --method POST \ + --body "Testing 123" \ + --header "Content-Type: text/plain" \ + --header "Authorization: Bearer abc123" \ + --uri http://localhost:8080/api/testing ``` +Note that the `\` character in the above example is the line continuation character that allows you to break long lines into smaller lines in most Linux/macOS shells. + +For the Windows `cmd` shell, use `^` for line continuation. For PowerShell, use ` (the backtick character). + ## Server Mode -Creates mock routes that listen on specific paths and return specific response bodies. Displays the details of any requests that it receives. +Creates a web server with mock routes that listen on specific paths and return specific response bodies. Displays the details of any requests that it receives. ### Usage ``` -httpcat [OPTIONS] server [server-OPTIONS] +httpcat server [OPTIONS] +``` -Application Options: - -v, --verbose Show additional details - --headers Show headers and request/status line only (default is everything) - --bodies Show bodies only (default is everything) - --nocolour Don't use colours (default is requests are blue and responses are red) - --notimestamps Don't show timestamps +### Server Specific Options -Help Options: - -h, --help Show this help message +``` +-p, --port= Port to listen on. (default: 8080). -[server command options] - -p, --port= Port to listen on. (default: 8080) - -r, --route= Route which is made up of a path, a response body, and a response status, all separated by the pipe character. Repeat for additional routes. (default: /|testing|200) - -c, --cors Enable Cross Origin Resource Sharing (CORS). - -H, --header= A header to add to response in the form name:value. Repeat for additional headers. +-r, --route= Route which is made up of a path, a response body, and a + response status, all separated by the pipe '|' character. + Repeat for additional routes. (default: /|testing 123|200). + +-c, --cors Enable Cross Origin Resource Sharing (CORS). Allows all + requested methods and headers. + +-H, --header= A header to add to response in the form name:value. Use + multiple times for multiple headers. ``` ### Example ``` -httpcat server --port 8080 --route "/hello|Hello World|200" --header "Content-Type:text/plain" +httpcat server \ + --port 8080 \ + --route "/hello|Hello World|200" \ + --route "/goodbye||204" \ + --header "Content-Type: text/plain" \ + --cors ``` -This creates a web server that listens on port 8080 and responds to any requests to the `/hello` path with the response `Hello World` and response code `200`. Repeat the `--route` option to add more routes. +This creates a web server that listens on port `8080` and responds to any requests to the `/hello` path with the response `Hello World` and response code `200`, and returns an empty response with a `204` code to any requests made to `/goodbye`. The server will allow any requested headers and methods for CORS requests. ## Proxy Mode @@ -104,21 +124,13 @@ ### Usage ``` -httpcat [OPTIONS] proxy [proxy-OPTIONS] +httpcat proxy [OPTIONS] +``` -Application Options: - -v, --verbose Show additional details - --headers Show headers and request/status line only (default is everything) - --bodies Show bodies only (default is everything) - --nocolour Don't use colours (default is requests are blue and responses are red) - --notimestamps Don't show timestamps - -Help Options: - -h, --help Show this help message - -[proxy command options] - -p, --port= The port that the proxy listens on. - -t, --target= +### Proxy Specific Options +``` +-p, --port= The port that the proxy listens on. +-t, --target= ``` ### Example