Skip to content
Back to search

httpstat

curl statistics made simple

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/reorx--httpstat/badge.svg)](/listings/reorx--httpstat)

HTML

<a href="/listings/reorx--httpstat"><img src="/api/listings/reorx--httpstat/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

There are three ways to get `httpstat`:

- Download the script directly: `wget https://raw.githubusercontent.com/reorx/httpstat/master/httpstat.py`

- Through pip: `pip install httpstat`

- Through homebrew (macOS only): `brew install httpstat`

> For Windows users, @davecheney's [Go version](https://github.com/davecheney/httpstat) is suggested. → [download link](https://github.com/davecheney/httpstat/releases)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 238 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # httpstat
  2. ![screenshot](screenshot.png)
  3. httpstat visualizes `curl(1)` statistics in a way of beauty and clarity.
  4. It is a **single file🌟** Python script that has **no dependency👏** and is compatible with **Python 3🍻**.
  5. ## Features
  6. - **Beautiful terminal output** — timing breakdown of DNS, TCP, TLS, server processing, and content transfer
  7. - **Structured JSON output** — `--format json` / `jsonl` for machine consumption with a stable v1 schema
  8. - **SLO threshold checking** — `--slo total=500,connect=100` exits with code 4 on violation
  9. - **Save results to file** — `--save path.json` for multi-step workflows
  10. - **NO_COLOR support** — respects the [NO_COLOR](https://no-color.org) convention
  11. - **Agent skill** — built-in [skill](skills/httpstat/SKILL.md) for agent-assisted HTTP performance diagnostics
  12. ## Installation
  13. There are three ways to get `httpstat`:
  14. - Download the script directly: `wget https://raw.githubusercontent.com/reorx/httpstat/master/httpstat.py`
  15. - Through pip: `pip install httpstat`
  16. - Through homebrew (macOS only): `brew install httpstat`
  17. > For Windows users, @davecheney's [Go version](https://github.com/davecheney/httpstat) is suggested. → [download link](https://github.com/davecheney/httpstat/releases)
  18. ## Skills
  19. httpstat ships with an agent [skill](skills/httpstat/SKILL.md) that teaches AI coding assistants (Claude Code, Cursor, etc.) how to use httpstat for HTTP performance diagnostics — automatic installation, bottleneck identification, and actionable fix suggestions.
  20. Install the skill into your project:
  21. ```bash
  22. npx skills add reorx/httpstat
  23. ```
  24. Once installed, your agent will automatically use httpstat when you ask questions like "why is this API slow?" or "debug this endpoint's latency".
  25. ## Usage
  26. Simply:
  27. ```bash
  28. python httpstat.py httpbin.org/get
  29. ```
  30. If installed through pip or brew, you can use `httpstat` as a command:
  31. ```bash
  32. httpstat httpbin.org/get
  33. ```
  34. ### cURL Options
  35. Because `httpstat` is a wrapper of cURL, you can pass any cURL supported option after the url (except for `-w`, `-D`, `-o`, `-s`, `-S` which are already used by `httpstat`):
  36. ```bash
  37. httpstat httpbin.org/post -X POST --data-urlencode "a=b" -v
  38. ```
  39. ### Structured Output
  40. Use `--format` (`-f`) to get machine-readable output:
  41. ```bash
  42. httpstat httpbin.org/get --format json
  43. ```
  44. ```json
  45. {
  46. "schema_version": 1,
  47. "url": "httpbin.org/get",
  48. "ok": true,
  49. "exit_code": 0,
  50. "response": {
  51. "status_line": "HTTP/2 200",
  52. "status_code": 200,
  53. "remote_ip": "...",
  54. "remote_port": "443",
  55. "headers": {"Content-Type": "application/json", "Server": "nginx", "...": "..."}
  56. },
  57. "timings_ms": {
  58. "dns": 5, "connect": 10, "tls": 15,
  59. "server": 50, "transfer": 20, "total": 100,
  60. "namelookup": 5, "initial_connect": 15,
  61. "pretransfer": 30, "starttransfer": 80
  62. },
  63. "speed": { "download_kbs": 1234.5, "upload_kbs": 0.0 },
  64. "slo": null
  65. }
  66. ```
  67. Use `--format jsonl` for compact single-line JSON (useful for log pipelines).
  68. ### SLO Thresholds
  69. Check response times against thresholds. Exits with code `4` on violation:
  70. ```bash
  71. httpstat httpbin.org/get --slo total=500,connect=100,ttfb=200
  72. ```
  73. Supported keys: `total`, `connect`, `ttfb` (time to first byte), `dns`, `tls`.
  74. In pretty mode, violations are printed in red at the end of the output.
  75. In JSON mode, violations appear in the `slo` field:
  76. ```json
  77. {
  78. "slo": {
  79. "pass": false,
  80. "violations": [
  81. { "key": "total", "threshold_ms": 500, "actual_ms": 823 }
  82. ]
  83. }
  84. }
  85. ```
  86. ### Save Results
  87. Write structured JSON output to a file (works with any `--format`):
  88. ```bash
  89. httpstat httpbin.org/get --save result.json
  90. httpstat httpbin.org/get --format json --save result.json
  91. ```
  92. ### Environment Variables
  93. `httpstat` has a bunch of environment variables to control its behavior.
  94. Here are some usage demos, you can also run `httpstat --help` to see full explanation.
  95. - <strong><code>HTTPSTAT_SHOW_BODY</code></strong>
  96. Set to `true` to show response body in the output, note that body length
  97. is limited to 1023 bytes, will be truncated if exceeds. Default is `false`.
  98. - <strong><code>HTTPSTAT_SHOW_IP</code></strong>
  99. By default httpstat shows remote and local IP/port address.
  100. Set to `false` to disable this feature. Default is `true`.
  101. - <strong><code>HTTPSTAT_SHOW_SPEED</code></strong>
  102. Set to `true` to show download and upload speed. Default is `false`.
  103. ```bash
  104. HTTPSTAT_SHOW_SPEED=true httpstat http://cachefly.cachefly.net/10mb.test
  105. ...
  106. speed_download: 3193.3 KiB/s, speed_upload: 0.0 KiB/s
  107. ```
  108. - <strong><code>HTTPSTAT_SAVE_BODY</code></strong>
  109. By default httpstat stores body in a tmp file,
  110. set to `false` to disable this feature. Default is `true`
  111. - <strong><code>HTTPSTAT_CURL_BIN</code></strong>
  112. Indicate the cURL bin path to use. Default is `curl` from current shell $PATH.
  113. This exampe uses brew installed cURL to make HTTP2 request:
  114. ```bash
  115. HTTPSTAT_CURL_BIN=/usr/local/Cellar/curl/7.50.3/bin/curl httpstat https://http2.akamai.com/ --http2
  116. HTTP/2 200
  117. ...
  118. ```
  119. > cURL must be compiled with nghttp2 to enable http2 feature
  120. > ([#12](https://github.com/reorx/httpstat/issues/12)).
  121. - <strong><code>HTTPSTAT_METRICS_ONLY</code></strong>
  122. If set to `true`, httpstat will only output metrics in json format,
  123. this is useful if you want to parse the data instead of reading it.
  124. > **Note**: This is kept for backward compatibility. Prefer `--format json` instead.
  125. - <strong><code>HTTPSTAT_DEBUG</code></strong>
  126. Set to `true` to see debugging logs. Default is `false`
  127. - <strong><code>NO_COLOR</code></strong>
  128. When set (to any value), disables all colored output.
  129. See [no-color.org](https://no-color.org) for the convention.
  130. ```bash
  131. NO_COLOR=1 httpstat httpbin.org/get
  132. ```
  133. For convenience, you can export these environments in your `.zshrc` or `.bashrc`,
  134. example:
  135. ```bash
  136. export HTTPSTAT_SHOW_IP=false
  137. export HTTPSTAT_SHOW_SPEED=true
  138. export HTTPSTAT_SAVE_BODY=false
  139. ```
  140. ## Related Projects
  141. Here are some implementations in various languages:
  142. - Go: [davecheney/httpstat](https://github.com/davecheney/httpstat)
  143. This is the Go alternative of httpstat, it's written in pure Go and relies no external programs. Choose it if you like solid binary executions (actually I do).
  144. - Go (library): [tcnksm/go-httpstat](https://github.com/tcnksm/go-httpstat)
  145. Other than being a cli tool, this project is used as library to help debugging latency of HTTP requests in Go code, very thoughtful and useful, see more in this [article](https://medium.com/@deeeet/trancing-http-request-latency-in-golang-65b2463f548c#.mm1u8kfnu)
  146. - Bash: [b4b4r07/httpstat](https://github.com/b4b4r07/httpstat)
  147. This is what exactly I want to do at the very beginning, but gave up due to not confident in my bash skill, good job!
  148. - Node: [yosuke-furukawa/httpstat](https://github.com/yosuke-furukawa/httpstat)
  149. [b4b4r07](https://twitter.com/b4b4r07) mentioned this in his [article](https://tellme.tokyo/post/2016/09/25/213810), could be used as a HTTP client also.
  150. - PHP: [talhasch/php-httpstat](https://github.com/talhasch/php-httpstat)
  151. The PHP implementation by @talhasch
  152. Some code blocks in `httpstat` are copied from other projects of mine, have a look:
  153. - [reorx/python-terminal-color](https://github.com/reorx/python-terminal-color) Drop-in single file library for printing terminal color.
  154. - [reorx/getenv](https://github.com/reorx/getenv) Environment variable definition with type.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.