Nostr Deploy CLI

June 11, 2025 · View on GitHub

A revolutionary CLI tool for deploying static sites using the Nostr protocol and Blossom servers following the Pubkey Static Websites NIP

npm version License: MIT

🌟 What makes this special?

Nostr Deploy CLI leverages the decentralized Nostr protocol and Blossom servers with the Pubkey Static Websites NIP standard to provide a unique static site deployment experience:

  • 🔐 Decentralized Authentication: No traditional accounts needed - authenticate with your Nostr keys
  • 🔑 NPub Subdomains: Your public key (npub) becomes your unique subdomain
  • 🌸 Blossom Storage: Your files are stored on decentralized Blossom servers
  • 📡 NIP-Compliant: Uses kind 34128 events for file metadata and kind 10063 for server lists
  • 🌐 Automatic Subdomains: Get instant subdomains automatically
  • 🚀 Zero Configuration: Deploys React, Vue, Angular, and any static site

🏗️ How It Works - Pubkey Static Websites NIP

1. NPub Subdomain Generation

  • Your Nostr public key (npub) becomes your subdomain: npub1abc123....nostrdeploy.com
  • No random subdomains - your identity is tied to your Nostr key
  • Consistent subdomain across all deployments

2. File Metadata Publishing (Kind 34128)

  • Each file is published as a kind 34128 Nostr event
  • Contains d tag with absolute file path (e.g., /index.html)
  • Contains x tag with SHA-256 hash of the file content
  • Enables decentralized file discovery and integrity verification

3. Server List Publishing (Kind 10063)

  • BUD-03 user servers event specifies which Blossom servers host your files
  • Host servers can discover and serve files from the correct Blossom instances
  • Enables redundancy and decentralized hosting

4. Host Server Resolution

  • Host servers resolve npub1xyz.nostrdeploy.com requests
  • Fetch user's kind 34128 events for the requested path
  • Retrieve files from Blossom servers using SHA-256 hashes
  • Serve with proper Content-Type headers

🚀 Quick Start

Installation

npm install -g nostr-deploy-cli

Instant Deploy

Want to deploy immediately? Use the fast deploy option:

# Navigate to your project and deploy in one command
cd your-project-directory
nostr-deploy-cli deploy --skip-setup

This auto-generates keys and deploys without any setup required!

Development / Local Usage

If you're developing or want to test locally without global installation:

# Clone and setup
git clone <repository-url>
cd nostr-deploy-cli
npm install
npm run build

# Run CLI directly
node dist/cli.js help
node dist/cli.js auth
node dist/cli.js config

# Or create a local symlink (recommended for development)
npm link
nostr-deploy-cli help  # Now works globally during development

# Remove the symlink when done
npm unlink -g nostr-deploy-cli

Initial Setup

Each project has its own local configuration and Nostr identity.

  1. Navigate to your project directory:
cd your-project-directory
  1. Set up authentication for this project:
nostr-deploy-cli auth

Your project's npub will become your subdomain: npub1abc123....nostrdeploy.com

  1. Configure deployment settings for this project:
nostr-deploy-cli config
  1. View your project's configuration:
nostr-deploy-cli info
  1. Deploy your site:
# Build your site first (if needed)
npm run build

# Deploy to your project's npub subdomain
nostr-deploy-cli deploy

Your site is now live at https://npub1abc123....nostrdeploy.com!

Note: Each project directory has its own .env.nostr-deploy.local configuration file with its own Nostr identity. This allows you to deploy different projects to different npub subdomains.

🚀 Fast Deploy (Skip Setup)

For quick deployments without manual setup, use the --skip-setup flag:

# Build your site first (if needed)
npm run build

# Auto-generate keys and deploy in one command
nostr-deploy-cli deploy --skip-setup

This will:

  • 🔍 Check for existing authentication configuration in the project
  • 🔄 Reuse existing keypair if found, or auto-generate a new one if needed
  • ⚙️ Set up default configuration (relays, Blossom server, domain) for missing settings
  • 💾 Display keys for you to save securely (if newly generated)
  • 🚀 Deploy immediately to your npub subdomain

Important: Save the generated private key (nsec) securely! You'll need it for future deployments.

📋 Commands

nostr-deploy-cli auth

Set up Nostr authentication for the current project

Options:

  • -k, --key <key> - Import private key (nsec format)
  • -p, --pubkey <pubkey> - Import public key only (npub format)

Examples:

# Interactive setup - generates new keys for this project
nostr-deploy-cli auth

# Import existing private key for this project
nostr-deploy-cli auth -k nsec1abc123...

# Import public key only (read-only mode)
nostr-deploy-cli auth -p npub1xyz789...

nostr-deploy-cli info

Display local project configuration and authentication status

Examples:

# View current project's configuration
nostr-deploy-cli info

nostr-deploy-cli config

Configure deployment settings for the current project

Options:

  • -r, --relays <relays...> - Nostr relay URLs
  • -b, --blossom <url> - Blossom server URL
  • -d, --domain <domain> - Base domain for subdomains

Examples:

# Interactive configuration for this project
nostr-deploy-cli config

# Set specific options for this project
nostr-deploy-cli config -b https://blossom.hzrd149.com -d nostrdeploy.com

nostr-deploy-cli deploy

Deploy your static site using Pubkey Static Websites NIP

Options:

  • -d, --dir <directory> - Build directory (default: auto-detect)
  • --skip-setup - Skip auth and config steps, reuse existing config or auto-generate keypair and deploy

Examples:

# Auto-detect build directory and deploy to this project's npub subdomain
nostr-deploy-cli deploy

# Specify build directory
nostr-deploy-cli deploy -d ./dist

# Deploy with specific directory
nostr-deploy-cli deploy -d ./out

# Fast deploy: auto-generate keys and deploy in one command
nostr-deploy-cli deploy --skip-setup

# Fast deploy with specific directory
nostr-deploy-cli deploy --skip-setup -d ./build

nostr-deploy-cli status

Check deployment status for your project's npub subdomain

Options:

  • -s, --subdomain <npub> - Check specific npub subdomain

Examples:

# List all deployments for this project
nostr-deploy-cli status

# Check specific npub subdomain status
nostr-deploy-cli status -s npub1abc123...

🔧 Configuration

Configuration is stored locally in each project directory as .env.nostr-deploy.local:

# Nostr Deploy CLI Configuration
# This file contains sensitive information - do not commit to version control

# Nostr Authentication
NOSTR_PRIVATE_KEY=your-hex-private-key
NOSTR_PUBLIC_KEY=your-hex-public-key
NOSTR_RELAYS=wss://relay.nostr.band

# Blossom File Storage
BLOSSOM_SERVER_URL=https://blossom.hzrd149.com

# Deployment Settings
BASE_DOMAIN=nostrdeploy.com

Important Notes:

  • Each project has its own .env.nostr-deploy.local configuration file
  • The .env.nostr-deploy.local file should be included in .gitignore
  • Different projects can use different Nostr identities and settings
  • Private keys are stored locally and never shared between projects
  • Environment variable format makes it easy to integrate with CI/CD pipelines

📡 Nostr Events Published

Static File Events (Kind 34128)

{
  "kind": 34128,
  "content": "",
  "tags": [
    ["d", "/index.html"],
    ["x", "186ea5fd14e88fd1ac49351759e7ab906fa94892002b60bf7f5a428f28ca1c99"]
  ]
}

User Servers Event (Kind 10063)

{
  "kind": 10063,
  "content": "",
  "tags": [["server", "https://blossom.hzrd149.com"]]
}

🌐 Architecture

graph TB
    A[Your Static Site] --> B[nostr-deploy-cli CLI]
    B --> C[Blossom Server]
    B --> D[Nostr Relays]
    B --> E[nostrdeploy.com]
    C --> F[File Storage with SHA-256]
    D --> G[Kind 34128 File Events]
    D --> H[Kind 10063 Server Events]
    E --> I[npub1abc.nostrdeploy.com]
    F --> I
    G --> I
    H --> I

🔒 Security & Privacy

  • Decentralized: No central authority controls your deployments
  • Cryptographic Identity: Your npub is cryptographically tied to your private key
  • Content Integrity: SHA-256 hashes ensure file integrity
  • Verifiable: Anyone can verify your site's authenticity via Nostr events
  • Censorship Resistant: Distributed across multiple relays and Blossom servers

🛠️ NIP Compliance

This tool implements multiple Nostr protocol specifications:

Pubkey Static Websites NIP:

  • ✅ Kind 34128 events for static file definitions
  • ✅ Absolute paths in d tags
  • ✅ SHA-256 hashes in x tags
  • ✅ NPub subdomain resolution
  • ✅ Kind 10063 BUD-03 user servers events
  • ✅ Fallback to /index.html for directory requests
  • ✅ /404.html fallback for not found pages

🌍 Nostr Ecosystem

This tool is part of the growing Nostr ecosystem:

  • Nostr Protocol: Decentralized social media protocol
  • Blossom Servers: Decentralized file storage network
  • Relay Network: Distributed message/metadata storage
  • Key Management: Compatible with existing Nostr clients

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/your-username/nostr-deploy-cli.git
cd nostr-deploy-cli

# Install dependencies
npm install

# Build the project
npm run build

# Test locally
npm run dev

📝 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Made with ❤️ for the decentralized web