Remote Fetching

Boiler can fetch resources from anywhere - GitHub, GitLab, Bitbucket, your own website, or a direct URL. No lock-in, complete flexibility.

Two Commands for Remote Fetching

Command	Saves to local store?	Use case
`bl add ... -r`	✅ Yes - reusable later with `bl add <name>`	Team/personal registry, frequently reused resources
`bl use ...`	❌ No - one-shot fetch	Grab something once, no clutter

Supported Platforms

Boiler auto-detects the right provider from the URL:

Platform	Format	Archive
GitHub	`owner/repo` or `https://github.com/owner/repo`	tar.gz
GitLab	`https://gitlab.com/owner/repo`	tar.gz
Bitbucket	`https://bitbucket.org/owner/repo`	zip
Custom registry	`https://yoursite.com/boiler-store`	zip
Direct archive	`https://anysite.com/stack.zip` or `.tar.gz`	auto-detected

Understanding Formats

The colon (:) separates the source from the path inside it.

What You Want	Format	Example
Whole GitHub/GitLab/Bitbucket repo	`owner/repo` or full URL	`alice/my-stack`
File inside a GitHub repo	`owner/repo:path/to/file.js`	`alice/snippets:js/logger.js`
Custom domain file	`domain.com:path/file`	`mysite.com:snippets/util.js`
Direct file URL	`https://full-url`	`https://mysite.com/file.js`
Direct archive URL	`https://full-url.zip`	`https://mysite.com/stack.zip`

`bl add -r` - Fetch and Save

When you use -r, Boiler downloads and caches locally so you can reuse without re-downloading:

Downloads from internet
Saves to ~/.boiler/store/
Updates boiler.meta.json
Copies to your project

sequenceDiagram
  participant User
  participant CLI as Boiler CLI
  participant Remote as Remote Source
  participant Store as Local Store
  participant Project as Your Project

  User->>CLI: bl add express -r
  CLI->>Remote: Download resource
  Remote-->>CLI: Return files
  CLI->>Store: Save to ~/.boiler/store/
  CLI->>Store: Update boiler.meta.json
  Store-->>CLI: Resource cached
  CLI->>Project: Copy to current directory
  CLI-->>User: ✓ Added successfully

  Note over User,Project: Next time...

  User->>CLI: bl add express
  CLI->>Store: Check local store
  Store-->>CLI: Found (no download!)
  CLI->>Project: Copy to current directory
  CLI-->>User: ✓ Added (super fast!)

Examples

# From configured registry
bl add express@1 -r

# GitHub (short format)
bl add rishiyaduwanshi/boiler-express -r

# GitHub (full URL)
bl add https://github.com/alice/my-stack -r

# GitLab
bl add https://gitlab.com/alice/my-stack -r

# Bitbucket
bl add https://bitbucket.org/alice/my-stack -r

# GitHub subfolder as stack
bl add vercel/next.js:examples/blog -r

# GitHub single file (snippet)
bl add rishiyaduwanshi/boiler-snippets:js/errorHandler.js -r

# Direct URL
bl add https://mysite.com/snippets/helper.js -r

# Custom registry (one-time override)
bl add express@1 -r --registry https://github.com/myteam/boiler

`bl use` - One-Shot Fetch (No Store)

No -r flag, no local caching. Just fetch and use directly.

# GitHub repo
bl use alice/my-stack

# GitLab
bl use https://gitlab.com/alice/stack

# Bitbucket
bl use https://bitbucket.org/alice/stack

# Direct zip or tar.gz (any site)
bl use https://mysite.com/templates/express.zip
bl use https://mysite.com/stack.tar.gz

# Single file
bl use alice/snippets:js/errorHandler.js
bl use https://mysite.com/snippets/logger.js

# Into a specific folder
bl use alice/my-stack ./new-project

Using a Registry

Set once, use forever:

bl conf --set-registry https://github.com/rishiyaduwanshi/boiler
bl search express -r
bl add express@1 -r

One-time override:

bl add express@1 -r --registry https://github.com/myteam/boiler

sequenceDiagram
  participant User
  participant CLI as Boiler CLI
  participant Registry as Registry Repo
  participant Source as Resource Source
  participant API as Provider API
  participant Store as Local Store

  User->>CLI: bl add express@1 -r
  CLI->>Registry: GET store/boiler.meta.json
  Registry-->>CLI: {"stacks":{"express@1":"owner/repo"}}
  CLI->>API: Try subtree fetch (provider-specific)
  API-->>CLI: Files (or fallback required)
  CLI->>Source: Fallback archive download (if needed)
  Source-->>CLI: Return files
  CLI->>Store: Save + update boiler.meta.json
  Store-->>User: ✓ Resource ready

If a hosted repository archive contains Git LFS pointers, Boiler automatically falls back to a shallow Git clone and removes the repository metadata before storing the stack. This fallback requires both Git and Git LFS to be available.

Setting Up Your Own Registry

Any static file server works (GitHub Pages, Netlify, S3, your own VPS). Required structure:

<your-registry-url>/
└── store/
    ├── boiler.meta.json       ← resource index
    ├── stacks/
    │   ├── express.zip
    │   └── nextjs.zip
    └── snippets/
        ├── errorHandler@1.js
        └── logger@1.js

This is the same structure as the official Boiler registry on GitHub - consistent everywhere.

boiler.meta.json for GitHub/GitLab/Bitbucket registry

Values are owner/repo paths (provider is auto-detected from the configured registry URL):

{
  "stacks": {
    "express@1": "alice/boiler-express"
  },
  "snippets": {
    "errorHandler@1.js": "alice/boiler-snippets:js/errorHandler@1.js"
  }
}

boiler.meta.json for a custom/generic website

Values must be full download URLs since the tool cannot infer paths from a custom server:

{
  "stacks": {
    "express@1": "https://mysite.com/store/stacks/express.zip"
  },
  "snippets": {
    "errorHandler@1.js": "https://mysite.com/store/snippets/errorHandler@1.js"
  }
}

Then use it:

bl conf --set-registry https://mysite.com/store
bl add express@1 -r

Explore more