Basic Usage

This guide covers the most common workflows and commands you'll use with nsyte. For a complete reference of all commands, see the Command Reference.

Initializing a Project

The first step in using nsyte is to initialize your project. This creates the necessary configuration files and sets up your authentication.

nsyte init

This interactive command will:

1. Ask for your authentication method (private key or bunker)
2. Configure your relays and servers
3. Create a .nsite directory with your configuration

Deploying Your Site

The most common command you'll use is deploy. This command publishes your website files to the configured relays and servers.

# Basic deploy
nsyte deploy ./dist

# Deploy with options
nsyte deploy ./dist --force --concurrency 8 --verbose

Common options:

• --force: Re-upload all files, bypassing server preflight checks
• --sync: Check all servers and upload missing blobs
• --verbose: Show detailed progress
• --concurrency: Number of parallel uploads (default: 4)
• --fallback: HTML file to use as 404.html (for SPAs)

Managing Files

Listing Published Files

To see what files are currently published:

nsyte list

This will show:

• File paths
• Upload dates
• File sizes
• Status (if available)

Downloading Files

To download your published files:

nsyte download ./backup

This is useful for:

• Creating backups
• Migrating to a different setup
• Verifying published content

Deleting Files

To remove published files from relays and optionally from Blossom servers:

# Delete root site (interactive confirmation)
nsyte delete

# Delete a named site
nsyte delete -d blog

# Delete site and its blobs from Blossom servers
nsyte delete --include-blobs

This is useful for:

• Removing old/unwanted content
• Cleaning up after testing
• Managing storage space on servers
• Removing sensitive content

Note: Creates NIP-09 delete events. Some relays may not honor delete requests.

Authentication Methods

nsyte supports three authentication methods:

1. Generated Private Key

The simplest method - nsyte will generate a new nostr key pair for you.

2. Existing Private Key

Use your own nostr private key.

3. nostr Bunker (NIP-46)

The most secure method - keeps your keys on a separate device.

# Connect to a bunker
nsyte bunker connect 'bunker://pubkey?relay=wss://relay.example&secret=xxx'

# List connected bunkers
nsyte bunker list

Common Workflows

Deploying a Static Site

1. Build your site:

npm run build  # or your build command

2. Deploy the built files:

nsyte deploy ./dist

Deploying a Single Page Application (SPA)

For SPAs with client-side routing:

nsyte deploy ./dist --fallback=/index.html

Updating Your Site

1. Make your changes
2. Build your site
3. Deploy the changes:

nsyte deploy ./dist

CI/CD Integration

To automate deployments in CI/CD:

1. Generate CI/CD credentials locally:

nsyte ci
# Follow prompts to connect bunker
# Copy the generated nbunksec (shown only once!)

2. Add the nbunksec to your CI/CD secrets (e.g., NBUNK_SECRET)

3. Use in your pipeline:

nsyte deploy ./dist --sec $NBUNK_SECRET

Next Steps

• Learn about configuration options
• Set up CI/CD integration
• Read about security best practices