copy cli docs from render-engine into this repo

docs/README.md

@@ -0,0 +1 @@
+The docs at cli.md are loaded into the render-engine docs using mkdocs-multirepo plugin. Do not build/serve the docs directly here

docs/cli.md

@@ -0,0 +1,230 @@
+---
+title: "Render Engine CLI"
+description: "Guide to using Render Engine CLI for creating, building, and serving your site."
+date: August 22, 2024
+tags: ["render-engine", "cli", "site-setup", "build", "serve"]
+---
+
+Render Engine comes with a CLI that can be used to create, build, and serve your site.
+
+> !!! Note
+    The CLI is no longer a part of the Render Engine package and must be installed
+    separately. To install run `pip install render-engine-cli`. Render Engine can be
+    installed together with the CLI as well using
+    `pip install render-engine[cli]`.
+
+## pyproject.toml Configuration
+
+The Render Engine CLI can be configured through your `pyproject.toml` file to set default values and avoid
+repetitive command-line arguments.
+
+### Configuration Options
+
+- **module**: The Python module containing your Site class
+- **site**: The name of your Site class within the module
+- **collection**: Default collection name for the `new-entry` command
+
+### Example Configuration
+
+```toml
+[tool.render-engine.cli]
+module = "my_site"
+site = "MySite"
+collection = "posts"
+```
+
+With this configuration, commands that normally require `module:site` can be run without arguments:
+
+- `render-engine build` instead of `render-engine build my_site:MySite`
+- `render-engine serve` instead of `render-engine serve my_site:MySite`
+
+## CLI Commands
+
+### init
+
+Create a new Render Engine site from a template.
+
+```bash
+render-engine init [TEMPLATE] [OPTIONS]
+```
+
+**Arguments:**
+
+- `TEMPLATE`: Template URL or path (default: <https://github.com/render-engine/cookiecutter-render-engine-site>)
+
+**Options:**
+
+- `--extra-context, -e`: Extra context as JSON string
+- `--no-input`: Skip all prompts
+- `--output-dir`: Output directory (default: ./)
+- `--config-file, -c`: Path to cookiecutter config file
+
+**Examples:**
+
+```bash
+# Use default template
+render-engine init
+
+# Use custom template with no prompts
+render-engine init https://github.com/myuser/mytemplate --no-input
+
+# Provide extra context
+render-engine init --extra-context '{"project_name": "My Blog"}'
+```
+
+### build
+
+Build your static site.
+
+```bash
+render-engine build [MODULE:SITE] [OPTIONS]
+```
+
+**Arguments:**
+
+- `MODULE:SITE`: Module path and site class (e.g., `my_site:MySite`)
+
+**Options:**
+
+- `--clean, -c`: Remove output folder before building
+
+**Examples:**
+
+```bash
+# Basic build
+render-engine build my_site:MySite
+
+# Build with clean
+render-engine build my_site:MySite --clean
+
+# Using config defaults
+render-engine build
+```
+
+### serve
+
+Serve your site locally with auto-reload capability.
+
+```bash
+render-engine serve [MODULE:SITE] [OPTIONS]
+```
+
+**Arguments:**
+
+- `MODULE:SITE`: Module path and site class
+
+**Options:**
+
+- `--clean, -c`: Clean output folder before building
+- `--reload, -r`: Auto-reload on file changes
+- `--directory, -d`: Directory to serve (default: output)
+- `--port, -p`: Port number (default: 8000)
+
+**Examples:**
+
+```bash
+# Basic serve
+render-engine serve my_site:MySite
+
+# Serve with auto-reload on port 3000
+render-engine serve my_site:MySite --reload --port 3000
+
+# Clean build and serve
+render-engine serve my_site:MySite --clean --reload
+```
+
+### templates
+
+List available templates from installed themes.
+
+```bash
+render-engine templates [MODULE:SITE] [OPTIONS]
+```
+
+**Arguments:**
+
+- `MODULE:SITE`: Module path and site class
+
+**Options:**
+
+- `--theme-name`: Specific theme to list templates from
+- `--filter-value`: Filter templates by name
+
+**Examples:**
+
+```bash
+# List all templates
+render-engine templates my_site:MySite
+
+# List templates from specific theme
+render-engine templates my_site:MySite --theme-name bootstrap
+
+# Filter templates containing "post"
+render-engine templates my_site:MySite --filter-value post
+```
+
+### new-entry
+
+Create a new collection entry (blog post, page, etc.).
+
+```bash
+render-engine new-entry [MODULE:SITE] [COLLECTION] [FILENAME] [OPTIONS]
+```
+
+**Arguments:**
+
+- `MODULE:SITE`: Module path and site class
+- `COLLECTION`: Collection name (e.g., "blog", "pages")
+- `FILENAME`: Output filename for the new entry
+
+**Options:**
+
+- `--content`: Content string for the entry
+- `--content-file`: Path to file containing content
+- `--title`: Entry title
+- `--slug`: URL slug for the entry
+- `--args`: Additional metadata as key=value or key:value pairs
+- `--include-date`: Add today's date to the entry. NOTE: If this is set and a
+date is included in the `--args` the one from the `--args` will be used.
+
+**Examples:**
+
+```bash
+# Create a basic blog post
+render-engine new-entry my_site:MySite blog my-first-post.md --title "My First Post"
+
+# Create post with content
+render-engine new-entry my_site:MySite blog hello.md --content "Hello, world!" --title "Hello"
+
+# Create post from file with metadata
+render-engine new-entry my_site:MySite blog review.md \
+    --content-file draft.txt \
+    --title "Product Review" \
+    --args author="John Doe" \
+    --args category=reviews \
+    --args tags="product,tech"
+
+# Using slug
+render-engine new-entry my_site:MySite pages about.md \
+    --title "About Us" \
+    --slug "about-us"
+
+# With --include-date
+render-engine new-entry my_site:MySite pages about.md \
+    --include-date
+```
+
+**Notes:**
+
+- The `--args` option can be used multiple times
+- Arguments can use either `=` or `:` as separator
+- If `EDITOR` environment variable is set, the file opens automatically after creation
+- Cannot use both `--content` and `--content-file` options
+
+## Usage Tips
+
+1. **Configuration First**: Set up your `pyproject.toml` to avoid typing module:site repeatedly
+2. **Development Workflow**: Use `serve --reload` during development for instant feedback
+3. **Clean Builds**: Use `--clean` flag when switching between major changes
+4. **Template Discovery**: Use `templates --filter-value` to find specific template types
+5. **Batch Entry Creation**: Combine `new-entry` with shell scripts for bulk content creation