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

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