Bikeshed Documentation

Living Standard,

3. Invoking Bikeshed Locally

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:

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:

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:

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.

← 2 Invoking Bikeshed Without Installing Table of Contents 4 Metadata →

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 21 January 2026, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.