zapstore

A standalone CLI package manager for zapstore, built on Nostr.

Install

go install github.com/zapstore/zapstore@latest

Or download a pre-built binary from the releases page.

Usage

zapstore [flags] <command> [arguments]

Commands

zapstore install <app-id>      # fetch from relay, download, verify, install
zapstore remove  <app-id>      # uninstall
zapstore update  [<app-id>]    # update one or all installed packages
zapstore list                  # show installed packages
zapstore search  <query>       # discover packages on relay
zapstore cleanup               # remove old versions and free disk space

Flags

Flag	Description
-q, --quiet	Suppress status output (results and errors only)
-v, --verbose	Show detailed output (relay URLs, platform info)
--json	Output results as JSON (list, search)
--no-color	Disable colored output
--refresh-profiles	Force refresh of cached developer profiles
--version	Print version and exit
-h, --help	Show help

Flags can appear anywhere in the command:

zapstore -q install com.example.app
zapstore search markdown --json
zapstore list --json -q | jq '.[].app_id'

First time

No setup is required: search and install work immediately. Installed binaries are symlinked into ~/.local/bin/. After your first install, if that directory isn't on your PATH, the CLI prints the exact line to add to your shell profile (e.g. export PATH="$HOME/.local/bin:$PATH").

Examples

# Search for packages
zapstore search jq

# Search and pipe JSON to jq
zapstore search jq --json | jq '.[].app_id'

# Install a package
zapstore install com.github.jqlang.jq

# Install quietly (for scripts)
zapstore install -q com.github.jqlang.jq

# List installed packages
zapstore list

# List as JSON
zapstore list --json

# Update all packages
zapstore update

# Remove a package
zapstore remove com.github.jqlang.jq

# Clean up old versions
zapstore cleanup

How it works

1. Queries the zapstore relay (wss://relay.zapstore.dev) for app, release, and asset metadata (Nostr kinds 32267, 30063, 3063)
2. Filters assets by your current platform and architecture
3. Downloads the binary and verifies its SHA-256 hash against the signed event
4. Places the binary in <data-dir>/packages/<hex-pubkey>-<app-id>/<version>/ and symlinks ~/.local/bin/<app-id> to it

Output design

The CLI uses a Cargo-inspired action-verb prefix pattern. Status messages go to stderr, data to stdout:

   Resolving  com.github.jqlang.jq
       Found  jq v1.7.1
 Downloading  jq (2.1 MB)
   Verifying  SHA-256 ✓
  Installing  ~/.local/share/zapstore/bin/jq
    Finished  installed jq v1.7.1 in 1.8s

This means piping works correctly:

# Status on stderr, JSON data on stdout
zapstore search markdown --json 2>/dev/null | jq .

# Quiet mode for scripting
zapstore list -q --json | jq -r '.[].app_id' | xargs -I{} zapstore update {}

Filesystem layout

zapstore follows the XDG Base Directory Specification. The filesystem is the sole source of truth -- there is no separate state file.

Path	Purpose	Default
$XDG_DATA_HOME/zapstore/packages/<hex>-<appid>/<version>/	Installed binaries	~/.local/share/zapstore/packages/
~/.local/bin/<app-id>	Symlinks to active binary	~/.local/bin/
$XDG_CACHE_HOME/zapstore/	Profile cache	~/.cache/zapstore/
$XDG_CONFIG_HOME/zapstore/config.env	User-level configuration	~/.config/zapstore/config.env

Package directories are prefixed with the publisher's hex pubkey for namespacing:

~/.local/share/zapstore/packages/
  79be667ef9dcbbac55a06295ce870b07029bfcdb2dce28d959f2815b16f81798-zapstore/
    0.4.0/
      zapstore-darwin-arm64

~/.local/bin/zapstore  →  ~/.local/share/zapstore/packages/79be6...-zapstore/0.4.0/zapstore-darwin-arm64

Add the bin directory to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Configuration

zapstore automatically loads environment files in this priority order:

1. Existing environment variables (highest priority)
2. .env.local in current directory
3. .env in current directory
4. ~/.config/zapstore/config.env (user-level defaults)

Example config.env:

RELAY_URLS=wss://relay.zapstore.dev,wss://backup-relay.example.com

Building from source

git clone https://github.com/zapstore/zapstore.git
cd zapstore
go build -o zapstore .

# With version info:
go build -ldflags "-X main.buildVersion=0.1.0" -o zapstore .

Environment variables

Variable	Description
RELAY_URLS	Comma-separated Nostr relay URLs (default: wss://relay.zapstore.dev). Use e.g. ws://localhost:4334 or multiple relays.
XDG_DATA_HOME	Override data directory (default: ~/.local/share)
XDG_CACHE_HOME	Override cache directory (default: ~/.cache)
XDG_CONFIG_HOME	Override config directory (default: ~/.config)
NO_COLOR	Disable colored terminal output
FORCE_COLOR	Force colored output even when not a TTY

License

MIT