zapstore-cli

The permissionless package manager.

Download binaries

If you have zapstore already installed, run:

zapstore install zapstore

Or download an executable for your platform here: https://zapstore.dev/download or https://github.com/zapstore/zapstore-cli/releases. Make sure to verify hashes published in zapstore.dev.

You need to run the executable once, follow instructions and it will auto-install itself. After that simply call zapstore.

Note for Linux users: you must have libsqlite3.so in your library path. You can install via apt install libsqlite3-dev or similar.

From source

Download and select release:

git clone https://github.com/zapstore/zapstore-cli
cd zapstore-cli
git checkout <tag> # select a release from here: https://github.com/zapstore/zapstore-cli/tags

Please do not run it from master or any other feature branch.

Install dependencies:

dart pub get

Build and run:

dart compile exe lib/main.dart -o zapstore
./zapstore

New version 0.2.0

This major refactor removes most external dependencies, so apktool and apksigner are no longer necessary on your system.

Install or update a package

zapstore install <package>
# or zapstore i

Attempting to install will trigger a web of trust check via Vertex DVMs if the signer is not known. You can skip this by: passing the -t argument, or by having no SIGN_WITH env var to sign the DVM request with.

Discover new packages

An experimental command recently added:

zapstore discover
# or zapstore d

It will show recommended packages that are currently not installed.

List installed packages

zapstore list <optional-filter>
# or zapstore l

If filter is provided it is treated as a regex to filter down installed packages.

Remove a package

zapstore remove <package>
# or zapstore r

Run zapstore --help for more information.

Publishing apps or packages

Currently supported platforms:

• Android arm64-v8a (android-arm64-v8a)
• MacOS arm64 (darwin-arm64)
• Linux amd64 (linux-x86_64)
• Linux aarch64 (linux-aarch64)

Run zapstore publish in a folder with a zapstore.yaml config file. Alternatively supply its location via the -c argument.

Example of a minimal config. The assets list is required.

assets:
  - output/.*.apk

Convention over configuration is the way. The main AssetParser aims to require as little information as possible to work. It will extract as much information as possible from supplied assets, particularly from Android APKs.

Most properties can be overridden in the configuration, and additional information can be pulled from remote metadata sources such as Github and Google Play Store.

The asset parser has two additional subclasses: GithubParser and WebParser. In the remainder of this documentation we will focus on local (default) and Github parsing.

If assets contain a forward-slash they are considered to be local, otherwise they are looked up on Github, provided there is a defined repository.

Below is a full config example with all supported properties:

identifier: com.sample.app
version: 1.0.0
name: Sample
summary: Sample summary
description: Just a sample APK
repository: https://github.com/sample/android
release_repository: https://github.com/sample/android-releases
homepage: https://zapstore.dev
images:
  - test/assets/i1.jpg
  - test/assets/i2.jpg
icon: test/assets/icon.png
changelog: CHANGELOG.md
tags: freedom-tech sample android
license: MIT
remote_metadata:
  - playstore
  - github
blossom_server: https://cdn.zapstore.dev
assets: # for local (relative to config file path!)
  - test/assets/.*.apk
# or
assets: # for github
  - \d+\.\d+\.\d+-arm64-v8a.apk
executables:
  - ^sample-.*

Notes on properties:

• identifier: Main identifier that will become the d tag in the app event. Mostly useful for CLI apps, in Android identifier will be extracted from the APK. Can be derived from the last bit of repository if on Github, or from name.
• version: Version being published, not allowed on Android as version will be extracted from the APK. Useful for CLI apps published from a local source
• name: App name, if not supplied it will be derived from the identifier. Can be pulled via remote metadata like Google Play Store, for example
• summary: Short sentence describing this app. Can be pulled from remote metadata.
• description: Longer description of the app, markdown allowed. Can be pulled from remote metadata. Can be derived from summary.
• repository: Source repository. If on github.com, releases will be looked up via Github API
• release_repository: If source repository is missing (closed source apps) or releases are found here instead
• homepage: App website
• images: List of image paths. Local paths or remote URLs supported. Must be relative to the config file directory
• icon: Icon path. Local paths or remote URLs supported. Must be relative to the config file directory
• changelog: Local path to the changelog in the Keep a Changelog format, release notes for the resolved version can be extracted from here, defaults to CHANGELOG.md
• tags: String with tags related to the app, separated by a space
• license: Project license in SPDX identifier format
• remote_metadata: List of remote metadata sources, currently supported: playstore, fdroid (also checks Izzy), github, gitlab
• blossom_server: The Blossom server where to upload assets. Includes icon and images, whether local or pulled via remote_metadata. If any upload fails the program will exit as events contain URLs to this Blossom server which need to be valid.
• assets: List of paths to assets as regular expressions.
  • If paths contain a forward-slash they will trigger the local asset parser. All asset paths are relative to the config path directory
  • If they do not contain forward-slashes, the Github/Gitlab parsers will be used (as long as there is a repository with a github.com or gitlab.com host).
  • If they are another HTTP URI, the Web parser.
  • If omitted, the list defaults to a single .* which means all assets in Github/Gitlab release, if applicable.
• executables: Strictly for CLI apps that are packaged as a compressed archive, a list of in-archive paths as regular expressions. If omitted, all supported executables (see supported platforms above) inside the archive will be linked and installed.

Supported compressed archive formats: ZIP, and TAR, XZ, BZIP2 (gzipped or not).

If you need assistance producing a zapstore.yaml config file, please reach out via nostr.

Real world examples

This program:

name: zapstore
version: 0.2.0-rc1
description: The permissionless package manager
repository: https://github.com/zapstore/zapstore-cli
license: MIT
assets:
  - bin/.*

Zapstore Android app:

name: Zapstore
repository: https://github.com/zapstore/zapstore
icon: assets/images/logo.png
license: MIT

Alby Go:

name: Alby Go
summary: The easiest mobile app to use bitcoin on the Go!
repository: https://github.com/getAlby/go
homepage: https://albygo.com/
assets:
  - alby-go-v\d+\.\d+\.\d+-android.apk
remote_metadata:
  - github
  - playstore

nak:

repository: https://github.com/fiatjaf/nak
assets:
  - nak-v\d+\.\d+\.\d+-darwin-arm64
  - nak-v\d+\.\d+\.\d+-linux-amd64
  - nak-v\d+\.\d+\.\d+-linux-arm64

Phoenix for servers (includes phoenixd and phoenix-cli inside the archive):

repository: https://github.com/acinq/phoenixd
assets:
  - phoenixd-\d+.\d+.\d+-macos-arm64.zip
  - phoenixd-\d+.\d+.\d+-linux-x64.zip
  - phoenixd-\d+.\d+.\d+-linux-arm64.zip

Signing and publishing

Supported signing methods:

• nsec
• NIP-07 (opens a web browser with an extension)
• NIP-46 (requires nak which can be installed with zapstore i nak)
• sending unsigned events to stdout (see section below)

The method is passed via the SIGN_WITH environmental variable and it is required for publishing.

The .env file approach is supported and recommended. Example:

SIGN_WITH=176fa8c7a988df001bc062ce1443e5b8d3f24913b54ec49d322ddd638d0c17aa
# or SIGN_WITH=nsec1zah633af3r0sqx7qvt8pgsl9hrflyjgnk48vf8fj9hwk8rgvz74q6xaqee
SIGN_WITH=NIP07
SIGN_WITH=bunker://9fb1f82f03c40b6063e95f18ce9006d5a3b15fc05dd244d230c12a4e21fe304c?relay=wss%3A%2F%2Frelay.primal.net%2F&secret=87412ffe-4e3e-551e-97fc-5686ac74bf23

Note that uploading to Blossom servers will also require signing Blossom authorization events of kind 24242.

The ability of pasting an nsec found in previous versions was removed. If you don't want to include your nsec in an .env file, here is the recommended command:

 SIGN_WITH=176fa8c7a988df001bc062ce1443e5b8d3f24913b54ec49d322ddd638d0c17aa zapstore publish

(Notice the leading space, this will prevent your shell from saving this command in history.)

The program does not save any SIGN_WITH value or send it anywhere.

Signed events are only published to relay.zapstore.dev for now (this will change in the near future). Your pubkey must be whitelisted by Zapstore in order for your events to be accepted. Get in touch!

Sending unsigned events to stdout

Events can be produced and printed to stdout unsigned, so it's possible to pipe to nak or other signers:

zapstore publish | nak event --sec 'bunker://...' relay.zapstore.dev

This approach has a few limitations:

• An npub MUST be passed as the SIGN_WITH environment variable
• The provided npub MUST match the resulting pubkey from the signed events
• Blossom assets (if any) MUST be manually uploaded

Program arguments

Can be found with zapstore publish --help.

Usage: zapstore publish [arguments]
-h, --help                      Print this usage information.
-c, --config                    Path to the YAML config file
                                (defaults to "zapstore.yaml")
    --[no-]overwrite-app        Fetches remote metadata and overwrites latest app on relays
                                (defaults to on)
    --[no-]overwrite-release    Overwrites latest release on relays
    --[no-]indexer-mode         Run publish in indexer mode (non-interactively and without spinners)
    --[no-]honor                Indicate you will honor tags when external signing

If the release exists on relays, the program will show a warning and exit unless --overwrite-release was passed.

To prevent repeated fetches of remote metadata, use --no-overwrite-app.