header documentation on header — website metadata toolkit

Extraction and rendering

Mon, 01 Jan 0001 00:00:00 +0000

Extraction and rendering

The program first fetches a page and extracts its available metadata into a PageInfo value. Supported groups include Open Graph, Twitter Cards, JSON-LD, App Links, HTML link relationships and selected site-specific information.

Different output styles render selected properties rather than changing the underlying extraction. The json style exposes structured fields; the Open Graph and Twitter styles focus on their respective families. This is why a field may be present in one style but omitted by design in another.

Getting started

Mon, 01 Jan 0001 00:00:00 +0000

Getting started

Goal: Install header, extract metadata from a URL, and inspect the result.

Prerequisites

Install a supported Go toolchain (Go 1.26 or later to build from source) and have network access to a webpage. Alternatively, download a compatible binary from GitHub Releases when available.

Install

go install github.com/arran4/header/cmd/header@latest

Check the installed command:

header --help

Extract metadata

header extract --style json https://example.com

This requests the page and prints the extracted metadata in JSON. The actual fields depend on the remote page and can change as its content changes.

Inspect social preview metadata

Mon, 01 Jan 0001 00:00:00 +0000

Fetch a page and focus on the metadata that social platforms use:

header extract --style opengraph https://example.com
header extract --style twitter https://example.com

The output only includes properties found on the page; an absent Open Graph image, for example, is not invented.

To run built-in metadata checks:

header lint https://example.com
header lint --list all https://example.com

To generate a PNG preview card from a webpage:

header card list
header card file --out card.png https://example.com

The card file is written locally. Be aware that downloaded website images remain the property of their respective owners.

Trace redirects

Mon, 01 Jan 0001 00:00:00 +0000

Trace redirects

To follow HTTP redirects and HTML meta-refresh redirects:

header trace-redirects https://example.com

Use header trace-redirects --help for the current redirect limit, delay and cookie options. Avoid using the fetcher as an unrestricted proxy in a privileged network environment; see the repository’s security policy.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Troubleshooting

Symptom	First check
The request fails	Confirm the URL is reachable and that the host accepts your client and User-Agent
A metadata field is missing	Inspect the source document; `header` does not fabricate absent properties
A rendered output is unexpected	Run `header extract --style json URL` and compare the raw parsed properties
A generated card fails	Verify destination permissions and image availability

To diagnose a page with the built-in rules:

Contributing

Mon, 01 Jan 0001 00:00:00 +0000

Contributing

The project is written in Go. Build from a checkout with Go 1.26 or later.

go test ./...
go test -race -count=1 ./...
go vet ./...
go generate ./...

Generated command sources under cmd/ are produced from definitions under internal/cli/ using the pinned gosubc dependency. Review AGENTS.md and the generation notes before changing commands.

Documentation

The documentation source lives in docs/ and uses Hugo Book as a pinned submodule. Preview with: