Skip to content
AustinMusikuPublic

About

Times each phase of an HTTP request, and gives you back the stats as json or a waterfall in your terminal.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

timeline

A network waterfall for the terminal. timeline sends a sequence of HTTP requests and draws them all on one time axis, with each bar split into DNS, connect, TLS, wait and download.

timeline drawing three requests, cold then warm

Install

With Go 1.27 or newer:

go install github.com/AustinMusiku/timeline@latest

Or download an archive for Linux or macOS (amd64 and arm64) from the releases page and put the timeline binary on your PATH.

Usage

timeline run https://example.com https://example.com/about

Each URL gets a GET, one after the other, in the order given. For anything more, write the sequence in a file and run it with -f.

Flag Default What it does
-n, --repeat 1 Times to run the whole sequence
-c, --concurrency 1 Requests to keep in flight at once
--timeout 30s Time limit for each request, 0 for none
--max-redirects 10 Redirects to follow from each request, 0 for none
-X, --method GET Method for every request, POST when there is a body
-H, --header Name: value to send with every request, repeatable
-u, --user user:password for basic auth on every request
-d, --data Body for every request, @file or @- for stdin
--data-raw Like -d, but a leading @ is sent as typed
--data-binary Like -d, but @file keeps its line breaks
-f, --file Read the sequence from a .http file, - for stdin
--cookies off Keep the cookies responses set and send them on
-k, --insecure off Skip checking the server's certificate
--cacert PEM file of CA certificates to trust
--cert PEM file of a client certificate
--key PEM file of the client certificate's key
--json off One line of JSON per request instead of drawing
--show-body off With --json, each response's body as well
--show-secrets off Show the passwords, tokens and cookies output hides
--color auto auto, always or never

timeline run --help has the full reference.

Flags from curl that timeline lacks, such as -L, -s and -o, are errors that say what to use instead. --compressed does nothing, since timeline asks for gzip already.

Authentication

timeline run -H "Authorization: Bearer $TOKEN" https://api.example.com/me
timeline run -u me https://api.example.com/me

-u with no password asks for one, so it stays out of your shell history. An Authorization from -H wins over -u. Credentials are not sent on to another host when a redirect leads there.

Output hides credentials: a password in a URL becomes xxxxx, an Authorization keeps only its scheme (Bearer xxxxx), and a Cookie only its names (session=xxxxx). Response bodies hide them too. --show-secrets shows them all, for when you need the real values, such as to decode a token. It is read from the command line only.

Request bodies

timeline run -d 'user=me&remember=1' https://example.com/login
timeline run -H 'Content-Type: application/json' -d @body.json https://api.example.com/items

The body flags work as in curl, so a command from your browser's "Copy as cURL" runs with curl swapped for timeline run:

  • A body makes the request a POST, unless -X says otherwise, and sends Content-Type: application/x-www-form-urlencoded, unless -H gives one.
  • -d @file reads a file and drops its line breaks, which suits form data. --data-binary @file sends the file exactly as it is, and --data-raw never reads a file.
  • Several body flags are joined with &, in the order given.

Each repeat sends the same bytes. A 307 or 308 redirect sends them on again, and a 301, 302 or 303 turns the request into a GET with no body.

Writing the body is part of send. A small body is handed to the kernel in one go, so send stays short and its trip to the server shows up in wait; send grows only once the body outgrows the socket's buffer.

Sequence files

When each step needs its own method, headers or body, write the sequence in the .http format that VS Code's REST Client and JetBrains share:

@base = https://api.example.com

# @name login
POST {{base}}/login
Content-Type: application/json

{"user": "me", "password": "{{$processEnv PASSWORD}}"}

###
# @name me
GET {{base}}/me
Authorization: Bearer {{login.response.body.access_token}}
timeline run -f flow.http

Requests are separated by ### and run in order. A request is its request line (METHOD URL, or just a URL for a GET), its headers, a blank line, and its body. Lines starting with ? or & right after the request line continue the URL. # @name names a request, and the waterfall shows that name in place of its URL. Lines starting with # or // are comments.

< ./file sends a file as the body and <@ ./file fills in its variables first, both relative to the .http file. @name = value sets a variable for the whole file. {{name}} is that variable, or the environment variable of the same name; {{$processEnv NAME}} is the environment only. A variable that is not set is an error, and errors give the file and line but never a value.

{{login.response.body.access_token}} is a value from the response of an earlier request named login. The path after body. reads JSON: body.data.items[0].id for nested keys and lists, body.$.token as well as body.token, and body.* for the whole body. headers.Name reads a response header. A text value goes in as it is; numbers, objects and lists go in as JSON. Each round reads its own responses, and after a redirect the value comes from the last hop.

A request that reads a value waits for the request it reads, even with -c; the others run as usual. If the value isn't there, because the earlier request failed or its body has no such key, the request is not sent: its row shows ERR with the variable, and it counts as failed. A value is never printed, though one put in a query string shows in the URL like any other. Only the bodies of requests that another one reads are kept, up to 16 MiB each, and only JSON can be read from; XML is not.

-H and -u apply to every request in the file that does not set the same header itself. -X and the body flags don't go with -f, since each request has its own. -n, -c and the rest work as with URLs.

These parts of the format are errors rather than skipped, since the run would not be the one the file describes: response handlers (> {% ... %}) and >>, values from an earlier request ({{login.request.body.user}}), generated values such as {{$guid}}, environment files (http-client.env.json), and any other # @ line. Output hides credentials in headers and URLs as usual, but not in a query string, so keep secrets out of ?key={{API_KEY}}.

Cookies

timeline run --cookies -f login.http

--cookies keeps the cookies that responses set, redirects included, and sends them with later requests to the same site, as a browser would. They last for the whole run, so a later round starts with the cookies of the one before. It is off by default, so that rounds stay the same unless you ask. The Cookie a request sent is in request_headers with its values hidden.

With -c above 1, requests can overlap, so a request may go out before the one that sets its cookie has finished. A request that reads a value from an earlier response waits for it, but a cookie gives no such link.

TLS

timeline run --cacert internal-ca.pem https://api.internal.example.com/health
timeline run --cert client.pem --key client-key.pem https://mtls.example.com/
timeline run -k https://localhost:8443/

--cacert trusts the certificates in a PEM file in place of the system's, for hosts signed by a private CA. --cert sends a client certificate to a server that asks for one, with its key from --key or, without it, from the same file. A key protected by a passphrase is not supported. -k skips checking the server's certificate altogether. The TLS timings are the same either way.

Reading the waterfall

                                             0              500ms           1s
                                             ┬──────────────┬───────────────┬───
 1  404  #1  https://go.dev/nope      745ms  ddcccccttttttwwwwwwwwwwr
 2  ERR      http://nosuch.invalid     51ms                         dd
             dial tcp: lookup nosuch.invalid: no such host

 1  404  #1  https://go.dev/nope      312ms                          wwwwwwwwwwr
 2  ERR      http://nosuch.invalid     18ms                                    d
             dial tcp: lookup nosuch.invalid: no such host

 #1  216.239.34.21:443  HTTP/2.0  TLS 1.3

 - blocked  d dns  c connect  t tls  s send  w wait  r receive

A row is the request's place in the sequence, its status, the connection it used, its URL, how long it took, and its bar. A bar starts where the request started and is made of these phases, in order:

Phase Letter Colour What it covers
blocked - grey Before any network activity, such as waiting for a free connection
dns d cyan Looking up the host
connect c yellow The TCP handshake
tls t magenta The TLS handshake
send s default Writing the request and its body
wait w green Request written, waiting for the first byte back
receive r blue First byte to the end of the body

In a terminal the bars are coloured blocks. Piped, or with --color never, they are the letters above. Piped, URLs are also never shortened, however long the lines get.

A blank line separates rounds of --repeat. Connections stay open between rounds, so the first round is cold and the rest are warm: a warm request has no dns, connect or tls.

With --repeat above 1, a table under the chart sets each request's first round beside the median of the rest, phase by phase:

                 total  blocked   dns  connect    tls  send   wait  receive
 1  https://go.dev/nope
    round 1      745ms        -  60ms    150ms  220ms     -  300ms     15ms
    median 2–5   312ms        -     -        -      -     -  300ms     12ms
 2  http://nosuch.invalid
    round 1     failed
    rounds 2–5  failed

A - is a phase that took under 0.05ms. Failed rounds are left out of the median, and the line ends with how many there were, such as (1 of 4 failed). Each column is its own median, so the phases need not add up to the total.

Connections are numbered in the order the run first used them, and listed under the chart with their address, protocol and TLS version. Rows with the same # shared a connection: several at once under HTTP/2, one after another under HTTP/1.1. A connection marked resumed was opened with a shortened TLS handshake, using a session from an earlier connection in the run.

A request that got no response shows ERR with the reason underneath, and its bar stops in the phase that failed. A 4xx or 5xx is a response like any other.

Redirects are followed, and each hop is a request of its own, drawn on a row under the one that led to it:

 1  302  #1  http://go.dev             523ms  ddwwww
    200  #2  ↳ https://go.dev/         809ms       ccttwwwr

After --max-redirects hops the last redirect is left unfollowed, with stopped after 10 redirects under its row, and counts as a failed request.

JSON

timeline run --json -n 5 https://example.com | jq -s 'map(.wait_ms) | add / length'

--json writes one object per request, as each one finishes:

{
  "seq":0,
  "round":0,
  "hop":0,
  "name":"",
  "started_at":"2026-10-12T14:01:33.823986Z",
  "offset_ms":0.118,
  "method":"GET",
  "url":"https://go.dev",
  "request_headers":{"Accept-Encoding":["gzip"]},
  "request_body_bytes":0,
  "status":200,
  "proto":"HTTP/2.0",
  "body_bytes":12085,
  "body":null,
  "body_encoding":"",
  "body_error":"",
  "location":null,
  "conn_id":1,
  "reused":false,
  "remote_addr":"216.239.34.21:443",
  "local_addr":"172.29.91.41:41948",
  "tls_version":"TLS 1.3",
  "tls_resumed":false,
  "alpn":"h2",
  "attempts":1,
  "resolved_ips":[
    "216.239.34.21","216.239.32.21","216.239.38.21","216.239.36.21",
    "2001:4860:4802:34::15","2001:4860:4802:32::15",
    "2001:4860:4802:38::15","2001:4860:4802:36::15"
  ],
  "dial_attempts":1,
  "blocked_ms":0.234,
  "dns_ms":75.149,
  "connect_ms":153.612,
  "tls_ms":203.429,
  "send_ms":0.132,
  "wait_ms":315.502,
  "receive_ms":34.016,
  "total_ms":782.074,
  "error":""
}

Every key is always present. The hops of a redirect share a seq, and hop counts them from 0 for the URL that was given. name is the request's # @name from a sequence file, and empty otherwise. request_headers are the headers timeline set, with credentials hidden; Go's client adds Host, User-Agent and the like as it sends. request_body_bytes is the size of the body sent; the request body itself is never written out. location is the response's Location header, or null if it had none. conn_id is the number the waterfall shows, and 0 for a request that never got a connection. resolved_ips and dial_attempts describe the request's own dial, so they are empty and 0 on a reused connection. timeline run --help describes the format.

Response bodies

timeline run --json --show-body -f flow.http | jq -r 'select(.status >= 400) | .body'

--show-body fills in body with each response's body, gunzipped and otherwise as it arrived, so you can see what a POST returned without sending it again. It goes with --json only, and the waterfall never shows a body. A body that isn't UTF-8 text is base64, with body_encoding set to base64. Each hop of a redirect has its own body.

body stays null without --show-body, for a request that got no response or failed partway through its body, and for a body timeline can't read: one over 16 MiB, or encoded with something other than gzip. body_error says which of the last two.

A body hides credentials as the headers do. Any value of 8 characters or more shows as xxxxx when:

  • the request sent it in Authorization, Proxy-Authorization, Cookie or as the URL's password, as a server that echoes the request would show it
  • the response set it in a Set-Cookie
  • a later request in the sequence file sends it in one of those headers, as with the login's token below
{"name":"login","body":"{\"access_token\": \"xxxxx\", \"refresh_token\": \"r-9f2c...\"}",...}
{"name":"account","request_headers":{"Authorization":["Bearer xxxxx"]},...}

Only the output hides them, so the account request still sends the real token. Other secrets show as they are, such as a refresh_token that no request sends. --show-secrets shows every value.

Configuration

A setting is read from its flag, then a TIMELINE_* environment variable, then the config file, then the default.

TIMELINE_REPEAT=3 timeline run https://example.com
# ~/.config/timeline/config.yaml
# (~/Library/Application Support/timeline/config.yaml on macOS)
repeat: 3
timeout: 5s
color: never

--config points at a different file. NO_COLOR is honoured. -H, -u and the body flags can carry credentials, so they are read from the command line only. So is -k, so that no config file can turn certificate checks off, and --show-secrets, so that none can make every run show credentials. --cacert, --cert and --key are paths, and can be set in either place.

Exit status

Status When
0 Every request got a response, 4xx and 5xx included
1 A request failed, with the reason under its row and in its JSON error
2 A flag, argument or file was wrong, so nothing was sent
130, 143 Ctrl-C or SIGTERM stopped the run

An interrupted run still draws what it collected, and with --json those lines are already written.

For AI agents

skills/timeline/SKILL.md tells an agent when to reach for timeline and how to read what it prints. For Claude Code, put it in your skills:

mkdir -p ~/.claude/skills/timeline
curl -fsSL -o ~/.claude/skills/timeline/SKILL.md https://raw.githubusercontent.com/AustinMusiku/timeline/master/skills/timeline/SKILL.md

Development

make test      # go test ./...
make build     # bin/timeline
make demo      # re-record assets/demo.gif
make release   # update CHANGELOG.md and tag the next version

License

MIT. See LICENSE.

About

Times each phase of an HTTP request, and gives you back the stats as json or a waterfall in your terminal.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Used by

Contributors

Languages