brok: Finds broken links in text files

[ bsd3, command-line-tools, library, program ] [ Propose Tags ]
Versions [RSS],,,,,,, 1.0.0, 1.1.0
Dependencies ansi-terminal, attoparsec, base (>=4.7 && <5), brok, classy-prelude, connection, containers, directory, file-embed, http-client, http-client-tls, http-conduit, template-haskell, text, time [details]
License BSD-3-Clause
Copyright 2019 Small Hadron Collider
Author Small Hadron Collider
Category Command Line Tools
Home page
Bug tracker
Source repo head: git clone
Uploaded by smallhadroncollider at 2020-07-27T20:33:00Z
Executables brok
Downloads 3513 total (21 in the last 30 days)
Rating 2.0 (votes: 1) [estimated by Bayesian average]
Your Rating
  • λ
  • λ
  • λ
Status Docs available [build log]
Last success reported on 2020-07-27 [all 1 reports]

Readme for brok-1.1.0

[back to package description]


Find broken links in text documents


Similar idea to awesome_bot, but with different output options.

Currently only supports http:// and https:// prefixed URLs


Binaries for Mac and Linux are available. Add the binary to a directory in your path (such as /usr/local/bin).


To build the latest version:

docker build -t brok

To run brök:

docker run brok


If you have cabal installed:

cabal install brok

Make sure you run cabal update if you haven't run it recently.


Requirements: Stack

The following command will build brök and then install it in ~/.local/bin:

stack build && stack install


Basic Usage

Check all links in a single text file:


Or in multiple files:

brok links.tex

If you're using this as part of a test suite, you probably only need the errors:

brok links.tex > /dev/null



By default brök will cache successes for a day in a .brokdb file. It will always recheck errors.

If you want to adjust the cache length, you can enter the number of seconds after which the cache invalidates:

# cache for a week
brok --cache 604800 links.tex

If you want to avoid creating the .brokdb file or ignore the cache entirely you can use the --no-cache option:

# do not cache results
# and don't use previously generated cache
brok --no-cache links.tex

Check Certificates

Most browsers will display a website even if it has certificate issues (such as an incomplete certificate chain). By default Brök will not check certificates, so replicate this behaviour.

If you would like to enforce certificate checking, you can turn this on:

brok --check-certs

Any sites with certificate issues will then return a Could not connect error.

Ignore URLs

You can tell brök to ignore URLs with specified prefixes:

# ignore facebook and amazon URLS
brok --ignore "" "" links.tex


By default brök waits for 100ms between URL checks. You can change the delay:

# wait for 1 second between checks
brok --interval 1000 links.tex

Only Show Failures

If you want to see what's going on, but you're not interested in successes, then you can use the --only-failures option:

# see what's going on, but only show failures
brok --only-failures links.tex

If you're using brök as part of a script then you should redirect stdout.

Colour Output

By default the output uses bash colour codes. You can turn this off using the --no-color setting.

Git Pre-Commit Hook

If you want to check all the links in your Git repo are valid before being able to commit then add something like the following to .git/hooks/pre-commit.


#! /bin/bash

# cache for 1 week
# use find to check all *.md files
# only show errors (if there are any)
brok --cache 604800 $(find . -type f -name "*.md") > /dev/null


#! /bin/zsh

# cache for 1 week
# using a zsh glob to check all *.md files
# only show errors (if there are any)
brok --cache 604800 */**/*.md > /dev/null