id          = "grip"
name        = "Grip"
homepage    = "https://github.com/joeyespo/grip"
description = "Grip is a command-line server application written in Python that uses the GitHub markdown API to render a local readme file."
executables      = ["grip"]

[dotfiles]

# Grip's official README says its persistent settings.py lives under ~/.grip.
# It can contain a GitHub password or personal access token, so the whole file
# is conservatively classified as a credential.
# https://github.com/joeyespo/grip/blob/master/README.md
paths  = []
secret = ["~/.grip/settings.py"]

[commands]
format = 1
label = "Preview or export Markdown"
description = "Serve a Markdown file or README as GitHub-rendered HTML, or export it to a file. GitHub credentials, API URL and user-content rendering options are left out."
quality = "ai-draft"
parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]
id = "help"
kind = "help"
url = "https://github.com/joeyespo/grip/blob/master/grip/command.py"
revision = "master 2026-10-27"
evidence = '''
Usage:
  grip [options] [<path>] [<address>]

Where:
  <path> is a file to render or a directory containing README.md (- for stdin)
  <address> is what to listen on, of the form <host>[:<port>], or just <port>

Options:
  --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.
  --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.
  --theme=<theme>   Theme to view markdown file (light mode or dark mode).
                    Valid options ("light", "dark"). Default: "light"
  --wide            Renders wide, i.e. when the side nav is collapsed.
'''

[[commands.field]]
id = "path"
label = "Markdown file or directory"
description = "File to render, or a directory containing README.md. Leave empty for the current directory."
type = "path"
position = 0
path = { kind = "any", role = "input", must_exist = true }
sources = ["help"]

[[commands.field]]
id = "address"
label = "Port or host:port (or output file with export)"
description = "Listen address such as 6419 or localhost:8080. With Export it is the output file instead."
type = "string"
position = 1
sources = ["help"]

[[commands.field]]
id = "browser"
label = "Open in browser"
type = "boolean"
option = ["--browser", "-b"]
sources = ["help"]

[[commands.field]]
id = "export"
label = "Export HTML instead of serving"
type = "boolean"
option = ["--export"]
sources = ["help"]

[[commands.field]]
id = "no_inline"
label = "Link styles instead of inlining"
description = "Only meaningful together with Export."
type = "boolean"
option = ["--no-inline"]
sources = ["help"]

[[commands.field]]
id = "theme"
label = "Theme"
type = "enum"
option = ["--theme"]
choices = [{ value = "light", label = "Light" }, { value = "dark", label = "Dark" }]
sources = ["help"]

[[commands.field]]
id = "title"
label = "Page title"
type = "string"
option = ["--title"]
sources = ["help"]

[[commands.field]]
id = "norefresh"
label = "Disable auto-refresh"
type = "boolean"
option = ["--norefresh"]
sources = ["help"]

[[commands.field]]
id = "wide"
label = "Wide layout"
type = "boolean"
option = ["--wide"]
sources = ["help"]

[[commands.field]]
id = "quiet"
label = "Quiet"
type = "boolean"
option = ["--quiet"]
sources = ["help"]

[[commands.task]]
id = "preview"
label = "Preview in browser"
set = { browser = [true] }
fields = ["path", "address", "browser", "theme", "norefresh"]
required = []

[[commands.task]]
id = "export"
label = "Export to HTML"
set = { export = [true] }
lock = ["export"]
fields = ["path", "address", "export", "no_inline", "theme", "title"]
required = ["path"]

[[commands.group]]
id = "basic"
label = "Basic"
fields = ["path", "address", "browser", "export", "theme"]

[[commands.group]]
id = "advanced"
label = "Advanced"
fields = ["no_inline", "title", "norefresh", "wide", "quiet"]