---
name: "grip"
section: "1"
platform: "linux"
package: "grip"
version: "4.6.1-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/grip"
---

# grip(1)

Preview GitHub Markdown files like Readme locally

## NAME

**grip** - Preview GitHub Markdown files like Readme locally

## SYNOPSIS

```
grip [options] [PATH] [ADDRESS]
```

## DESCRIPTION

**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.**

**Privacy notice: by default all documents will be sent to GitHub (Microsoft).**

## OPTIONS

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

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

- **--user-content**

  **Render as user-content like comments or issues.**

- **--context=\<repo\>**

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

- **--user=\<username\>**

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

- **--pass=\<password\>**

  **A GitHub password or auth token for API auth.**

- **--wide**

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

- **--clear**

  **Clears the cached styles and assets and exits.**

- **--export**

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

- **--no-inline**

  **Link to styles instead inlining when using --export.**

- **-b --browser**

  **Open a tab in the browser after the server starts.**

- **--api-url=\<url\>**

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

- **--title=\<title\>**

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

- **--norefresh**

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

- **--quiet**

  **Do not print to the terminal.**

- **-V, --version**

  **Version info.**

- **-h, --help**

  **Show help message and exit.**

## ENVIRONMENT VARIABLES

- **GRIPHOME**

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

- **GRIPURL**

  **The URL of the Grip server, "/\_\_/grip" by default.**

## EXAMPLES

**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 AUTHORS.md
```

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

**You can combine the previous examples:**

```
    $ grip AUTHORS.md 80
```

**Or specify a hostname instead of a port.:**

```
    $ grip CHANGES.md 0.0.0.0
```

**Or provide both:**

```
    $ grip . 0.0.0.0:80
```

**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 README.md --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 README.md --export --no-inline introduction.html
```

**Reading from stdin:**

```
    $ cat README.md | grip -
```

**Writing to stdout:**

```
    $ grip AUTHORS.md --export - | bcat
```

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

```
    $ cat README.md | 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

**Bugs should be reported as issues at the project's GitHub page:** **\<https://github.com/joeyespo/grip/issues\>**

## AUTHOR

**Grip is developed by Joe Esposito \<joe@joeyespo.com\>.**

**This man page was written by Tiago Ilieve \<tiago.myhro@gmail.com\> for the** **Debian distribution (but it may be used by others).**