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.
With Go 1.27 or newer:
go install github.com/AustinMusiku/timeline@latestOr download an archive for Linux or macOS (amd64 and arm64) from the
releases page and put the
timeline binary on your PATH.
timeline run https://example.com https://example.com/aboutEach 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.
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.
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/itemsThe 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
-Xsays otherwise, and sendsContent-Type: application/x-www-form-urlencoded, unless-Hgives one. -d @filereads a file and drops its line breaks, which suits form data.--data-binary @filesends the file exactly as it is, and--data-rawnever 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.
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.httpRequests 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}}.
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.
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.
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.
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.
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,Cookieor 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.
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.
| 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.
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.mdmake test # go test ./...
make build # bin/timeline
make demo # re-record assets/demo.gif
make release # update CHANGELOG.md and tag the next versionMIT. See LICENSE.
