title: Wisp CLI 0.4.0 (alpha) description: Command-line tool for deploying static sites to the AT Protocol#

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#

2b5c1d6d0e21f9d764dd66ef869bfcd348e8a111  wisp-cli-aarch64-darwin

68d4a3831c07d2f32fdde8d3e809af1ab79e804e  wisp-cli-aarch64-linux

86e89f592b0ec53239c082f502cbe7a47ed8bbec  wisp-cli-x86_64-linux

227b735911ad260cff5af3ca3beefa4e1e3956a8  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'

clone:
  skip: false
  depth: 1
  submodules: false

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-macos-arm64
chmod +x wisp-cli-macos-arm64

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

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

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 \
  --output ./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.

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] <INPUT>

Arguments:
  <INPUT>  Handle or DID

Options:
  -s, --site <SITE>           Site name to download
  -o, --output <OUTPUT>       Output directory [default: .]
  -h, --help                  Print help

Serve Command#

wisp-cli serve [OPTIONS] <INPUT>

Arguments:
  <INPUT>  Handle or DID

Options:
  -s, --site <SITE>           Site name to serve
  -o, --output <OUTPUT>       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/.

Related#

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