Wisp CLI v1.1.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.1.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

Windows (x86_64): wisp-cli-x86_64-windows.exe

SHA-256 Checksums


ccf8076d13a32806cd2902941d9ce2825915a7c9c82867288c0921c2eae4db7a  wisp-cli-aarch64-darwin
9ca9e9f4dbfd6422529bcfda1fcbf12ea3b84b19dcbf212b1c3ee46f488306c9  wisp-cli-x86_64-darwin
83cff4775f85f597c62fa50d027108b4228feff3c927300fed0d44bc2922dedb  wisp-cli-aarch64-linux
99225a569f4ad395ca52055f5d602f1d8d649bc9ea9d542e303469a700fa3a73  wisp-cli-x86_64-linux
65da77e8868c8fb900b788e9c613866f7af3920a0274bdb1e76a4ca4b930c5a8  wisp-cli-x86_64-windows.exe

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
    - glibc
  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