deploy

Deploy files from a directory to configured relays and blossom servers.

Aliases: upload, dpl — nsyte upload and nsyte dpl are equivalent to nsyte deploy. (upload prints a deprecation notice; prefer deploy.)

Usage

nsyte deploy <folder> [options]

• <folder>: The directory to deploy (required)

Options

• -f, --force — Force re-upload all files, bypassing server preflight checks (default: false)
• -s, --servers <servers> — The blossom servers to use (comma-separated)
• -r, --relays <relays> — The nostr relays to use (comma-separated)
• --sec <secret> — Secret for signing (auto-detects: nsec, nbunksec, bunker://, hex)
• --prompt-sec — Prompt for the signing secret at runtime instead of --sec (keeps it out of shell history)
• --sync — Check all servers and upload missing blobs (default: false)
• --use-fallback-relays — Include default nsyte relays in addition to configured relays
• --use-fallback-servers — Include default blossom servers in addition to configured servers
• --use-fallbacks — Enable both fallback relays and servers
• -v, --verbose — Verbose output (default: false)
• -c, --concurrency <number> — Number of parallel uploads (default: 4)
• --publish-profile — Publish profile metadata (Kind 0) - root sites only (default: false)
• --publish-relay-list — Publish relay list (Kind 10002) - root sites only (default: false)
• --publish-server-list — Publish Blossom server list (Kind 10063) - root sites only (default: false)
• --publish-app-handler — Publish NIP-89 app handler announcement (Kind 31990) (default: false)
• --handler-kinds <kinds> — Event kinds this nsite can handle (comma-separated)
• --fallback <file> — An HTML file to reference as 404.html (creates path mapping with same hash)
• -d, --name <name> — The site identifier for named sites (kind 35128). If not provided, deploys root site (kind 15128)
• --dry-run — Preview what would be deployed without uploading or publishing (default: false)
• --dry-run-output <dir> — Output directory for dry-run event previews (default: /tmp/nsyte-dry-run-{timestamp}/)
• --dry-run-show-kinds <kinds> — Also print events of these kinds to stdout (comma-separated kind numbers)
• --no-config — Ignore config file and use only CLI arguments (default: false)
• -i, --non-interactive — Run in non-interactive mode (default: false)
• --skip-secrets-scan — Skip the pre-deploy secrets scan (default: false)
• --scan-level <level> — Secrets scan sensitivity level: low, medium, or high (default: medium)

Examples

Deploy the dist directory:

nsyte deploy dist

Deploy with custom relays and servers:

nsyte deploy dist --relays wss://relay.example --servers https://server.example

Deploy with force (bypass server preflight checks):

nsyte deploy dist --force

Sync missing blobs across all servers:

nsyte deploy dist --sync

Deploy with metadata events:

nsyte deploy dist --publish-profile --publish-relay-list --publish-server-list

Deploy with app handler announcement:

nsyte deploy dist --publish-app-handler --handler-kinds "1,30023,30311"

Deploy with fallback relays and servers:

nsyte deploy dist --use-fallbacks

Preview deploy events without uploading or publishing:

nsyte deploy dist --dry-run --dry-run-show-kinds 15128,31990

How it Works

The deploy command:

1. Scans your local directory for files
2. Compares with previously deployed files (using SHA256 hashes)
3. Uploads only changed or new files to Blossom servers
4. Publishes the site manifest event (kind 15128 for root sites, 35128 for named sites) to configured relays
5. Optionally publishes metadata events for discovery

Authentication

The deploy command requires authentication to sign nostr events. You can provide authentication through:

1. Unified --sec flag: Auto-detects format (nsec, nbunksec, bunker://, or hex private key)
2. Project config: Uses bunker configured during nsyte init

The --sec flag accepts multiple formats:

• nsec1... - Nostr private key (bech32)
• nbunksec... - Encoded bunker credentials
• bunker://... - Bunker URL with relay and optional secret
• 64-character hex string - Raw private key

Performance

• Smart diffing: Only uploads changed files
• Parallel uploads: Use --concurrency to control parallel uploads
• Progress tracking: Shows upload progress with visual indicators

Metadata Publishing

Important: Profile, relay list, and server list can only be published from root sites (where id is null or empty in your config). These are user-level metadata and cannot be published from named sites to prevent conflicts.

Profile (Kind 0) - Root Sites Only

Use --publish-profile to publish your Nostr profile metadata. Configure the profile data in your .nsite/config.json:

{
  "id": null,
  "publishProfile": true,
  "profile": {
    "name": "Your Name",
    "about": "Description",
    "picture": "https://example.com/avatar.jpg"
  }
}

Relay List (Kind 10002) - Root Sites Only

Use --publish-relay-list to publish your outbox relays (NIP-65). This publishes all relays from your config as write-only (outbox) relays:

nsyte deploy dist --publish-relay-list

Server List (Kind 10063) - Root Sites Only

Use --publish-server-list to publish your Blossom servers. This helps clients know where to download your media files:

nsyte deploy dist --publish-server-list

App Handler (Kind 31990)

Use --publish-app-handler to announce your nsite as a NIP-89 application handler. This works for both root and named sites. Specify which event kinds your app can handle with --handler-kinds:

nsyte deploy dist --publish-app-handler --handler-kinds "1,30023"

Error Handling

• Network errors: Automatically retried with exponential backoff
• Authentication errors: Clear messages about missing or invalid credentials
• Upload failures: Detailed error messages for each failed file
• Relay rejections: Shows which relays accepted or rejected events

See Also

• nsyte init - Initialize a new nsyte project
• nsyte ls - List deployed files
• nsyte browse - Interactive file browser
• nsyte delete - Selectively remove deployed files
• nsyte undeploy - Completely remove a deployed site
• nsyte serve - Serve files locally for testing
• nsyte scan - Scan files for secrets before deploying

Inherits global options. See global options.