ShellBot Website

Build and deploy micro apps and websites on Cloudflare Workers with production-grade design.

Arguments

• - Command: $0 (create | deploy | domain | provision | secrets | status | teardown)
• Arg 1: $1 (template name, resource type, domain, etc.)
• Arg 2+: $2, $3, etc.
• All args: INLINECODE11

Authentication

Two authentication methods, checked in this order:

Method 1: API Token (recommended, required for agents/CI)

Set CLOUDFLARE_API_TOKEN environment variable. This is the primary method — it takes precedence over OAuth if both are present.

If any command fails with authentication errors, tell user:
CODEBLOCK0

Method 2: OAuth via wrangler login (fallback for local use)

If CLOUDFLARE_API_TOKEN is not set, attempt OAuth login:

CODEBLOCK1

This opens a browser for Cloudflare OAuth. When running in an agent context:

1. 1. Run wrangler login — it will print an authorization URL to stdout
2. Show the URL to the user and ask them to open it in their browser
3. The user authorizes in the browser, which redirects to INLINECODE37
4. Wrangler receives the callback and stores OAuth tokens in INLINECODE38

Limitation: This only works when the agent runs on the user's local machine (the OAuth callback must reach localhost:8976). It will NOT work in remote/CI environments — use API token there.

After login, verify with:
CODEBLOCK2

Auth check order in scripts

All scripts check CLOUDFLARE_API_TOKEN first. If not set, they check if wrangler whoami succeeds (meaning OAuth tokens exist in ~/.wrangler/config/default.toml). If neither works, they error with instructions for both methods.

Optional: Account ID

INLINECODE43 — auto-detected by wrangler. Set it to skip the account selection prompt when multiple accounts exist.
CODEBLOCK3

Prerequisites

• - Node.js v20+
• Wrangler: npm install -g wrangler or use INLINECODE45

Verify setup:
CODEBLOCK4

Non-Interactive Design

All scripts run fully non-interactively — no prompts, no user input required. This makes them safe for agent invocation. Destructive operations require explicit --force flags instead of confirmation prompts.

Quick Start

CODEBLOCK5

Project Scaffolding

Default Templates

CODEBLOCK6

See references/cf-templates.md for the full catalog of 36+ templates.

Custom Template URL

CODEBLOCK7

Deployment

CODEBLOCK8

The deploy.sh script pre-checks that wrangler config exists and CLOUDFLARE_API_TOKEN is set before deploying.

Custom Domains

Three approaches to connect a custom domain to a CF Worker. See references/custom-domains.md for the full guide.

1. Automated Setup (Recommended)

CODEBLOCK9

2. Via wrangler.toml Routes

CODEBLOCK10

3. Via Cloudflare Dashboard

Workers & Pages → your worker → Settings → Domains & Routes → Add Custom Domain.

DNS Requirements

• - Domain must be in your Cloudflare account (orange-cloud proxied)
• SSL is automatic — no certificate management needed
• DNS propagation takes 1-5 minutes for proxied domains

Resource Provisioning

D1 (SQL Database)

CODEBLOCK11

Common D1 operations:
CODEBLOCK12

KV (Key-Value Store)

CODEBLOCK13

R2 (Object Storage)

CODEBLOCK14

Queues

CODEBLOCK15

Secrets Management

CODEBLOCK16

Configuration

Wrangler supports TOML and JSON/JSONC. If both exist, JSON takes precedence. Pick one.

Quick Reference (wrangler.toml)

CODEBLOCK17

See references/wrangler-config.md for the full reference including JSONC format, static assets, and all binding types.

Frontend Design

When building the frontend, apply these principles. Each links to a deep reference guide.

Typography

Choose distinctive fonts (not Inter/Roboto). Use a modular type scale with clamp() for headings. Pair a display font with a body font. Use font-display: swap and fallback metric matching to prevent layout shift.

Color & Theme

Use OKLCH for perceptually uniform palettes. Tint neutrals toward your brand hue. Follow the 60-30-10 rule (neutrals / secondary / accent). Avoid pure black/white. Avoid the AI palette (cyan-on-dark, purple-blue gradients).

Layout & Space

Use a 4pt spacing system. Create rhythm through varied spacing. Use auto-fit grids. Avoid wrapping everything in cards. Embrace asymmetry.

Motion

Only animate transform and opacity. Use exponential easing (quart/quint/expo). 100-150ms for feedback, 200-300ms for state changes, 300-500ms for layout. Always support prefers-reduced-motion.

Interaction

Design all 8 states (default, hover, focus, active, disabled, loading, error, success). Use :focus-visible for keyboard-only focus rings. Prefer optimistic UI and undo over confirmation dialogs.

Responsive

Mobile-first with min-width queries. Use container queries for components. Detect input method (pointer: fine/coarse), not just screen size. Handle safe areas.

UX Writing

Specific verb + object for buttons. Every error message answers what/why/how-to-fix. Empty states are onboarding moments. Pick one term and stick with it.

The AI Slop Test

If someone sees this interface and immediately thinks "AI made this" — that's the problem. Avoid: cyan-on-dark, purple gradients, glassmorphism everywhere, identical card grids, gradient text, dark mode with glowing accents. Make unexpected, intentional design choices.

Context Gathering

Before doing design work, you MUST have confirmed design context:

1. 1. Check loaded instructions for a Design Context section
2. Check .impeccable.md in project root
3. If neither exists, ask the user for: target audience, use cases, brand personality/tone

Troubleshooting

Scripts & References

Scripts

Script	Purpose
INLINECODE67	Scaffold project from CF templates
INLINECODE68

Deploy worker with pre-checks |

References

File	Topic
references/cf-templates.md	All 36+ CF quickstart templates
references/custom-domains.md

Domain setup, DNS, routes, SSL |

External Resources

• - Workers Docs
• Wrangler CLI
• D1 Docs
• R2 Docs
• KV Docs
• Workers Templates