Documentation

Everything you need to deploy and manage static sites with bassh.

Installation

Install the CLI with a single command. Works on macOS and Linux.

curl -fsSL https://raw.githubusercontent.com/get-bassh/bassh-site/main/install.sh | bash
source ~/.zshrc  # or ~/.bashrc

This installs the bassh binary to ~/.local/bin.

Registration

Register with an invite code provided by your operator.

bassh register myusername --invite subdomain:secretcode

The invite code format is subdomain:secret where:

• subdomain — The operator's worker subdomain
• secret — The registration secret

Registration is one-time per machine. Your credentials are stored locally and tied to your hardware ID.

Quick Start

Deploy your first site in seconds:

# Navigate to your project
cd my-website

# Deploy it
bassh

Deploying 5 files...
✓ Site deployed successfully
https://myusername-my-website.pages.dev

Basic Deployment

Deploy the current directory or a specific folder.

# Deploy current directory
bassh

# Deploy a specific folder
bassh ./dist

# Deploy an absolute path
bassh /path/to/my-site

All HTML, CSS, JS, and asset files in the folder are deployed. The project name defaults to the folder name.

Project Naming

Use -n to set a custom project name.

bassh ./dist -n v2-preview

The URL becomes: https://username-v2-preview.pages.dev

Deploying to the same project name updates the existing site.

Custom Domains

Attach your own domain to a deployment.

bassh ./docs --custom-domain docs.example.com

After deployment, the CLI displays the DNS configuration you need:

Add this DNS record:
  Type:  CNAME
  Name:  docs
  Value: username-project.pages.dev

Root domains

For root domains (e.g., example.com instead of docs.example.com), use CNAME flattening or an ALIAS record if your DNS provider supports it.

Password Protection

Encrypt your site with a password using -p.

bassh ./dist -p "mysecretpassword"

How it works:

• Files are encrypted client-side with AES-256-GCM
• Key derived via PBKDF2 (100k iterations)
• Server never sees your password or unencrypted content
• Visitors enter the password in-browser to decrypt

Magic Links

Email-based access without sharing passwords. Visitors enter their email and receive a time-limited link using -o.

# Allow specific emails
bassh ./dist -o "alice@gmail.com,bob@company.com"

# Allow entire domain
bassh ./dist -o "@company.com"

How it works:

1. Visitor enters their email on the protected page
2. If the email matches the allowlist, a magic link is sent
3. Clicking the link decrypts and displays the content

Email Restrictions

Limit access to specific email addresses using -e.

# Single email
bassh ./dist -e "alice@example.com"

# Multiple emails (comma-separated)
bassh ./dist -e "alice@example.com,bob@example.com"

Visitors authenticate via Cloudflare Access—they receive a one-time code via email. No passwords to manage.

Domain Restrictions

Allow access to anyone with an email from a specific domain using -d.

bassh ./dist -d "@acme.com"

Anyone with an @acme.com email address can access the site after verifying via Cloudflare Access.

List Projects

View all your deployed projects.

bassh -l

Projects:
  my-website    https://user-my-website.pages.dev
  v2-preview    https://user-v2-preview.pages.dev
  docs          https://docs.example.com

Delete Projects

Remove a deployed project.

bassh -D -n my-project

This deletes the site from Cloudflare Pages. The action is immediate and irreversible.

Account Info

View your current identity and configuration.

# Show logged-in user
bassh me

User: myusername
API:  https://bassh.example.workers.dev

Delete Account

Remove your account and all deployed sites.

bassh uninstall

This deletes your registration and all projects. You'll need a new invite code to re-register.

API Key

Get your API key for automated deployments.

bassh key

SHARE_SITE_KEY=sk_abc123...

Store this securely. It grants full access to deploy and manage your projects.

Environment Variables

Configure the CLI via environment variables for CI/CD.

GitHub Actions

Deploy automatically on push to main.

# .github/workflows/deploy.yml
name: Deploy

on:
  push:
    branches: [main]

env:
  DEPLOY_DIR: "."
  PROJECT_NAME: "my-site"

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install bassh
        run: |
          curl -fsSL https://raw.githubusercontent.com/get-bassh/bassh-site/main/install.sh | bash
          echo "$HOME/.local/bin" >> $GITHUB_PATH

      - name: Deploy
        env:
          SHARE_SITE_API: ${{ secrets.SHARE_SITE_API }}
          SHARE_SITE_KEY: ${{ secrets.SHARE_SITE_KEY }}
        run: bassh ${{ env.DEPLOY_DIR }} -n ${{ env.PROJECT_NAME }}

Required secrets in your repo settings:

• SHARE_SITE_API — Your operator's worker URL
• SHARE_SITE_KEY — Your API key

Form Setup

Collect form submissions from your static sites. No backend required.

Point your HTML form's action to your project's form endpoint:

<form action="/form/my-project" method="POST">
  <input type="text" name="name" placeholder="Your name" required />
  <input type="email" name="email" placeholder="Email" required />
  <textarea name="message" placeholder="Message"></textarea>
  <button type="submit">Send</button>
</form>

Replace my-project with your project name. Form submissions are stored and accessible via the CLI.

Spam protection

Add a honeypot field to block bots. If this field has a value, the submission is rejected:

<input type="text" name="_honeypot" style="display:none" />

Limits

View Submissions

View form submissions from the command line.

# List all submissions for a project
bassh forms -n my-project

#1  2024-01-15 14:32
    name: Alice Smith
    email: alice@example.com
    message: Great work!

#2  2024-01-15 16:45
    name: Bob Jones
    email: bob@example.com
    message: Question about pricing...

Submission count

Get a quick count of submissions:

bassh forms -n my-project --count

12 submissions

Export Data

Export submissions in CSV or JSON format for analysis or backup.

# Export as CSV
bassh forms -n my-project --csv > submissions.csv

# Export as JSON
bassh forms -n my-project --json > submissions.json

Clear submissions

Delete all submissions for a project:

bassh forms -n my-project --clear

✓ Cleared 12 submissions

Claude Code Skill

Deploy HTML artifacts directly from Claude Code conversations. Generate a page, deploy it instantly—zero context switching.

Install the skill

curl -fsSL https://raw.githubusercontent.com/get-bassh/bassh-site/main/skill/deploy-artifact.md \
  -o ~/.claude/skills/deploy-artifact.md

Usage

In a Claude Code conversation, ask Claude to create HTML and deploy it:

Claude will generate the HTML, save it to a temp folder, and run bassh to deploy it. You get a live URL in seconds.

Operator Overview

Operators host the bassh infrastructure on their Cloudflare account. Users deploy sites without needing Cloudflare accounts—they just need an invite code from you.

What you'll set up:

• Cloudflare Worker — Handles API requests, user registration, and deployments
• KV Namespaces — Store user data and form submissions
• API Token — Grants the Worker permission to create Pages projects

Requirements:

• Cloudflare account (free tier works)
• Node.js 18+ installed
• 5 minutes

Quick Setup

The fastest way to get started. One script handles everything.

# Clone the repo
git clone https://github.com/get-bassh/bassh.git
cd bassh

# Run the setup script
./setup.sh

The script will:

1. Authenticate with Cloudflare (opens browser if needed)
2. Create KV namespaces for users and forms
3. Generate wrangler.toml configuration
4. Prompt for your API token
5. Configure registration mode (invite-only or open)
6. Deploy the Worker
7. Display your invite code to share with users

Manual Setup

If you prefer to understand each step or need custom configuration.

1. Install Wrangler

npm install -g wrangler
wrangler login

2. Clone the repository

git clone https://github.com/get-bassh/bassh.git
cd bassh

3. Create KV namespaces

npx wrangler kv namespace create USERS
⛅️ Created namespace "bassh-api-USERS" with id "abc123..."

npx wrangler kv namespace create FORMS
⛅️ Created namespace "bassh-api-FORMS" with id "def456..."

4. Update wrangler.toml

Replace the namespace IDs with yours:

[[kv_namespaces]]
binding = "USERS"
id = "your-users-namespace-id"

[[kv_namespaces]]
binding = "FORMS"
id = "your-forms-namespace-id"

5. Set secrets

# Required: Account ID
npx wrangler secret put CF_ACCOUNT_ID
> Enter value: your-32-char-account-id

# Required: API Token (see next section)
npx wrangler secret put CF_API_TOKEN
> Enter value: your-api-token

# Optional: Registration code for invite-only mode
npx wrangler secret put REGISTRATION_CODE
> Enter value: your-secret-code

6. Deploy

npx wrangler deploy
✓ Deployed bassh-api to https://bassh-api.yoursubdomain.workers.dev

Creating an API Token

The Worker needs an API token to create Pages projects and Access policies.

Step-by-step

1. Go to Cloudflare API Tokens
2. Click Create Token
3. Use the Edit Cloudflare Workers template
4. Add these additional permissions:
   • Account → Cloudflare Pages → Edit
   • Account → Access: Apps and Policies → Edit
5. Set Account Resources to your account
6. Click Continue to summary → Create Token
7. Copy the token (you won't see it again)

Managing Invite Codes

Control who can register on your bassh instance.

Invite-only mode

When you set REGISTRATION_CODE, users need an invite to register:

# Your invite code format
yoursubdomain:yoursecretcode

# Users register with
bassh register alice --invite yoursubdomain:yoursecretcode

Open registration

Without REGISTRATION_CODE, anyone with your Worker URL can register:

# Users set the API endpoint
export BASSH_API=https://bassh-api.yoursubdomain.workers.dev

# Then register
bassh register alice

Generating new invite codes

To change the invite code, update the secret:

npx wrangler secret put REGISTRATION_CODE
> Enter value: new-secret-code

Existing users are unaffected—only new registrations need the new code.

Email Routing (Optional)

Enable magic links (-o flag) for email-based site protection.

Requirements

• A domain with DNS on Cloudflare
• Email Routing enabled for that domain

Setup steps

1. In Cloudflare dashboard, go to your domain → Email → Email Routing
2. Click Enable Email Routing and follow the DNS setup
3. Set the sender email secret:

   npx wrangler secret put EMAIL_FROM
   > Enter value: access@yourdomain.com

4. Redeploy: npx wrangler deploy

Users can now protect sites with magic links:

bassh ./dist -o "alice@company.com,@trusted.com"

All Flags

All Commands