CLI Guidelines: the clig.dev guide as a Hugo site you can self-host

What the CLI Guidelines project actually ships

The repository is the source of a document, not a tool. The README states that the content of the guide lives in a single Markdown file, content/_index.md, and that the website is built using Hugo. Everything else in the tree supports that one file: assets/, layouts/, hugo.toml, build.sh, scripts/ and wrangler.toml. There is no package to install into your project and no API to call. If you arrived expecting a library that validates your argument parser, you are looking at the wrong repository.

The audience is narrower than the description suggests. The guide is written for people who are making decisions about a command-line program's interface: flag naming, error messages, help output, exit codes, prompts, and the interaction between a tool and the shell it runs in. A backend engineer who occasionally writes a script will find some of it applicable and much of it aimed elsewhere. A team maintaining a CLI that other people install is the group this is written for. The README frames the goal as taking traditional UNIX principles and updating them for the modern day, which is a fair summary of the editorial stance: the guide treats conventions as defaults to be justified rather than laws to be obeyed.

How the guide is built and served

The pipeline is short and worth understanding before you fork it. Hugo reads content/_index.md plus the templates in layouts/ and the settings in hugo.toml, and writes a static site into public/. The README states that build.sh installs a pinned Hugo and builds the site into public/, so the build is reproducible rather than dependent on whatever Hugo version happens to be on your machine. That pinned install is the detail that matters if you plan to rebuild the guide years from now.

Deployment is described as Cloudflare Workers acting as a static-assets project, driven by wrangler.toml, which runs build.sh and uploads public/ as the Worker's static assets. The deploy command given in the README is npx wrangler deploy. Two additional pieces sit outside the deploy itself, described as zone-level Cloudflare Rules: a URL Rewrite rule that serves /llms.txt for requests to / that send an Accept: text/markdown header, and a Redirect rule from www.clig.dev to the apex clig.dev. The README notes these are not part of the deploy and that both can be provisioned or updated idempotently with scripts/cloudflare-transform-rule.sh.

That Accept: text/markdown behaviour is the most interesting architectural choice here. The same URL returns HTML to a browser and Markdown to a client that asks for it, which is a deliberate concession to agents and command-line fetchers. It also means the site has two representations of the same content, and only one of them is what a human reviewer typically reads.

Running Hugo locally to read or edit the guide

The README gives the local workflow directly. It assumes Homebrew for the Hugo install, which is a macOS and Linux convention; on other systems you would install Hugo by whatever means that platform provides, and the README does not cover that case. After installing, you change into the repository and start the server.

brew install hugo
cd <path>/<to>/cli-guidelines/
hugo server

Hugo serves the site on its default port and rebuilds as you edit files. Because the entire guide is content/_index.md, you can open that file in an editor, change a sentence, and see the result on the next page load without touching anything under layouts/.

The README also documents how to view the site from a phone or another device on the same network:

hugo server --bind 0.0.0.0 --baseURL http://$(hostname -f):1313

Note the port 1313 in that command, which is the one the README uses when it constructs the base URL. Binding to 0.0.0.0 exposes the server to your local network, so this is a command for a trusted network, not a coffee shop. The README does not discuss authentication or access control for that mode because there is none.

Where the advice is opinionated and where it is thin

A guide that spans flag conventions, output formatting, error handling and interactivity will not be equally strong on all of them, and this one is no exception. The sections that deal with human-facing behaviour, such as how a program should respond when it is not attached to a terminal, or when it should refuse to prompt, tend to be the most concrete. The advice about machine-readable output is harder to apply because the guide cannot know whether your tool's consumers want JSON, line-delimited records, or something else, so it can only push you toward making a deliberate choice.

The real limitation is that nothing here is enforceable. There is no test suite in the repository, no schema, and no reference implementation. Two engineers can read the same paragraph and ship different behaviour, both believing they followed the guide. That is a property of written guidelines generally, but it matters more for a project whose entire output is prose. If your team needs consistency across many CLIs, you will have to convert the guide's positions into your own review checklist or lint rules; the repository does not do that for you.

A second constraint is licensing rather than technology. The work is licensed under CC-BY-SA-4.0, which the README links to. A ShareAlike licence is not the same as a permissive software licence, and a modified internal version of the guide may carry obligations that a plain MIT-licensed document would not. That is a question for whoever handles your organisation's licensing, not something the repository answers.

How it differs from a CLI framework or generator

The obvious alternative is not another guide but a framework that encodes conventions in code, such as a command-line parsing library for your language of choice. The difference in approach is fundamental. A framework decides how flags are parsed, how help is generated and how errors are printed, and you get consistency by construction. The CLI Guidelines decide nothing for you; they describe what a good outcome looks like and leave the mechanism to you. You can follow the guide while using any parser, or none.

The trade-off runs both ways. A framework gives you uniform behaviour across every tool that uses it and takes the design decision off your plate, at the cost of fitting your tool into that framework's model of what a CLI is. The guide gives you the reasoning behind the conventions, which is useful precisely when your case does not fit the common pattern, and costs you the effort of applying it. Teams that maintain one CLI usually want the framework. Teams that maintain many, or that are writing something unusual, get more from the guide.

There is also a distribution difference. A framework is a dependency with versions and upgrade paths. This repository is a document you can clone, read offline, and pin at a commit. The README's own contribution notes point at a Discord server for discussion, which is where the editorial arguments happen; the Markdown file is the settled output of those arguments.

Maintenance, licence and the cost of staying current

The repository is not archived, and the last push was on 2026-05-16. That is recent enough that the project is not abandoned, but the commit history of a document repository is not a release cadence: there are no releases, and the README does not describe a versioning scheme for the guide's content. If you vendor the guide into your own documentation, you have no version number to pin against, only a commit hash. That is the practical upgrade cost. You will not be notified when a paragraph changes, because there is nothing to notify you.

On the build side, the pinned Hugo in build.sh reduces the risk that a future Hugo release breaks the site, but it also means the guide's rendering is tied to that pin until someone updates it. Cloudflare Workers and wrangler.toml are external dependencies with their own change cycles, and the README's deploy instructions assume access to a Cloudflare account and an API token for the transform rule script. Self-hosting on a static file server is straightforward; reproducing the Accept: text/markdown behaviour at the edge is not, because it depends on zone-level rules that the repository scripts but does not own.

The licence question deserves a plain statement rather than a recommendation. CC-BY-SA-4.0 requires attribution and imposes ShareAlike terms on adaptations. Quoting a paragraph in an internal design document and redistributing a modified version of the whole guide are different acts, and only your legal team can say which one you are doing. What the repository tells you is the licence and the fact that the content is one Markdown file, which makes the scope of any adaptation easy to see.

Editorial conclusion

Adopt CLI Guidelines if you are designing or reviewing a command-line tool and want a written position to argue against, and self-host it if you need an offline or internal copy. Skip it if you want runnable code, a linter or a conformance test suite; the repository holds prose, layouts and a build script, not a library. Before you rely on a fork, read the CC-BY-SA-4.0 terms and confirm whether the ShareAlike clause affects how you redistribute a modified guide, then run hugo server and check that content/_index.md is the only file you need to edit.

Frequently asked questions

Official sources

1. cli-guidelines/cli-guidelines on GitHub
2. Issues
3. License: CC-BY-SA-4.0
4. Project website
5. README