# Grip

> Python command-line server that renders local Markdown readme files through the GitHub Markdown API, with live refresh and HTML export.

Stars: 6.8k · Language: Python · License: MIT · Categories: Dev Tools

- Repository: https://github.com/joeyespo/grip
- Page: https://www.trmn.sh/tools/grip

## Install

- pip: `pip install grip`
- Homebrew: `brew install grip`

## Overview

Grip is a command-line server written in Python that renders a local readme or other Markdown file using the GitHub Markdown API. It uses GitHub rendering and styles to preview the file before pushing. Running `grip` in a repository starts a server on http://localhost:6419/, and the browser view updates when the file changes, without a manual refresh. The `-b` flag opens a browser tab automatically.

The CLI accepts a file, a port, a host, or combinations of these (e.g. `grip AUTHORS.md 80`, `grip . 0.0.0.0:80`). Relative URLs are supported, so other files in the directory can be viewed by path. `grip --export` bypasses the server and writes a single HTML file with styles and assets inlined, and `--no-inline` keeps styles external. Grip can read from stdin and write to stdout (`cat README.md | grip -`, `grip --export - | less`), and `--user-content` with `--context=user/repo` renders content as GitHub comments or issues.

Since rendering uses the GitHub API, unauthenticated use is subject to its hourly rate limit. Grip supports authenticating API requests with a personal access token. Settings such as HOST, PORT, API_URL (for GitHub Enterprise), AUTOREFRESH, CACHE_DIRECTORY and STYLE_URLS go in `~/.grip/settings.py`. A Python API (`serve`, `export`, `create_app`, which returns a Flask app) allows embedding it in other projects. It suits developers and documentation authors who want to check Markdown output before committing, or generate HTML from Markdown files or GitHub wikis.

### Installation

```bash
# via pip
pip install grip
```

```bash
# via Homebrew
brew install grip
```

## Alternatives

- [isort](https://www.trmn.sh/tools/isort.md): Python command line utility and library that sorts imports alphabetically and groups them into sections by type. (Python, 7.0k stars)
- [harlequin](https://www.trmn.sh/tools/harlequin.md): Terminal-based SQL IDE with database adapter support for DuckDB, SQLite, PostgreSQL, MySQL and dozens of other databases (Python, 6.5k stars)
- [Hatch](https://www.trmn.sh/tools/hatch.md): Python project manager covering builds, environments, Python distributions, testing, static analysis, version management, and publishing to PyPI. (Python, 7.3k stars)
- [Azure CLI](https://www.trmn.sh/tools/azure-cli.md): Microsoft's cross-platform command-line interface for managing Azure resources with az group/subgroup/command syntax, JMESPath queries, and tab completion. (Python, 4.7k stars)
- [tox](https://www.trmn.sh/tools/tox.md): Command-line virtual environment manager and test runner for Python that automates testing across environments and acts as a frontend to CI servers. (Python, 4.0k stars)

---

Canonical: https://www.trmn.sh/tools/grip
