Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (nostr-deploy-cli) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Nostr Deploy CLI

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

🌟 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.

Navigate to your project directory:

cd your-project-directory

Set up authentication for this project:

nostr-deploy-cli auth

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

Configure deployment settings for this project:

nostr-deploy-cli config

View your project's configuration:

nostr-deploy-cli info

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

Nostr Protocol - Decentralized communication protocol
Blossom Servers - Decentralized file storage
nostr-tools - JavaScript Nostr library

🔗 Links

Made with ❤️ for the decentralized web