https://github.com/zapstore/zapstore-cli
The permissionless package manager
https://github.com/zapstore/zapstore-cli
cli dart freedom-tech linux macos nostr nostr-protocol package zapstore
Last synced: 3 months ago
JSON representation
The permissionless package manager
- Host: GitHub
- URL: https://github.com/zapstore/zapstore-cli
- Owner: zapstore
- License: mit
- Created: 2024-07-19T18:15:27.000Z (almost 2 years ago)
- Default Branch: master
- Last Pushed: 2026-02-13T02:28:48.000Z (4 months ago)
- Last Synced: 2026-02-13T11:04:07.706Z (4 months ago)
- Topics: cli, dart, freedom-tech, linux, macos, nostr, nostr-protocol, package, zapstore
- Language: Go
- Homepage: https://zapstore.dev
- Size: 20.5 MB
- Stars: 22
- Watchers: 1
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# zapstore
A standalone CLI package manager for [zapstore](https://zapstore.dev), built on Nostr.
## Install
```bash
go install github.com/zapstore/zapstore@latest
```
Or download a pre-built binary from the [releases page](https://github.com/zapstore/zapstore/releases).
## Usage
```
zapstore [flags] [arguments]
```
### Commands
```bash
zapstore install # fetch from relay, download, verify, install
zapstore remove # uninstall
zapstore update [] # update one or all installed packages
zapstore list # show installed packages
zapstore search # 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:
```bash
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
```bash
# 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 `/packages/-//` and symlinks `~/.local/bin/` 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:
```bash
# 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](https://specifications.freedesktop.org/basedir-spec/latest/). The filesystem is the sole source of truth -- there is no separate state file.
| Path | Purpose | Default |
|------|---------|---------|
| `$XDG_DATA_HOME/zapstore/packages/-//` | Installed binaries | `~/.local/share/zapstore/packages/` |
| `~/.local/bin/` | 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`:
```bash
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`:
```bash
RELAY_URLS=wss://relay.zapstore.dev,wss://backup-relay.example.com
```
## Building from source
```bash
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