header is a Go command-line application and library that extracts human-readable metadata from a given URL. It scrapes OpenGraph information, Twitter cards, JSON-LD, AppLinks, and YouTube specifics (watch time, video IDs, titles), displaying them cleanly in the terminal.
Developer documentation — getting started, how-to guides, concepts, CLI reference and contribution guidance. The site deploys from main through GitHub Pages Actions; see docs/ for its source.
- Build targets: Linux and Windows on amd64, arm64 and 386; macOS on amd64 and arm64.
- Building from Source: Requires Go 1.26 or higher.
- Go Library: Importable as
github.com/arran4/headerfor embedding metadata extraction directly into Go applications.
No GitHub releases have been published yet. After the first release, binaries will be available at https://github.com/arran4/header/releases.
brew tap arran4/homebrew-tap
brew install --cask headergo install github.com/arran4/header/cmd/header@latestExtracts human-readable metadata from a given URL.
header https://youtube.com/watch?v=dQw4w9WgXcQ
header extract https://youtube.com/watch?v=dQw4w9WgXcQExample Output:
URL: https://youtube.com/watch?v=dQw4w9WgXcQ
Title: Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster) - YouTube
Description: The official video for “Never Gonna Give You Up” by Rick Astley. Never: The Autobiography 📚 OUT NOW! Follow this link to get your copy and listen to Rick’s ...
Cover Images:
- https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg
Output Formats
The tool supports multiple output formatting templates using the --style flag:
default: The default format printing concise, highlighted essential fields (URL, title, description, cover images).all_fields: A detailed format printing all captured metadata grouped logically.all_fields_plain: A detailed plain text format.json: Prints the raw page metadata as JSON.discord: A format tailored for Discord metadata embedding.jsonld: Prints human readable JSON-LD metadata.opengraph: Prints OpenGraph metadata only.twitter: Prints Twitter card metadata only.
Example of retrieving all fields in JSON:
header extract --style json https://example.comDisplay Cover Images
The --show-image flag will download the image and use your system's default image viewer (xdg-open, open, or start) to display it.
header extract --show-image https://example.com/some/articleExperimental Shiny UI: You can build the app with the shiny tag to display the image using an experimental UI window:
go build -tags shiny ./cmd/header
./header extract --show-image https://example.com/some/articleTest Diagnostics
If you want to debug what metadata a site is missing, you can use --test:
header extract --test https://example.comEdits HTML file head/meta fields.
header edit head -S '<link rel="canonical" href="https://example.com/"/>' index.html
header edit meta -s "new value" "description" index.htmlThe edit command operates in two modes: head and meta.
header edit head [flags] <file>targets the root<head>block, allowing you to manipulate standard HTML links and elements.header edit meta [flags] <name> <file>specifically targets a<meta name="...">or<meta property="...">tag for modification.
Options:
-s: set (removes all existing occurrences of this tag and inserts the new one).-S: add to set (appends a new one, does not remove existing tags).-r: replace (replaces exactly 1 existing value).-n: replace number x (only works with-r, specifies which index to replace).
Use - as the filename to read from stdin and write to stdout, which is useful for chaining in pipes.
Traces URL HTTP standard redirects as well as HTML meta-refresh redirects.
header trace-redirects https://example.com/redirectCustomization flags include --store-cookies, --redirect-limit, --update-referer, and --redirect-delay.
Checks all URLs and other details; a subset of lint rules mostly concerned with valid info (URL reachability and image validity).
header verify https://example.comLints the metadata of a URL.
header lint https://example.com
header lint --list all https://example.com
header lint --rule twitter,opengraph https://example.comLists available lint rule lists.
header lint-rule-listsLists available lint rules.
header lint-rulesExports a "card" (as an image) including the image, description, and metadata from a URL. Output can be to a file, clipboard, or stdout (specify an output destination subcommand: file, clipboard, or stdout).
header card file --out card.png https://example.com
header card file --require-cover --quality-report report.json --out card.png https://example.com
header card stdout https://example.com > card.png
header card clipboard https://example.comCard flags:
--require-cover: Fails generation if no usable cover image could be loaded. In default mode, a placeholder is rendered.--quality-report <path>: Writes machine-readable card quality JSON diagnostics.--retry-attempts: Number of HTTP attempts for idempotent requests (default:3;1disables retries).--retry-delay: Initial retry delay (default:250ms).--retry-max-delay: Maximum retry delay cap (default:5s).--timeout: Maximum total page fetch timeout (default:20s).--image-timeout: Image download timeout (default:10s).
Cover image candidates (og:image, og:image:secure_url, and twitter:image) are tried in priority order with automatic fallback upon HTTP errors or decode failures. Piping via card stdout outputs only pure PNG binary data, directing human review diagnostics to stderr.
Views images or icons from a URL (positional syntax: header view <viewType> <url>).
header view image https://example.com/image.png
header view icon https://example.comFetches a URL and prints HTTP requests and responses using httpretty.
header httpretty https://example.comSee AGENTS.md for contribution and generated-file contracts.
Run unit, integration, and race tests using:
go test -race ./...Use golangci-lint v2.15.0, matching CI, to run lint checks:
golangci-lint runTo regenerate CLI command definitions:
go generate ./...The generator is pinned as a Go tool dependency in go.mod. The generation notes explain the small main-template overlay and deterministic provenance settings.
This project is licensed under the MIT License; see LICENSE and third-party notices. Fetched website content and third-party assets retain their owners’ rights. See SECURITY.md before using the fetcher in a privileged service.