finder

README

finder

Finder is a lightweight command-line tool written in Go to locate projects and files based on predefined folder/file structure templates. It ships with 370+ built-in templates covering a huge range of technologies, frameworks, and services — and you can add your own without recompiling.

Current version: 0.3.17

Features

• Template-based search — find projects by folder/file structure using JSON5 templates (370+ built-in).
• Custom templates — drop .json5 files into ~/.finder/templates/ or ./.finder/templates/ and they are loaded automatically. User templates can override built-in ones.
• Regex support — use regular expressions in template patterns for advanced matching.
• Async search — searches all drives (Windows) or root / (Linux/macOS) in parallel for maximum speed.
• Caching — create and reuse a cache for significantly faster repeat searches.
• JSON output — pipe results into other tools with --json.
• Tag search — browse templates by tag (-t <tag>).
• Binary search — find executables in your $PATH (-b).
• File size & checksum validation — templates can require minimum/maximum file sizes and SHA-256/SHA-512 checksums.
• Command validation — templates can run a shell command after matching and filter by exit code.
• Web UI (findergen) — a built-in HTTP server for browsing, creating, and editing templates, viewing the cache, and more.
• Cross-platform — works on Windows, Linux, and macOS.

Requirements

• Go 1.18 or newer

Binaries

The repository contains several binaries:

Binary	Description
finder	Main CLI — search for projects and files using templates
findergen	HTTP server & web UI for template management, cache viewer, config editor
csf	Build helper — compile scripts, go install with CGO, git repo pack/restore
tester	Template test tool — validates template files

Installation

Build from source

go build ./cmd/finder

Or install directly (Go 1.18+):

go install github.com/shadowdara/finder/cmd/finder@latest

The produced binary is finder (on Windows finder.exe).

Build all binaries

# Windows
build.bat

# Linux / macOS
go build ./cmd/finder
go build ./cmd/findergen
go build ./cmd/tester

Or using make:

make          # debug build
make release  # release build with stripped symbols
make install  # build release + copy to /usr/local/bin

Usage

Basic search

finder <template-name>

Find Git repositories:

finder git

Commands

Command	Aliases	Description
finder <template>		Search for projects matching a template
finder check		Validate all built-in and custom templates
finder list	ls	List all available templates
finder tags	tag	Show all tags in the console
finder -t <tag>		Search for templates by tag
finder -b		Search for executables in your $PATH
finder cp		Print the path to the global config file
finder version	-v, v	Print the current version
finder template <name>	tpl	Search using an explicit template name

Global flags

Flag	Aliases	Description
--json	-j	Output results as JSON
--verbose	-vv	Enable verbose output

Cache flags

Flag	Aliases	Description
--cache	-c	Use the existing cache instead of searching
--create-cache	-cc	Create a new cache
--create-cache-db	-ccd	Create a Git database from cache data

Example

# Find all React projects
finder react

# Find with JSON output
finder --json react

# Create a cache for faster repeat searches
finder --create-cache git

# Use the cache
finder --cache git

# Find templates tagged with "python"
finder -t python

# List all templates
finder list

Templates

Built-in templates

370+ templates are shipped in templates/ and compiled into internal/templates/. They cover frameworks, languages, databases, CI/CD systems, cloud services, AI/ML tools, and much more.

Template format

Templates are JSON5 files. A minimal template:

{
  name: "*",
  folders: [{ name: ".git" }],
}

A full template with all supported fields:

{
  min_version: "0.3.6",
  description: "My Custom Project Type",
  name: "*",
  tags: ["node", "typescript"],
  folders: [
    {
      name: "src",
      folders: [],
      files: ["index.ts"],
    },
  ],
  files: [
    "package.json",
    {
      name: "*.ts",
      existence: "required",
      size: {
        min: 1,
        min_size_type: "KB",
      },
    },
  ],
  command: "",
  invert_command: false,
  size: {
    min: 10,
    min_size_type: "KB",
  },
}

Custom templates

Place your own .json5 template files in:

OS	Path
Windows	%USERPROFILE%\.finder\templates\
Linux	~/.finder/templates/
macOS	~/.finder/templates/

Or in the project-local directory:

./.finder/templates/

User templates take precedence over built-in templates with the same name. See CUSTOM_TEMPLATES.md for the full guide.

Pattern matching (exact, regex, glob)

Since v0.3.17, every name pattern in a template — the top-level name, every file name, and every folder name (including nested folders) — is resolved by a 3-tier matching strategy:

Priority	Method	Applies when
1	Exact string equality	pattern equals the name verbatim
2	Go regex (regexp.MatchString)	pattern compiles as a valid regex (RE2)
3	Glob (path.Match)	pattern is not a valid regex (e.g. *.ts)

This means:

• "src" → exact match
• "^project-[0-9]+$" → valid regex, matches project-123, project-42, …
• "*.ts" → not a valid regex → glob fallback, matches any .ts file
• "^(main|app|server)\.py$" → valid regex, matches exactly main.py, app.py, or server.py

Regex patterns work in all name fields:

// top-level name: match folder names like project-42, project-99
{
  name: "^project-[0-9]+$",
  min_version: "0.3.17",
  files: [
    {
      // file name: match exactly main.py, app.py, or server.py
      name: "^(main|app|server)\\.py$",
      existence: "required",
    },
  ],
  folders: [
    {
      // folder name: match src, lib, or pkg
      name: "^(src|lib|pkg)$",
    },
  ],
}

Note: Go regex is RE2 — no backreferences and no lookahead/lookbehind. If your pattern uses unsupported syntax, it fails to compile and falls back to glob matching.

If your template relies on regex patterns, set "min_version": "0.3.17" to indicate the minimum Finder version required.

Config

Since v0.3.15, finder has a global config file at ~/.finder/config.json5. If the file does not exist, defaults are used:

{
  port: 8080,
  cache: false,
  create_cache_db: false,
  finder_instances: 8,
}

Key	Type	Default	Description
port	int	13420	HTTP server port for findergen
cache	bool	false	Enable cache by default
create_cache_db	bool	false	Create a Git database from cache data
finder_instances	int	8	Max parallel instances when creating cache

For a visual config editor, visit https://shadowdara.github.io/finder/configeditor.

Web UI (findergen)

findergen starts a local HTTP server with a web interface for:

• Template Creator — create and edit JSON5 templates visually
• Template Viewer — browse all built-in and custom templates
• Config Editor — edit config.json5 through the browser
• Cache Viewer — inspect cached search results
• Regex Creator — build and test regular expressions for templates
• Minecraft World Dashboard — view Minecraft worlds from the cache

# Start the web UI on the default port
./findergen

# Use a custom port
./findergen --port 3000

# Collect Minecraft worlds from cache
./findergen worlds

Project structure

finder/
├── cmd/
│   ├── finder/          # Main CLI binary
│   ├── findergen/       # Web UI server binary
│   ├── csf/             # Build helper binary
│   └── tester/          # Template test binary
├── internal/
│   ├── bt/              # Build tools (script compiler, git repo)
│   ├── cache/           # Cache system & Git DB
│   ├── cli/             # CLI command handling
│   ├── config/          # Configuration loading
│   ├── finderversion/   # Version constants
│   ├── history/         # Search history
│   ├── loader/          # File loading utilities
│   ├── mcapp/           # Minecraft world data
│   ├── search/          # Core search logic & binary check
│   ├── structure/       # Folder/template structure parsing
│   └── templates/       # Compiled templates + loader
├── pub/
│   ├── argparser/       # Argument parsing library
│   ├── color/           # Terminal color utilities
│   ├── fsd/             # Filesystem directory utilities
│   ├── goansi/          # ANSI escape codes
│   ├── json5/           # JSON5 parser
│   └── version/         # Semantic version comparison
├── templates/           # Source JSON5 templates (370+)
└── finder-template-generator-ssg/  # Static site generator for docs

Development

Run tests

go test ./...

Generate coverage report

go test -coverprofile=coverage ./...
go tool cover -html=coverage

Build

go build ./cmd/finder

Validate templates

go run ./cmd/finder check

List all templates

go run ./cmd/finder list

Contributing

• Found a missing or inaccurate template? Please open an issue.
• Add new templates via PR. Keep them in JSON5 and provide a short description of what the template matches.
• Feel free to contribute code improvements or new features.

Roadmap

• Temporary templates via command-line arguments
• Template schema validation
• Improved search history
• Extended web UI features

License

See LICENSE.

---

Project: https://github.com/shadowdara/finder Website: https://shadowdara.github.io/finder

Extra Info

The Project fs-tools was more or less the prototype for finder.

Info Video

(a Youtube Video)