Preview GitHub-flavoured Markdown files locally.


Start the server and serve the rendered README file of a current directory

$ grip

Start the server and serve a specific Markdown file
$ grip [path/to/]

Start the server and open the README file of the current directory in the browser
$ grip --browser

Start the server in the specified port and serve the rendered README file of the current directory
$ grip [port]


grip [options] [PATH] [ADDRESS]


Grip is a command-line server application written in Python that uses the GitHub markdown API to render a local readme file. The styles come directly from GitHub, so you'll know exactly how it will appear. Changes you make to the Readme will be instantly reflected in the browser without requiring a page refresh.


PATH is a file to render or a directory containing Use - for stdin.

ADDRESS is what to listen on, of the form HOST[:PORT], or just PORT


Render as user-content like comments or issues.


The repository context, only taken into account when using --user-content.


A GitHub username for API authentication. If used without the --pass option, an upcoming password input will be necessary.


A GitHub password or auth token for API auth.


Renders wide, i.e. when the side nav is collapsed.


Clears the cached styles and assets and exits.


Exports to <path>.html or instead of serving, optionally using [<address>] as the out file (- for stdout).


Link to styles instead inlining when using --export.

-b --browser

Open a tab in the browser after the server starts.


Specify a different base URL for the github API, for example that of a Github Enterprise instance. Default is the public API:


Manually sets the page's title. The default is the filename.


Do not automatically refresh the Readme content when the file changes.


Do not print to the terminal.

-V, --version

Version info.

-h, --help

Show help message and exit.



Specify an alternative location, "~/.grip" by default.


The URL of the Grip server, "/__/grip" by default.


To render the readme of a repository:

    $ grip

Now open a browser and visit http://localhost:6419. Or run with -b and Grip will open a new browser tab for you.

You can also specify a port:

    $ grip 80

Or an explicit file:

    $ grip

Alternatively, you could just run grip and visit http://localhost:6419/ since Grip supports relative URLs.

You can combine the previous examples:

    $ grip 80

Or specify a hostname instead of a port.:

    $ grip

Or provide both:

    $ grip .

You can even bypass the server and export to a single HTML file, with all the styles and assets inlined:

    $ grip --export

Control the output name with the second argument:

    $ grip --export readme.html

If you're exporting a bunch of files, you can prevent styles from being inlined to save space with --no-inline:

    $ grip --export --no-inline introduction.html

Reading from stdin:

    $ cat | grip -

Writing to stdout:

    $ grip --export - | bcat

And both is also supported, allowing you to use Grip with other programs:

    $ cat | grip --export - | less

Rendering as user-content like comments and issues is also supported, with an optional repository context for linking to issues:

    $ grip --user-content --context=joeyespo/grip


Bugs should be reported as issues at the project's GitHub page: <>


Grip is developed by Joe Esposito <>.

This man page was written by Tiago Ilieve <> for the Debian distribution (but it may be used by others).

Copied to clipboard