Wisp CLI v1.0.0

Deploy static sites to the AT Protocol

The Wisp CLI is a command-line tool for deploying static websites directly to your AT Protocol account. Host your sites on wisp.place with full ownership and control, backed by the decentralized AT Protocol.

Features

Deploy: Push static sites directly from your terminal
Pull: Download sites from the PDS for development or backup
Serve: Run a local server with real-time firehose updates
Authenticate with app password or OAuth
Incremental updates: Only upload changed files

Downloads

Download v1.0.0

macOS (Apple Silicon): wisp-cli-aarch64-darwin

macOS (Intel): wisp-cli-x86_64-darwin

Linux (ARM64): wisp-cli-aarch64-linux

Linux (x86_64): wisp-cli-x86_64-linux

SHA-256 Checksums


560eface5029dbecdb4adb6cca169651cc301dd6d48263a1cddf1906a2295b0b  wisp-cli-aarch64-darwin
fc759aa8d412948f735420536ee3f7944bda6119ad2c9169583a9b188ae889e5  wisp-cli-x86_64-darwin
2ff51a5411a20c45fd05d29f90acd24410bdce31f6fc8a91a125691b275e1216  wisp-cli-aarch64-linux
8cf27698daf2d1371f1a4eb1ec1e24c4da9185639dc09edc3f8bc3d358f08738  wisp-cli-x86_64-linux

CI/CD Integration

Deploy automatically on every push using Tangled Spindle:

when:
  - event: ['push']
    branch: ['main']
  - event: ['manual']

engine: 'nixery'

dependencies:
  nixpkgs:
    - nodejs
    - coreutils
    - curl
  github:NixOS/nixpkgs/nixpkgs-unstable:
    - bun

environment:
  SITE_PATH: 'dist'
  SITE_NAME: 'my-site'
  WISP_HANDLE: 'your-handle.bsky.social'

steps:
  - name: build site
    command: |
      export PATH="$HOME/.nix-profile/bin:$PATH"

      # you may need to regenerate the lockfile due to nixery being weird
      # rm package-lock.json bun.lock
      bun install

      bun run build

  - name: deploy to wisp
    command: |
      # Download Wisp CLI
      curl https://sites.wisp.place/nekomimi.pet/wisp-cli-binaries/wisp-cli-x86_64-linux -o wisp-cli
      chmod +x wisp-cli

      # Deploy to Wisp
      ./wisp-cli \
        "$WISP_HANDLE" \
        --path "$SITE_PATH" \
        --site "$SITE_NAME" \
        --password "$WISP_APP_PASSWORD"

Note: Set WISP_APP_PASSWORD as a secret in your Tangled Spindle repository settings. Generate an app password from your AT Protocol account settings.

Basic Usage

Deploy a Site

# Download and make executable
curl -O https://sites.wisp.place/nekomimi.pet/wisp-cli-binaries/wisp-cli-aarch64-darwin
chmod +x wisp-cli-aarch64-darwin

# Deploy your site
./wisp-cli-aarch64-darwin deploy your-handle.bsky.social \
  --path ./dist \
  --site my-site

Your site will be available at: https://sites.wisp.place/your-handle/my-site

Domain Management

# Claim a custom domain
./wisp-cli domain claim your-handle.bsky.social --domain example.com

# Claim a subdomain
./wisp-cli domain claim-subdomain your-handle.bsky.social --subdomain alice

# Check domain status
./wisp-cli domain status your-handle.bsky.social --domain example.com

# Attach a site to a domain
./wisp-cli domain add-site your-handle.bsky.social --domain example.com --site mysite

# Delete a domain or site
./wisp-cli domain delete your-handle.bsky.social --domain example.com
./wisp-cli site delete your-handle.bsky.social --site mysite

List Domains & Sites

./wisp-cli list domains your-handle.bsky.social
./wisp-cli list sites your-handle.bsky.social

Options

Use an alternate proxy service DID:

./wisp-cli list domains your-handle.bsky.social --service did:web:example.com

Pull a Site from PDS

Download a site from the PDS to your local machine:

# Pull a site to a specific directory
wisp-cli pull your-handle.bsky.social \
  --site my-site \
  --path ./my-site

# Pull to current directory
wisp-cli pull your-handle.bsky.social \
  --site my-site

Serve a Site Locally with Real-Time Updates

Run a local server that monitors the firehose for real-time updates:

# Serve on http://localhost:8080 (default)
wisp-cli serve your-handle.bsky.social \
  --site my-site

# Serve on a custom port
wisp-cli serve your-handle.bsky.social \
  --site my-site \
  --port 3000

# Enable SPA mode (serve index.html for all routes)
wisp-cli serve your-handle.bsky.social \
  --site my-site \
  --spa

# Enable directory listing for paths without index files
wisp-cli serve your-handle.bsky.social \
  --site my-site \
  --directory

Downloads site, serves it, and watches firehose for live updates!

Authentication

OAuth (Recommended)

The CLI uses OAuth by default, opening your browser for secure authentication:

wisp-cli deploy your-handle.bsky.social --path ./dist --site my-site

This creates a session stored locally (default: /tmp/wisp-oauth-session.json).

App Password

For headless environments or CI/CD, use an app password:

wisp-cli deploy your-handle.bsky.social \
  --path ./dist \
  --site my-site \
  --password YOUR_APP_PASSWORD

Generate app passwords from your AT Protocol account settings.

File Processing

The CLI handles all file processing automatically to ensure reliable storage and delivery. Files are compressed with gzip at level 9 for optimal size reduction, then base64 encoded to bypass PDS content sniffing restrictions. Everything is uploaded as application/octet-stream blobs while preserving the original MIME type as metadata. When serving your site, the hosting service automatically decompresses non-HTML/CSS/JS files, ensuring your content is delivered correctly to visitors.

File Filtering: The CLI automatically excludes common files like .git, node_modules, .env, and other development artifacts. Customize this with a .wispignore file.

Incremental Updates

The CLI tracks file changes using CID-based content addressing to minimize upload times and bandwidth usage. On your first deploy, all files are uploaded to establish the initial site. For subsequent deploys, the CLI compares content-addressed CIDs to detect which files have actually changed, uploading only those that differ from the previous version. This makes fast iterations possible even for large sites, with deploys completing in seconds when only a few files have changed.

Limits

Max file size: 100MB per file (after compression)
Max total size: 300MB per site
Max files: 1000 files per site
Site name: Must follow AT Protocol rkey format (alphanumeric, hyphens, underscores)

Command Reference

Deploy Command

wisp-cli deploy [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Handle (e.g., alice.bsky.social), DID, or PDS URL

Options:
  -p, --path <PATH>           Path to site directory [default: .]
  -s, --site <SITE>           Site name (defaults to directory name)
      --store <STORE>         OAuth session file path [default: /tmp/wisp-oauth-session.json]
      --password <PASSWORD>   App password for authentication
  -h, --help                  Print help

Pull Command

wisp-cli pull [OPTIONS] --site <SITE> <INPUT>

Arguments:
  <INPUT>  Handle or DID

Options:
  -s, --site <SITE>           Site name to download
  -p, --path <PATH>           Output directory [default: .]
  -h, --help                  Print help

Serve Command

wisp-cli serve [OPTIONS] --site <SITE> <INPUT>

Arguments:
  <INPUT>  Handle or DID

Options:
  -s, --site <SITE>           Site name to serve
  -p, --path <PATH>           Site files directory [default: .]
  -P, --port <PORT>           Port to serve on [default: 8080]
      --spa                   Enable SPA mode (serve index.html for all routes)
      --directory             Enable directory listing mode for paths without index files
  -h, --help                  Print help

Development

The CLI is written in Rust using the Jacquard AT Protocol library. To build from source:

git clone https://tangled.org/@nekomimi.pet/wisp.place-monorepo
cd cli
cargo build --release

Built binaries are available in target/release/.

place.wisp.fs - Site manifest lexicon
place.wisp.subfs - Subtree records for large sites
AT Protocol - The decentralized protocol powering Wisp