# Bikeshed Documentation

## Living Standard, 19 December 2025

Locally-installed Bikeshed is invoked via the command-line. There’s a bunch of options, but you’ll only use a few in day-to-day use.

If you’ve installed Bikeshed via one of the standard local installs above, you can typically just type `bikeshed` in the folder where your `.bs` file lives and it’ll do its thing, automatically invoking the `spec` subcommand.

However, Bikeshed has a number of different subcommands, and both global and subcommand-specific flags that can be invoked.

### 3.1. Global Options

There are a few options that apply to many different options, so they’re specified before the individual commands:

`-h` or `--help`

  Shows the help message for the current command. Can be run without any command, like `bikeshed -h` to show the list of valid commands and the global flags, or after a command, like `bikeshed spec -h` to show the help text for that command in particular.

`--die-on = [ nothing | fatal | link-error | warning | lint | message | everything ]`

  Bikeshed categorizes errors into several categories, depending on their severity: clear mistakes are "fatal", errors in resolving autolinks are "link-error", things that look a little questionable but are totally okay to generate a document with are "warning", and things that just violate one of the opt-in lint checks are "lint". (The "message" level is for non-errors, like informing you that it’s updating its datafiles.)

  The `--die-on` flag controls which sorts of errors cause Bikeshed to fail to produce output and exit with a non-0 status (indicating the command failed).

  Possible values are "nothing", "fatal", "link-error", "warning", "lint", "message", and "everything", with each level including all previous levels. Defaults to "fatal".

  It can sometimes be useful to set this to "nothing" if you just need to push thru and generate a spec that happens to throw some unimportant errors you don’t have time to fix. The `-f` flag is a shorthand for this.

  Alternately, it can be useful to set it to a level stricter than "fatal" if you want to ensure that, for example, a CI build fails when link errors creep into your document, or if you just generally want to ensure that your document builds "cleanly", without any warnings at all.

  Note that this can also be controlled from within your document (or your group’s metadata) via the Die On metadata.

`--die-when = [ early | late ]`

  When Bikeshed encounters a disallowed error (per the `--die-on` value), it can either die immediately (`early`) so you can see the error and fix it without the rest of the document potentially being incorrect and throwing nonsensical errors; or it can wait until the end of processing (`late`) to die, so you can see all the errors without having to continually rerun the command.

  Either way, Bikeshed will exit with a non-zero status, and refuse to actually produce an output document.

  If unspecified, this defaults to `late`.

  (If using `late` and processing a document with many output messages, it might be useful to temporarily run it with `-q` or `-qq`, so you can focus on the more important messages first.)

  Note that this can also be controlled from within your document (or your group’s metadata) via the Die When metadata.

`-f` or `--force`

  A shorthand for `--die-on=nothing`.

`-q` or `--quiet`

  The `-q` flag suppresses one level of error messages. It can be passed multiple times to suppress additional levels, in the order "warnings", then "link errors", then "fatal errors".

`-s` or `--silent`

  The `-s` flag suppresses all console output from Bikeshed, regardless of source. (It’s more powerful than `-q`, as it’ll also suppresses things like the success/failure message.)

`-d` or `--dry-run`

  The `-d` flag prevents Bikeshed from actually writing anything to disk. It does everything else, just skips that final "save" operation.

`--print= [ plain | console | markup | json ]`

  Specifies how Bikeshed should output its messages.

  - `plain` prints as plain text.

  - `console` (the default) prints as plain text, but with console color codes to help (which look like jibberish if not viewed in a console).

  - `markup` prints the messages in a light markup structure (nominally XML, but I don’t go out of my way to double check that it’s valid; it’s definitely parseable as HTML).

  - `json` prints the messages as JSON.

`--no-update`

  By default, Bikeshed checks how old its data files are every time it runs, and automatically triggers an update (as if you ran `bikeshed update`) if they’re more than a few days old.

  If this is causing problems (for example, if something has gone wrong with the update service, or you are offline and don’t want to wait for the network to timeout), you can prevent it from doing the check with `--no-update`.

`--allow-nonlocal-files`
`--allow-execute`

  Bikeshed has the ability to include arbitrary files into your spec, and in a few cases the ability to execute shell commands or Python on your behalf (to allow for some extensions).

  By default, these are restricted: you can only include files from the spec’s own folder or subfolders, and arbitrary code execution is disallowed.

  If you trust the specs you are processing, and need these abilities, however, the restrictions can be relaxed by passing these flags.

### 3.2. `bikeshed spec`

The `spec` command is the most common one you’ll use. It turns a Bikeshed source file into an output HTML file. The rest of this document mostly describes how to format a source file for use with this command.

Most of the time you can just run `bikeshed spec` and things will "just work" as long as your source file has the `.bs` extension.

Relevant flags:

`--gh-token=TOKEN`

  If you’re using Inline GitHub Issues heavily, you might run into the GitHub rate limit. You can generate an OAuth token at https://github.com/settings/tokens and then pass it to Bikeshed via this flag to raise your limit considerably.

`-l` or `--line-numbers`

  If you’re having trouble locating the source of an error in your code, run Bikeshed with this flag and almost all errors will report the source line number they appear at (or somewhere very close - it’s per-element).

  This code is unfortunately forced to be fairly hacky, and has the potential to lightly corrupt your file (inserting extra debugging info into plain text that just happens to look like markup), so it automatically triggers a dry-run, as if you’d specified `--dry-run`. When you’re done debugging, just run again without this flag to actually get some output.

After any flags, you can optionally specify the input file path and output file path. Both of these can usually be omitted; if you omit the output file, it’ll just output to a file with the same name as the input file, but with the extension changed to `.html`; if you omit the input file, it’ll search thru the current directory and assume you want the first file with a Bikeshed extension (`.bs`).

If you want to feed Bikeshed from stdin or have it output to stdout, just use `-` as the appropriate filename.

### 3.3. `bikeshed watch`

The `watch` command is identical to the `spec` command, except it sets up a watcher and auto-rebuilds the spec every time it changes. With this turned on, you can edit with a simple save->refresh cycle, rather than having to do save->build->refresh.

It accepts all the same arguments as `spec`. (Tho using stdin/stdout might get a little weird.)

Use Ctrl-C to stop the watcher (or whatever key combo kills the currently running process in your console).

### 3.4. `bikeshed template`

The `template` command outputs a minimal "skeleton" document to stdout. It’s useful to get started with Bikeshed, without having to remember what all the required metadata is.

On a Linux-like command line, it should be used like:

    bikeshed template > index.bs

### 3.5. `bikeshed echidna`

The `echidna` command hooks into the W3C’s Echidna auto-publishing system, letting you publish W3C specs from the command-line, rather than having to go thru a staff contact.

Note: Currently, only Working Drafts (not including FPWD) and Candidate Recommendation Drafts can be published via Echidna.

It’s invoked similarly to `bikeshed spec`, with three required flags:

`--u USERNAME`

  Your W3C username

`--p PASSWORD`

  Your W3C password

`--decision DECISION_URL`

  A link to a publicly-visible message approving the publication of this draft.

There are some optional flags:

`--editorial`

  Marks the publication as an editorial update.

`--cc EMAILS`

  A comma-separated list of email addresses which the W3C will ping when the publication request is completed.

`--additional-directories [DIRECTORY ...]`

  By default, Bikeshed will look for directories named `images`, `diagrams`, and `examples`, and include them and their contents in the publication. This flag will override that list, letting you specify any number of files and/or folders that should be included with the publication.

`--self-contained`

  Conversely, this flag signals that the document doesn’t use anything external, so it shouldn’t include anything even if one of the default directories does exist.

`--just-tar`

  The Echidna service works by accepting an uncompressed TAR file of all the files that will be published. Passing this flag just constructs that TAR file and prints it to stdout, without actually contacting Echidna.

After the flags, you can optionally specify the input file path, just like for `bikeshed spec`; if omitted, it selects a file automatically in the same way.

Bikeshed then builds the spec normally, performs a little bit of fixup for common issues that PubRules complains about, and submits the spec to Echidna. It will print out a URL for you to check on the progress of your publication; it should complete in a few seconds.

Most likely you’ll have some PubRules errors when you check your progress; fix those (ask in irc.w3.org#pub for help if needed) then just run `bikeshed echidna` again.

Note: If auto-publishing via Travis CI, this Travis blog post about encrypted environment variables will be helpful for safely using your W3C password.

#### 3.5.1. Testing Publication Locally

Publishing via Echidna automatically does some "fixup" on your document, to fix some common errors that would make the doc fail the W3C’s PubRules check.

These fixes are controlled by the Prepare For TR metadata, so if you want to see precisely what your spec will look like when it’s published, add that to your metadata block manually.

If you want to go further, and see the actual TAR file that will be sent to the Echidna service, you can pass `--just-tar` to the command (and omit the authentication flags that are normally required). This will cause Bikeshed to create a file named `test.tar` in your current directory.

#### 3.5.2. Echidna Hooks

Bikeshed’s default publication behavior is usually sufficient, but if you need to customize it in some way, there are a few hooks you can use (assuming you can write Python). In an include file named `bs-extensions.include`, provide an implementation of the following methods (check the default version of this file for the default implementations, for the methods you don’t want to change):

`BSPrepTR(doc)`

  This method is called after processing is done, when the document is ready to be packed up and sent to Echidna. Here, you can perform whatever final post-processing is required.

  For example, the CSSWG EDs link to a stylesheet in the parent directory of the server they’re stored on. In their `BSPrepTR()`, they search for the link to that stylesheet, and update it to point to the current directory instead.
`BSPublishAdditionalFiles(files)`

  This method allows you to specify what files should be included in the publishing bundle. It must return an array of additional files/folders; each entry must either be a string, referring to a file/folder in the spec’s directory or subdirectories, or a tuple of 2 strings, the first of which points to a file outside the spec’s directory, and the second of which provides the path the file should have within the spec’s directory.

  The `files` value provides the default values, which you probably want to just extend, rather than fully replace. It defaults to `["images", "diagrams", "examples"]`, indicating that those folders, if present, will be included.

  For example, as stated in the example for `BSPrepTR()`, the CSSWG needs to include its stylesheet in with its specs. To do so, it just needs to add the entry `["../default.css", "default.css"]` to the `files` array, indicating that Bikeshed should grab the `default.css` file from the parent directory, and put it in the spec’s directory (in the bundle) with the same name.

### 3.6. `bikeshed update`

The `update` command updates Bikeshed’s datafiles, which it uses for autolinking and similar things. By default it’ll update all of its datafiles, but if you want to update only particular ones, you can pass any or all of the following flags:

- `--anchors` to update Bikeshed’s "anchor data" - a list of all the definitions and headers it knows about.

- `--biblio` to update Bikeshed’s bibliography database.

- `--caniuse` to update Bikeshed’s CanIUse.com information.

- `--link-defaults` to update Bikeshed’s manually-maintained list of special linking rules.

- `--test-suites` to update Bikeshed’s database of test-suite information from the Shepherd system.

- `--languages` to update Bikeshed’s database of language codes/names (used for the Translations metadata)

- `--wpt` to update Bikeshed’s database of WPT tests; see § 12 Testing Integration With WPT.

By default, Bikeshed’s update system relies on the Bikeshed-Data project, which preprocesses the various data sources directly into Bikeshed’s data formats, and prepares a manifest of changed files, letting Bikeshed quickly download only what it needs. However, this can be up to 10 minutes out of date (or longer, if the update process has fallen over); if you need absolutely up-to-date information right now, pass the `--skip-manifest` flag to force Bikeshed to do its full manual update process. (You can combine it with any of the flags above to only get the exact files you need.)

### 3.7. `bikeshed refs`

The `refs` command lets you search Bikeshed’s anchor database, letting you see what sort of things it’s looking at when doing autolinking. This can be very useful for debugging, or just for a quick check of where something is defined.

It’s flags are similar to the attributes used on autolinks:

- `--text=FOO` to specify the linktext you want to filter for

- `--type=FOO` to specify the link type

- `--for=FOO` to specify the for value

- `--spec=FOO` to specify the spec

- `--status=foo` to specify the status

- `--exact` to turn off the variations that Bikeshed applies to some link texts (such as looking for "book" when you search for "books"), and just search for the exact text you specified

Any or all of these flags can be specified, and Bikeshed will display all the refs it can find matching the criteria.

### 3.8. `bikeshed source`

The `source` command applies various transformations to the source document itself, rather than producing a separate output document. Its options are described in § 15 Source-File Processing: bikeshed source.

### 3.9. `bikeshed outline`

The `outline` command processes your document, then outputs an outline to stdout, listing the text of each heading along with its source line number and ID.

### 3.10. `bikeshed issues-list`

The `issues-list` command processes a plain-text document in an "issues-list" format pioneered by the CSSWG into an equivalent HTML version.

Relevant flags:

- `-t` outputs a template issues-list file to stdout, making it easier to start a new document without having to reference an old one to remember the format. Use it like `bikeshed issues-list -t > issues-19700101.txt`.

After the command you can pass the input and output filenames. As usual, one or both can be omitted: if you omit the output, it’ll write to a file with the same name as the input, but a `.html` extension; it you omit the input, it will look in the current folder for any files starting with "issues" and ending in ".txt", and then extract the digits from those filenames and select the one with the largest number. If you name your file as suggested above, with an ISO date, it’ll correctly always choose the latest issues list.

Define the issues-list format. The `-t` output is already more than enough to actually work with, but it would still be good to describe it more fully.

## Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with `class="example"`, like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with `class="note"`, like this:

Note, this is an informative note.