🐼 nptmpl - Distributed CLI Template Manager

nptmpl is a high-performance, distributed CLI template manager designed for professional software engineers. It automates boilerplate generation with a robust local registry, versioning, Jinja2-powered variable injection, and seamless remote HTTP/SSH registry support.

🌐 Public Registry

We host an official template registry for the community! Browse, search, and clone templates directly from our public instance.

• Web UI: https://nptmpl.nguyenpanda.com
• API Endpoint: https://nptmpl.nguyenpanda.com/api/v1/templates

✨ Features

• Distributed Registry: Host your own private registry with a Web UI and REST API.
• Enterprise-Grade Security: Built-in path traversal mitigation, automatic tarball memory limits (max 1MB payload inspection), and robust paramiko SSH policies.
• Blazing Fast Concurrency: Server runs SQLite operations within thread pools using Write-Ahead Logging (WAL) to guarantee non-blocking AsyncIO loops.
• Smart Compression: Optimized tar.gz archives preserving symlinks and permissions.
• Dynamic Injection: Full Jinja2 support for contents and paths, automatically skipping binary files.
• Visual Demo Previews: Attach demo images or PDFs to your templates for rich visual previews on the registry.
• Post-Clone Hooks: Automatically run shell commands after cloning.
• Auto-Discovery: Respects .gitignore and global patterns via pathspec.
• Modular CLI Architecture: Clean Command Pattern design for maintainability and extensibility.

🛠️ Installation & Setup

Option 1: Install via uv (Fastest)

nptmpl uses uv for lightning-fast installation.

uv tool install nptmpl

Option 2: Install via pip

If you don't use uv, you can install standardly from PyPI:

pip install nptmpl

Option 3: Install from Source

Ideal for development or contributing to nptmpl.

Using uv (Recommended):

# Clone the repository
git clone https://github.com/nguyenpanda/nptmpl
cd nptmpl

# Install as a global tool in editable mode
uv tool install --editable . --force

Using pip:

# Clone the repository
git clone https://github.com/nguyenpanda/nptmpl
cd nptmpl

# Install in editable mode
pip install -e .

2. Enable Tab Completion (Recommended)

# Install completion helper
uv tool install argcomplete

# Add to your ~/.zshrc or ~/.bashrc
eval "$(register-python-argcomplete nptmpl)"

📖 Usage Guide

1. Initialize a Template

nptmpl init ./my-project

2. Add to Local Registry

nptmpl add ./my-project web/starter

3. Clone and Render

nptmpl clone web/starter ./new-app --var project_name="My App"

Pinning a version

Append @<version> to any clone target. Without it, clone resolves to the highest semantic version available — so 1.10.0 wins over 1.9.0.

nptmpl clone web/[email protected] ./new-app          # local registry
nptmpl clone https://registry.example.com/api/v1/templates/web/[email protected] ./new-app

A pinned clone fetches that version's metadata as well as its archive, so the variable prompts and post-clone hooks are the ones that shipped with it.

4. Remote Operations

Push to server (requires authentication token):

nptmpl push web/starter https://registry.example.com

Search and clone from remote:

nptmpl search fullstack --remote https://registry.example.com
nptmpl clone https://registry.example.com/api/v1/templates/web/starter ./my-app
nptmpl clone https://registry.example.com/api/v1/templates/web/[email protected] ./my-app

The registry's web UI offers the same choice: the version picker on a template page sets ?v=<version>, and the download button follows it.

🏗️ Variable Injection (Jinja2)

nptmpl leverages the full power of Jinja2 to make your templates dynamic. It safely skips binary files to avoid corruption.

1. Define Variables

In your project's .nptmpl file (created via nptmpl init), define the variables you want to prompt for:

variables:
  project_name: "The human-readable name of your project"
  author_name: "The main developer's name"
  enable_docker: "Set to 'true' to include Dockerfile"

2. Use in File Content

Use the standard {{ variable_name }} syntax inside any file in your template:

# settings.py
PROJECT_NAME = "{{ project_name }}"
AUTHOR = "{{ author_name }}"

3. Use in Filenames & Directories

You can also use variables in the names of files and folders. For example:

• src/{{ project_name }}/main.py
• docs/{{ author_name }}_guide.md

4. Provide Variables via CLI

When cloning, use the --var (or -v) flag:

nptmpl clone web/starter ./my-new-app -v project_name="My Cool App" -v author_name="Alice"

If a variable is defined in .nptmpl but not provided via the CLI, nptmpl will interactively prompt you for its value.

🖼️ Visual Demo Previews

nptmpl supports attaching a visual demo (image or PDF) to your template. When published to a registry, this demo is rendered as a LIVE_PREVIEW on the template detail page — giving users an instant look at what the template produces.

How to use the demo attribute

Add the demo field to your .nptmpl configuration file. You can specify a single path, or a list of demos with optional descriptions (useful for showcasing different layouts or themes):

# .nptmpl
name: my-group/my-latex-report
version: 1.0.0
author: Your Name
description: A beautiful LaTeX report template.
languages:
  - latex
demo: 
  - path: media/1-col.png
    description: "Single Column Layout"
  - path: media/2-col.png
    description: "Two Column Layout"
tags:
  - report
  - academic

Supported Formats

Best Practices

• Include the demo file in your template directory (e.g., media/preview.png). It will be bundled into the .tar.gz archive on nptmpl push.
• Use a descriptive image: Screenshots of compiled output (PDF pages, rendered HTML, etc.) are ideal.
• Keep file sizes reasonable: The raw file endpoint caps at 10MB per file.
• If demo is not specified, no preview section is shown — the README is displayed directly.

⚙️ Configuration

nptmpl looks for ~/.config/nptmpl/config.yaml. See the exhaustive Configuration Guide for all available options.

core:
  store_path: "$HOME/.local/share/nptmpl/db"
  auth_token: "your-secure-api-token" # Required for pushing to server

defaults:
  author: "Your Name"
  email: "[email protected]"
  license: "MIT"

🐳 Self-Hosting the Registry

Run your own registry with Docker Compose:

git clone https://github.com/nguyenpanda/nptmpl
cd nptmpl

cp .env.example .env
# Fill in NPTMPL_SERVER_TOKEN, NPTMPL_SESSION_SECRET and NPTMPL_ADMIN_PASS.
# Compose refuses to start until all three are set.

docker compose up -d --build
curl -fsS http://localhost:9090/health

The registry lives entirely in the nptmpl-store volume — template archives and registry.db alike. docker compose down keeps it; docker compose down -v deletes it permanently.

Without Docker:

nptmpl server --host 0.0.0.0 --port 9090 --storage /var/lib/nptmpl-store

Full deployment reference — path layout, database location, backup and restore, nginx and systemd, the analytics API — is in the Server Setup Guide.

🏛️ Architecture

For developers contributing to nptmpl, see the Architecture Guide for component diagrams and sequence diagrams covering the CLI, server, and core engine.

📄 License

MIT License. See LICENSE for details.