YankRun User Guide

A CLI tool for smart template replacement in repositories and directories.

YankRun can run fully non-interactively, prompt in a terminal, or open a local web workbench for previewing template repos before writing files.

Short references:

Installation
Quick Start
Commands
Interactive Workbench
Values File Format
Transformation Functions
Configuration
Examples
Troubleshooting

Installation

Linux (AMD64)

curl -L https://github.com/AxeForging/yankrun/releases/latest/download/yankrun-linux-amd64.tar.gz | tar xz
sudo mv yankrun-linux-amd64 /usr/local/bin/yankrun
yankrun version

Linux (ARM64)

curl -L https://github.com/AxeForging/yankrun/releases/latest/download/yankrun-linux-arm64.tar.gz | tar xz
sudo mv yankrun-linux-arm64 /usr/local/bin/yankrun

macOS (Intel)

curl -L https://github.com/AxeForging/yankrun/releases/latest/download/yankrun-darwin-amd64.tar.gz | tar xz
sudo mv yankrun-darwin-amd64 /usr/local/bin/yankrun

macOS (Apple Silicon)

curl -L https://github.com/AxeForging/yankrun/releases/latest/download/yankrun-darwin-arm64.tar.gz | tar xz
sudo mv yankrun-darwin-arm64 /usr/local/bin/yankrun

Windows (PowerShell)

# Download
Invoke-WebRequest -Uri https://github.com/AxeForging/yankrun/releases/latest/download/yankrun-windows-amd64.zip -OutFile yankrun.zip

# Extract
Expand-Archive -Path yankrun.zip -DestinationPath .

# Move to PATH (adjust as needed)
Move-Item -Path yankrun-windows-amd64.exe -Destination C:\Windows\yankrun.exe

# Verify
yankrun version

From Source (Go 1.25+)

go install github.com/AxeForging/yankrun@latest

Or build manually:

git clone https://github.com/AxeForging/yankrun.git
cd yankrun
go build -o yankrun .
sudo mv yankrun /usr/local/bin/

Quick Start

Step 1: Create a values file

# values.yaml
variables:
  - key: APP_NAME
    value: MyApp
  - key: AUTHOR
    value: Your Name
  - key: VERSION
    value: 1.0.0

Step 2: Clone and template a repository

yankrun clone \
  --repo https://github.com/AxeForging/template-tester.git \
  --input values.yaml \
  --outputDir ./my-new-project \
  --verbose

Or inspect it interactively first:

yankrun serve --dir ./my-new-project --input values.yaml

Step 3: Check the output

cat ./my-new-project/README.md
# All [[APP_NAME]], [[AUTHOR]], [[VERSION]] placeholders are replaced!

Commands

`clone`

Clone a git repository and replace placeholders.

yankrun clone --repo <URL> --outputDir <DIR> [options]

All flags

Flag	Alias	Description	Default
`--repo`		Git URL (HTTPS or SSH)	required
`--outputDir`	`-o`	Output directory	required
`--input`	`-i`	Values file path (JSON/YAML)	-
`--startDelim`		Start delimiter	`[[`
`--endDelim`		End delimiter	`]]`
`--fileSizeLimit`		Skip files larger than	`3 mb`
`--prompt`	`-p`	Interactive mode (prompt for values)	`false`
`--processTemplates`	`--pt`	Process `.tpl` files	`false`
`--onlyTemplates`	`--ot`	Only process `.tpl` files	`false`
`--branch`	`-b`	Branch to clone	default branch
`--verbose`	`-v`	Show detailed output	`false`

Examples

# Basic clone with values
yankrun clone \
  --repo https://github.com/org/template.git \
  --input values.yaml \
  --outputDir ./new-project

# Interactive mode - will prompt for each placeholder
yankrun clone \
  --repo git@github.com:org/template.git \
  --outputDir ./new-project \
  --prompt

# Clone specific branch with custom delimiters
yankrun clone \
  --repo https://github.com/org/template.git \
  --branch develop \
  --input values.json \
  --outputDir ./new-project \
  --startDelim "{{" \
  --endDelim "}}"

# Clone and process .tpl files
yankrun clone \
  --repo https://github.com/org/template.git \
  --input values.yaml \
  --outputDir ./new-project \
  --processTemplates \
  --verbose

`template`

Apply replacements to an existing directory.

yankrun template --dir <DIR> [options]

All flags

Flag	Alias	Description	Default
`--dir`	`-d`	Directory to process	required
`--input`	`-i`	Values file path (JSON/YAML)	-
`--startDelim`		Start delimiter	`[[`
`--endDelim`		End delimiter	`]]`
`--fileSizeLimit`		Skip files larger than	`3 mb`
`--prompt`	`-p`	Interactive mode	`false`
`--processTemplates`	`--pt`	Process `.tpl` files	`false`
`--onlyTemplates`	`--ot`	Only process `.tpl` files	`false`
`--verbose`	`-v`	Show detailed output	`false`

Examples

# Basic templating
yankrun template --dir ./my-project --input values.yaml

# Interactive mode
yankrun template --dir ./my-project --prompt --verbose

# Skip large files
yankrun template --dir ./my-project --input values.yaml --fileSizeLimit "10 mb"

# Only process .tpl files
yankrun template --dir ./my-project --input values.yaml --processTemplates --onlyTemplates

`generate`

Interactively choose a template from your config and generate a new project.

yankrun generate [options]

All flags

Flag	Alias	Description	Default
`--template`	`-t`	Filter templates by name	-
`--branch`	`-b`	Branch to clone	default branch
`--outputDir`	`-o`	Output directory	prompted
`--input`	`-i`	Values file path	-
`--prompt`	`-p`	Interactive mode	`false`
`--verbose`	`-v`	Show detailed output	`false`
`--noCache`	`--nc`	Bypass cache, fetch fresh data	`false`

Examples

# Fully interactive
yankrun generate --prompt --verbose

# Filter templates and auto-select
yankrun generate --template "go-service" --outputDir ./new-service

# Dry run - shows cached placeholders without cloning
yankrun generate --template "go-service" --dryRun

# Force fresh data (skip cache)
yankrun generate --template "go-service" --noCache --outputDir ./new-service

# Non-interactive with values
yankrun generate \
  --template "api-template" \
  --branch main \
  --input values.yaml \
  --outputDir ./new-api

Caching: The generate command caches GitHub-discovered repos and template variables in ~/.yankrun/cache.yaml. Dry runs use cached data when available, avoiding re-cloning. Use --noCache to force fresh data.

`serve`

Open a local web workbench for local directories, direct clones, and configured templates.

yankrun serve --dir ./my-project --input values.yaml

The server binds to 127.0.0.1:17817 by default. It is intended for local use and shares the same parser, cloner, and replacer logic as the CLI commands.

All flags

Flag	Alias	Description	Default
`--dir`	`-d`	Directory for local scan/apply	-
`--input`	`-i`	Values file path	-
`--addr`		Listen address	`127.0.0.1:17817`
`--startDelim`	`--sd`	Template start delimiter	`[[`
`--endDelim`	`--ed`	Template end delimiter	`]]`
`--fileSizeLimit`	`--fl`	Skip files larger than this limit	`3 mb`
`--processTemplates`	`--pt`	Process `.tpl` files	`false`
`--onlyTemplates`	`--ot`	Only process `.tpl` files	`false`
`--dryRun`	`--dr`	Force preview-only mode	`false`
`--ignore`		Glob patterns to skip	-
`--verbose`	`-v`	Show detailed output	`false`

The workbench provides:

Local mode for a directory passed with --dir
Clone mode for SSH or HTTPS repositories
Generate mode for ~/.yankrun/config.yaml templates and GitHub-discovered templates
file-level placeholder trees so you can see what will change
evaluated transform previews, for example APP_NAME:toUpperCase -> MYAPP
idle refresh after value edits so previews stay current
editable delimiters in the browser — change the [[ ]] pair shown next to the directory path and click Set to rescan the whole workbench (Local, Clone, and Generate) with the new pair, no restart needed
saved presets stored in browser IndexedDB, searchable by repo/template/branch/output/value keys
preset JSON export/import for moving saved runs between browsers

`tui`

Open a preview-first terminal workflow for local directory templating.

yankrun tui --dir ./my-project --input values.yaml
yankrun tui --dir ./my-project --dryRun

The TUI is intentionally conservative: it scans, summarizes, previews the replacement count, and respects --dryRun before writing.

Interactive Workbench

Use serve when you want to inspect a template repo before writing it to disk, reuse values across repeated runs, or compare where placeholders appear.

Typical flow:

Start the server with an optional local directory and values file.
Use Local, Clone, or Generate mode.
If your files use a different delimiter pair, edit it next to the directory path and click Set to rescan — no restart needed.
Click Preview before applying.
Edit values; evaluated previews refresh after a short idle delay.
Restore prior work from the left preset rail when repeating a repo/template.

Delimiters set from the browser apply to every mode (Local, Clone, Generate) for the rest of the session; a rejected change (empty, identical, or overlapping delimiters) leaves the previous pair active and shows the reason in the notice banner.

For clone mode:

Repository URL: https://github.com/AxeForging/template-tester.git
Branch: main
Output directory: ./my-new-project

SSH URLs also work when your local environment has the needed SSH key or agent configured:

git@github.com:AxeForging/template-tester.git

Presets stay local to the browser unless exported manually as JSON.

`setup`

Configure YankRun defaults.

# Interactive setup
yankrun setup

# Show current config
yankrun setup --show

# Reset/delete config
yankrun setup --reset

Values File Format

YAML (Recommended)

# Directories to skip (optional)
ignore_patterns:
  - node_modules
  - dist
  - .git
  - vendor
  - __pycache__

# Variables to replace (required)
variables:
  - key: APP_NAME
    value: MyApplication

  - key: PACKAGE_NAME
    value: com.example.myapp

  - key: AUTHOR_NAME
    value: Jane Developer

  - key: AUTHOR_EMAIL
    value: jane@example.com

  - key: VERSION
    value: "1.0.0"

  - key: DESCRIPTION
    value: "A sample application"

  - key: LICENSE
    value: MIT

  - key: YEAR
    value: "2024"

JSON

{
  "ignore_patterns": ["node_modules", "dist", ".git"],
  "variables": [
    { "key": "APP_NAME", "value": "MyApplication" },
    { "key": "PACKAGE_NAME", "value": "com.example.myapp" },
    { "key": "AUTHOR_NAME", "value": "Jane Developer" },
    { "key": "AUTHOR_EMAIL", "value": "jane@example.com" },
    { "key": "VERSION", "value": "1.0.0" }
  ]
}

Key Behavior

Keys without delimiters are automatically wrapped: APP_NAME → [[APP_NAME]]
Keys with delimiters are used as-is: {{APP_NAME}} stays {{APP_NAME}}

Transformation Functions

Apply transformations to values using the colon syntax:

[[KEY:function]]
[[KEY:function1:function2]]

Available Functions

Function	Description	Example	Input → Output
`toUpperCase`	Convert to UPPERCASE	`[[NAME:toUpperCase]]`	`hello` → `HELLO`
`toLowerCase`	Convert to lowercase	`[[NAME:toLowerCase]]`	`HELLO` → `hello`
`toDownCase`	Alias for toLowerCase	`[[NAME:toDownCase]]`	`HELLO` → `hello`
`gsub(a,b)`	Replace `a` with `b`	`[[NAME:gsub(-,_)]]`	`my-app` → `my_app`

Chaining Functions

Functions are applied left-to-right:

[[PROJECT_NAME:gsub( ,-):toLowerCase]]

Input:  "My Cool Project"
Step 1: "My-Cool-Project"  (gsub replaces spaces with dashes)
Step 2: "my-cool-project"  (toLowerCase)
Output: "my-cool-project"

Examples in Templates

# [[PROJECT_NAME]]

Package: [[PACKAGE_NAME:toLowerCase]]
Constant: [[PACKAGE_NAME:toUpperCase]]
URL Slug: [[PROJECT_NAME:gsub( ,-):toLowerCase]]
Database: [[APP_NAME:gsub(-,_):toLowerCase]]_db

Configuration

YankRun stores configuration in ~/.yankrun/config.yaml.

Full Configuration Example

# Default delimiters for all commands
start_delim: "[["
end_delim: "]]"

# Default file size limit
file_size_limit: "3 mb"

# Pre-configured templates for `generate` command
templates:
  - name: "Go Microservice"
    url: "git@github.com:your-org/go-service-template.git"
    description: "Production-ready Go microservice"
    default_branch: "main"

  - name: "React Application"
    url: "https://github.com/your-org/react-template.git"
    description: "React + TypeScript + Vite starter"
    default_branch: "main"

  - name: "Python CLI"
    url: "git@github.com:your-org/python-cli-template.git"
    description: "Click-based Python CLI tool"
    default_branch: "main"

# GitHub auto-discovery (optional)
github:
  user: "your-username"
  orgs:
    - "your-org"
    - "another-org"
  topic: "template"           # Only repos with this topic
  prefix: "template-"         # Only repos starting with this
  include_private: true       # Include private repositories
  token: "ghp_xxxxxxxxxxxx"   # Required for private repos

Examples

Create a Go project from template

# go-values.yaml
variables:
  - key: MODULE_NAME
    value: github.com/myorg/myservice
  - key: SERVICE_NAME
    value: user-service
  - key: AUTHOR
    value: Platform Team
  - key: GO_VERSION
    value: "1.22"

yankrun clone \
  --repo git@github.com:myorg/go-template.git \
  --input go-values.yaml \
  --outputDir ./user-service \
  --verbose

Create a React app from template

# react-values.yaml
variables:
  - key: APP_NAME
    value: my-dashboard
  - key: APP_TITLE
    value: My Dashboard
  - key: DESCRIPTION
    value: Admin dashboard for managing users

yankrun clone \
  --repo https://github.com/myorg/react-template.git \
  --input react-values.yaml \
  --outputDir ./my-dashboard \
  --processTemplates \
  --verbose

Update version across a monorepo

# version-bump.yaml
variables:
  - key: OLD_VERSION
    value: "1.2.3"
  - key: VERSION
    value: "1.3.0"

# First, manually replace OLD_VERSION with [[VERSION]] placeholders
# Then run:
yankrun template \
  --dir ./packages \
  --input version-bump.yaml \
  --verbose

CI/CD pipeline usage

# .github/workflows/create-service.yml
name: Create Service
on:
  workflow_dispatch:
    inputs:
      service_name:
        description: 'Service name'
        required: true

jobs:
  create:
    runs-on: ubuntu-latest
    steps:
      - name: Create values file
        run: |
          cat > values.yaml << EOF
          variables:
            - key: SERVICE_NAME
              value: ${{ github.event.inputs.service_name }}
            - key: CREATED_BY
              value: ${{ github.actor }}
          EOF

      - name: Generate service
        run: |
          yankrun clone \
            --repo ${{ secrets.TEMPLATE_REPO }} \
            --input values.yaml \
            --outputDir ./output \
            --verbose

Troubleshooting

Placeholders not being replaced

Check delimiters match: Ensure your template uses [[KEY]] (or your custom delimiters)
Check key names match exactly: APP_NAME ≠ app_name
Use verbose mode: --verbose shows which files are processed
Check file size: Files over 3MB are skipped by default

yankrun template --dir ./project --input values.yaml --verbose

File being skipped

Files are skipped if:

They exceed --fileSizeLimit (default 3MB)
They're in ignored directories (.git, node_modules, vendor, etc.)
They're binary files

Increase the limit if needed:

yankrun template --dir ./project --input values.yaml --fileSizeLimit "50 mb"

Git clone fails

Check URL: Ensure the repo URL is correct
Check authentication: For SSH, ensure your key is loaded (ssh-add -l)
Check network: Ensure you can reach GitHub/GitLab

# Test git access directly
git clone https://github.com/org/repo.git /tmp/test-clone

Permission denied on install

Use sudo or install to a user directory:

# Option 1: Use sudo
sudo mv yankrun /usr/local/bin/

# Option 2: Install to user bin (add to PATH)
mkdir -p ~/.local/bin
mv yankrun ~/.local/bin/
export PATH="$HOME/.local/bin:$PATH"

Getting Help

Documentation: GitHub Repository
Issues: GitHub Issues
AI Reference: See docs/AI/README.md for technical details

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

YankRun User Guide

Table of Contents

Installation

Quick Start

Step 1: Create a values file

Step 2: Clone and template a repository

Step 3: Check the output

Commands

`clone`

`template`

`generate`

`serve`

`tui`

Interactive Workbench

`setup`

Values File Format

YAML (Recommended)

JSON

Key Behavior

Transformation Functions

Available Functions

Chaining Functions

Examples in Templates

Configuration

Full Configuration Example

Examples

Troubleshooting

Getting Help

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

YankRun User Guide

Table of Contents

Installation

Quick Start

Step 1: Create a values file

Step 2: Clone and template a repository

Step 3: Check the output

Commands

clone

template

generate

serve

tui

Interactive Workbench

setup

Values File Format

YAML (Recommended)

JSON

Key Behavior

Transformation Functions

Available Functions

Chaining Functions

Examples in Templates

Configuration

Full Configuration Example

Examples

Troubleshooting

Getting Help

`clone`

`template`

`generate`

`serve`

`tui`

`setup`