Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

klein logo

klein is a minimalist URL shortener written in Go. No unnecessary clutter, web UI, features, etc. Just shortening and serving redirections.


klein has three core components that are abstracted into drivers to allow different functionality:

  1. auth
    • Handles authentication, guarding access to shortening links
    • Comes with two drivers:
      • Unauthenticated—shorten URLs without authentication
      • Static Key—require a static key/password
      • HTTP Basic—uses HTTP Basic Auth, require a username and password
  2. alias
    • Handles generating URL aliases.
    • Comes with two drivers:
      • Alphanumeric—returns a random alphanumeric string with a configurable length
      • Memorable—returns a configurable amount of English words
  3. storage
    • Handles storing and reading shortened URLs.
    • Comes with four drivers:
      • File—stores data as text files in a directory
      • Bolt—stores data in a bolt database
      • Redis—stores data in a redis database (ensure you configure save)
      • Spaces.stateful—stores data as a single file in DigitalOcean Spaces
      • Spaces.stateless—stores each URL as an object in DigitalOcean Spaces
      • PostgreSQL—stores data in a PostgreSQL database
      • Memory—stores data in a temporary map in memory


Once installed and configured, there are two actions that you can do:

  1. Shorten a URL:
    • Send a POST request to / with the following two fields:
      1. url—the URL to shorten
      2. key—if the Static Key auth driver is enabled
      3. alias—a custom alias to be used instead of a randomly-generated one
    • Example cURL command: curl -X POST -d 'url=' -d 'key=secret_password' -d 'alias=klein_gh' http://localhost:5556/
      • This will create a short URL at http://localhost:5556/klein_gh that redirects to
  2. Look up a URL/serve a redirect:
    • Browse to http://[path to klein]/[alias] to access a short URL.


Use the docker image kamaln7/klein. The latest tag is a good bet. See the releases page for version numbers.

Or grab the latest binary from the releases page and drop it in /usr/local/bin, /opt, or wherever you like.


klein uses CLI options or environment variables for config. For environment variables, each option is prefixed with klein and both dots and dashes are replaced with underscores, eg the environment variable for the storage.spaces.access-key option is KLEIN_STORAGE_SPACES_ACCESS_KEY.

Running klein without any configuration will use the following default config:

  • Aliases are random 5-character alphanumeric strings
  • Listens on
  • No authentication
  • Stores URLs as files in a urls directory in the current working directory

Full list of config options

$ klein --help
klein is a minimalist URL shortener.

  klein [flags]

      --alias.alphanumeric.alpha                           use letters in code (default true)
      --alias.alphanumeric.length int                      alphanumeric code length (default 5)
      --alias.alphanumeric.num                             use numbers in code (default true)
      --alias.driver string                                what alias generation to use (alphanumeric, memorable) (default "alphanumeric")
      --alias.memorable.length int                         memorable word count (default 3)
      --auth.basic.password string                         password for HTTP basic auth
      --auth.basic.username string                         username for HTTP basic auth
      --auth.driver string                                 what auth backend to use (basic, key, none) (default "none")
      --auth.key string                                    upload API key
      --error-template string                              path to error template
  -h, --help                                               help for klein
      --listen string                                      listen address (default "")
      --root string                                        root redirect
      --storage.boltdb.path string                         path to use for bolt db (default "bolt.db")
      --storage.driver string                              what storage backend to use (file, boltdb, redis, spaces.stateful,, memory) (default "file")
      --storage.file.path string                           path to use for file store (default "urls")
      --storage.redis.address string                       address:port of redis instance (default "")
      --storage.redis.auth string                          password to access redis
      --storage.redis.db int                               db to select within redis
      --storage.spaces.access-key string                   access key for spaces
      --storage.spaces.region string                       region for spaces
      --storage.spaces.secret-key string                   secret key for spaces string                        space to use
      --storage.spaces.stateful.path string                path of the file in spaces (default "klein.json")
      --storage.spaces.stateless.cache-duration duration   time to cache spaces results in memory. 0 to disable (default 1m0s)
      --storage.spaces.stateless.path string               path of the directory in spaces to store urls in (default "/klein") string                     postgresql database (default "klein") string                         postgresql host (default "localhost") string                     postgresql password (default "secret") int32                          postgresql port (default 5432) string                      postgresql sslmode (default "prefer") string                        postgresql table (default "klein") string                         postgresql user (default "klein")
      --url string                                         path to public facing url

Service file

Here's a Systemd service file that you can use with klein:






Don't forget to add your config to the ExecStart line and update User and Group if necessary. Make sure that klein has permission to write to the URLs directory.


To manage dependencies, we use Go modules.

To build the app, run go build.
This will produce a binary named klein. You can now run the app by running ./klein

❤️ Contributors

  • @LukeHandle
  • @DMarby