grip(1)

💅 grip(1) — the manual, but make it slay

okay bestie, welcome to grip(1) — yes, that's the manual page name, it's giving very "section 1, user commands" ✨. Sit down, grab a boba, and let me tell you about the absolute icon that is grip. 🫶

---

✨ NAME ✨

grip — preview your GitHub Markdown files locally, like your Readme but make it you. 🌸

---

🌈 SYNOPSIS 🌈

grip [options] [PATH] [ADDRESS]

---

💖 DESCRIPTION 💖

So. grip is a command-line server application written in Python, and what it does is it uses the GitHub markdown API to render a local readme file. The styles? Pulled directly from GitHub, babes. Which means you know exactly how it's gonna look when it goes live. No guessing, no vibes-based layout crises. 🎀

And the best part — literal magic — changes you make to the Readme are instantly reflected in the browser without needing a page refresh. Obsessed. 🔥

⚠️ Privacy notice: by default all documents will be sent to GitHub (Microsoft). Yeah. Heads up on that one, bestie. 👀

---

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

Then the flags, in all their glory:

• --user-content — Render as user-content, like comments or issues would be.
• --context=<repo> — The repository context. Only taken into account when you're using --user-content, so don't bother otherwise, fr.
• --user=<username> — A GitHub username, for API authentication. If you use it 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, then exits. Spring cleaning energy. 🧹
• --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 of inlining them, when using --export.
• -b, --browser — Open a tab in the browser after the server starts. Main character move. 👑
• --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. Sneaky but valid. 😌

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 💀

Found a bug? Bestie, don't suffer in silence. 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).

---

okay that's the whole thing, you're basically a grip expert now, no cap. 🦋 the page you just read is dated 28 October 2025, and in case you were wondering about the source — yeah, it's Debian's grip(1) manual, section 1, user commands, living its best life. go render something iconic. 💜 ✨