YankRun

Template smarter: clone repos and replace tokens safely with size limits, custom delimiters, and JSON/YAML inputs.

Features

• Template values replacement across a directory tree
• Git clone with post-clone templating
• Custom delimiters with smart wrapping
• Size-based skipping (default 3 MB)
• Verbose reporting
• JSON/YAML inputs and ignore patterns
• Transformation functions (toUpperCase, toLowerCase, gsub)
• Template file processing (.tpl files processed and renamed)

Install

From Release

Linux/macOS (AMD64)

curl -L https://github.com/brasa-ai/yankrun/releases/download/stable/yankrun-linux-amd64.tar.gz -o yankrun-linux-amd64.tar.gz
tar -xvf yankrun-linux-amd64.tar.gz yankrun-linux-amd64
chmod +x yankrun-linux-amd64
sudo mv yankrun-linux-amd64 /usr/local/bin/yankrun

GitHub discovery config

You can auto-discover template repos from your GitHub user and/or orgs. All fields are optional; using only orgs is fine.

# ~/.yankrun/config.yaml (excerpt)
github:
  orgs: ["brasa-ai", "your-org"]          # one or more orgs (optional)
  user: "your-user"                         # your GitHub user (optional)
  topic: "templates"                        # filter repos by topic (optional)
  prefix: "template-"                       # filter repos by name prefix (optional)
  include_private: true                      # include private repos (requires token)
  token: "GITHUB_TOKEN"                      # optional; for higher rate limits/private

Notes:

• If nothing is configured yet, yankrun generate will ask for user/orgs inline and save them.
• When both user and orgs are set, results are merged.

Reset configuration

yankrun setup --reset

Deletes ~/.yankrun/config.yaml.

Linux/macOS (ARM64)

curl -L https://github.com/brasa-ai/yankrun/releases/download/stable/yankrun-linux-arm64.tar.gz -o yankrun-linux-arm64.tar.gz
tar -xvf yankrun-linux-arm64.tar.gz yankrun-linux-arm64
chmod +x yankrun-linux-arm64
sudo mv yankrun-linux-arm64 /usr/local/bin/yankrun

Windows (PowerShell)

Invoke-WebRequest -Uri https://github.com/brasa-ai/yankrun/releases/download/stable/yankrun-windows-amd64.zip -OutFile yankrun-windows-amd64.zip
Expand-Archive -Path yankrun-windows-amd64.zip -DestinationPath .
Move-Item -Path yankrun-windows-amd64/yankrun-windows-amd64.exe -Destination yankrun.exe

From Source

Build locally

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

Or install with Go:

go install github.com/brasa-ai/yankrun@latest

Usage

Clone & replace (interactive and non-interactive)

# Non-interactive: provide values via --input
yankrun clone \
  --repo https://github.com/brasa-ai/template-tester.git \
  --input examples/values.json \
  --outputDir ./clonedRepo \
  --verbose

# Interactive: prompt for discovered placeholders after clone
yankrun clone \
  --repo git@github.com:brasa-ai/template-tester.git \
  --outputDir ./clonedRepo \
  --prompt --verbose

What it does:

• Clones the repository
• Scans for placeholders between your delimiters (defaults: [[, ]])
• If -p/--prompt is set, shows a summary and prompts for values; otherwise uses values from -i if provided
• Applies replacements and logs completion

Options:

• --repo: Git URL to clone
• --input: JSON/YAML with variables (used in non-interactive or as defaults in interactive)
• --outputDir: directory to clone into
• --fileSizeLimit: skip files larger than this (default 3 mb)
• --startDelim: template start delimiter (default [[)
• --endDelim: template end delimiter (default ]])
• --prompt (alias: --interactive): ask for values before applying
• --processTemplates (alias: --pt): process .tpl files by evaluating templates and removing .tpl suffix
• --onlyTemplates (alias: --ot): when used with --processTemplates, only process .tpl files and ignore all other files

Generate (choose template repo & branch)

# Configure templates in ~/.yankrun/config.yaml
# templates:
#   - name: "Go App"
#     url: "git@github.com:brasa-ai/template-tester.git"
#     description: "Example templates"
#     default_branch: "main"

# Run interactive generator
yankrun generate --prompt --verbose

# Non-interactive values file and custom delimiters
yankrun generate --input examples/values.json --startDelim "[[{" --endDelim "}]]" --fileSizeLimit "5 mb"

What it does:

• Loads configured templates from ~/.yankrun/config.yaml
• Lets you choose a template and branch
• Clones the selected branch
• Removes .git so you start a fresh repo
• Scans placeholders, optionally prompts (-p), then applies replacements

Template command (interactive)

# Analyze placeholders and prompt for values
yankrun template --dir ./examples/project --prompt

# Use defaults or overrides (YAML values)
yankrun template --dir ./examples/project --input examples/values.yaml --startDelim "[[{" --endDelim "}]]" --fileSizeLimit "5 mb" --prompt --verbose

What it does:

• Scans --dir for placeholders between your delimiters (defaults: [[, ]]).
• Shows a summary of each placeholder with how many matches were found.
• Pre-fills values from -i if provided; prompts for missing ones.
• Applies replacements across the directory and prints a completion message.

Template File Processing

YankRun can process .tpl files by evaluating their template content and removing the .tpl suffix. This is useful when you have template files that should be processed and renamed.

# Process .tpl files in addition to regular templating
yankrun template --dir ./project --input values.json --processTemplates --verbose

# Clone and process .tpl files
yankrun clone --repo https://github.com/user/template.git --input values.yaml --processTemplates

# Process ONLY .tpl files (ignore all other files)
yankrun template --dir ./project --input values.json --processTemplates --onlyTemplates --verbose

What it does:

• Finds all files ending with .tpl in the target directory (recursively)
• Evaluates template placeholders in these files using the same replacement logic
• Creates new files without the .tpl suffix containing the processed content
• Removes the original .tpl files
• Skips .tpl files in ignored directories (.git, node_modules, vendor, etc.)

Example:

• README.tpl → README (with placeholders replaced)
• config.tpl → config (with placeholders replaced)
• src/main.tpl → src/main (with placeholders replaced)

The --processTemplates flag is optional and defaults to false to maintain backward compatibility.

Note: The --onlyTemplates flag requires --processTemplates to be set. When used together, YankRun will skip processing all non-.tpl files and only process template files.

Configuration

Interactive setup

# Create or update ~/.yankrun/config.yaml
yankrun setup

# Example session
Template start delimiter [[]: [[
Template end delimiter ]]: ]]
File size limit (e.g. 3 mb) [3 mb]: 3 mb

Flags always override config defaults if provided.

Show current config

yankrun setup --show

Outputs:

start_delim: [[
end_delim: ]]
file_size_limit: 3 mb

Input file format

JSON (see `examples/values.json` in the tester repo)

{
  "ignore_patterns": ["node_modules", "dist"],
  "variables": [
    { "key": "APP_NAME", "value": "TemplateTester" },
    { "key": "PROJECT_NAME", "value": "DemoProject" },
    { "key": "USER_NAME", "value": "axebyte" },
    { "key": "USER_EMAIL", "value": "user@example.com" },
    { "key": "VERSION", "value": "1.0.0" }
  ]
}

Notes:

• If your keys do not include delimiters, YankRun wraps them using your configured delimiters. For example, with start [[ and end ]], APP_NAME becomes [[APP_NAME]].
• If your keys already include delimiters, they are used as-is.

YAML (see `examples/values.yaml` in the tester repo)

ignore_patterns: [node_modules, dist]
variables:
  - key: APP_NAME
    value: TemplateTester
  - key: PROJECT_NAME
    value: DemoProject
  - key: USER_NAME
    value: axebyte
  - key: USER_EMAIL
    value: user@example.com
  - key: VERSION
    value: "1.0.0"

Examples

Set custom delimiters per run

yankrun clone --repo git@github.com:brasa-ai/template-tester.git --input examples/values.yaml --outputDir out --startDelim "[[{" --endDelim "}]]"

Skip large files

yankrun clone --repo git@github.com:brasa-ai/template-tester.git --input examples/values.json --outputDir out --fileSizeLimit "10 mb"

Verbose replacement report

yankrun clone --repo <repo> --input example.json --outputDir out --verbose

Why YankRun? Practical problems it solves

1) Bootstrap a new project from a template

Problem: You maintain a template repo (CI, lint, base code). You want to create a new project with your org/app names filled in, without carrying over the template’s git history.

Solution:

# Choose template + branch, clone, remove .git, scan tokens, fill values
yankrun generate --prompt --verbose

Outcome: Fresh repo with placeholders (e.g., [[NAME]], [[PROJECT_NAME]]) replaced and no template history.

2) Rollout org-wide config changes across many files

Problem: You have dozens of files with tokens for company, team, emails, or versions. Manual search/replace is error-prone.

Solution:

# Define values once
cat > values.json << 'EOF'
{
  "variables": [
    { "key": "COMPANY", "value": "Acme Corp" },
    { "key": "TEAM", "value": "Platform" },
    { "key": "VERSION", "value": "2.1.0" }
  ]
}
EOF

# Apply everywhere safely with size limits
yankrun template --dir . --input values.json --fileSizeLimit "5 mb" --verbose

Outcome: Consistent updates with a per-file replacement report, skipping large/binary files.

3) Customize a sample app quickly (no prompts)

Problem: You want a non-interactive pipeline (CI/CD) to stamp out a project with predetermined values.

Solution:

yankrun clone \
  --repo git@github.com:brasa-ai/template-tester.git \
  --input examples/values.json \
  --outputDir ./my-app \
  --startDelim "[[{" --endDelim "}]]" \
  --verbose

Outcome: Fully templated project ready for commit in automated flows.

Transformation Functions

YankRun supports transformation functions that can be applied to placeholders to modify their values. For more details, see the Transformation Functions documentation.