Quick Start

Install Branded Short Links and deploy your first short link to Cloudflare Workers.

Before you begin, you'll need a Cloudflare account with a registered domain — Cloudflare offers domain registration at cost with no markup. You'll generate a Cloudflare API token during the Deploy step below.

Install

Install the package globally to use the bsl command anywhere:

npm install -g branded-short-links

Or run it directly without installing:

npx branded-short-links

Both branded-short-links and bsl are registered as CLI aliases — they do the same thing.

The first command that needs configuration copies the starter template included with the npm package to your platform config directory. Global and npx installs don't require a repository clone or a separately downloaded config.sample.json.

First-Time Setup

1. Launch the Interactive Menu

Run the CLI with no arguments to start the guided setup:

bsl

The interactive menu walks you through configuring settings, links, and trackers step by step.

2. Configure Settings

Select Settings from the main menu. You're prompted for three values:

• Worker name — The name of your Cloudflare Worker (e.g., branded-short-links).
• Base domain — The custom domain your short links live on (e.g., example.com).
• Show response output — Whether the landing page displays masked config for debugging. Keep this false in production.

3. Add Your First Link

Select Manage Links > Add from the menu. Each link maps a shortcode to a destination URL:

• Shortcode — The path segment after your domain (e.g., /github). Must start with /.
• HTTP response — The redirect status code: 301, 302, 303, 307, or 308.
• Redirect URL — The full destination URL (e.g., https://github.com/yourname).

You can also set an optional fallback URL that catches any request that doesn't match a configured shortcode.

4. Add Trackers (Optional)

Attach analytics trackers that fire server-side on every redirect. Supported types:

• GA4 — Google Analytics 4 Measurement Protocol
• Facebook — Meta Pixel PageView (noscript endpoint)
• PostHog — PostHog event capture
• ntfy — Push notifications via ntfy
• Reverse Proxy for ntfy — Push notifications through an ntfy-reverse-proxy endpoint
• Plain Text — Plain text webhook to any endpoint

See Trackers for setup details on each type.

5. Deploy

Run the deploy command from the interactive menu or directly:

bsl deploy

The deploy process validates your config, verifies Cloudflare API permissions, generates wrangler.toml, and deploys the worker. See Deployment for the full walkthrough.

What Happens Next

Once deployed, your short links are live:

Trackers are optional — you can deploy with an empty "trackers": [] array and add them later.