blossom-cli

blossom-cli is a small command line tool for direct Blossom server operations.

It is designed around real-world flows that work well with https://blossom.primal.net:

• generate a signer when you do not already have an nsec
• upload files
• list a signer's blobs
• check whether a blob exists
• delete a blob
• generate optimized media URLs

Install

npm install -g blossom-cli

Or run it without installing:

npx blossom-cli help

Quick Start

If you do not already have an nsec, generate one:

npx blossom-cli keygen

Then use the returned nsec for authenticated commands:

BLOSSOM_NSEC='nsec1...' npx blossom-cli upload ./photo.jpg --server blossom.primal.net

Read-only commands do not need a signer:

npx blossom-cli exists <sha256> --server blossom.primal.net
npx blossom-cli optimize-url https://blossom.primal.net/<sha256> --width 1024 --format webp

Commands

keygen

Generate a disposable Blossom signer:

npx blossom-cli keygen

This is useful when you want to publish a file but do not already have an nsec. If you want to list or delete blobs later, keep the generated nsec.

upload

BLOSSOM_NSEC='nsec1...' npx blossom-cli upload ./hello.txt --server blossom.primal.net

list

BLOSSOM_NSEC='nsec1...' npx blossom-cli list --server blossom.primal.net

You can also list by --pubkey or --npub.

exists

npx blossom-cli exists <sha256> --server blossom.primal.net

delete

BLOSSOM_NSEC='nsec1...' npx blossom-cli delete <sha256> --server blossom.primal.net

optimize-url

npx blossom-cli optimize-url https://blossom.primal.net/<sha256> --width 768 --format webp

Notes

• Server names without a scheme are normalized to https://.
• Authenticated commands use a kind 24242 Blossom auth event.
• The tool does not require relays for direct server operations.
• The bundled npm package is built so it works under plain node, which is what npx uses.

Skill

This repo also contains a Codex skill for Blossom publishing workflows in blossom-publishing/SKILL.md.