mycelium-client

This is the official reference implementation of the Mycelium client software, written in Python. It comes with a library for Python applications, as well as a CLI for end-users.

Usage

As a CLI

In order to use the Mycelium client as a CLI, you need to install the mycelium-client[cli] variant:

pip3 install mycelium-client[cli]

Once that's done, you can get help information with mycelium-client --help:

$ mycelium-client --help
Usage: mycelium-client [OPTIONS] [COMMAND] [ARGS]...

Options:
  --version   Show the version and exit.
  -h, --help  Show this message and exit.

Commands:
  fetch
  show

As a Python library

The Mycelium client includes experimental support for use as a Python library without installing the CLI dependencies (this is what's supplied with the normal mycelium-client package):

import mycelium_client as mycelium
mycelium.fetch_hash(asset_hash="abcdef123...", oak="http://example.com:8000/", use_tqdm=False, quiet=True, timeout=15) # Fetch a hash.

mycelium.show_entries_md(filter_hash="", oak="http://example.com:8000/") # Generate human-readable Markdown describing the current entries advertised by an Oak. Leave filter_hash blank to disable hash filtering; set to a hash to filter for it.

mycelium.fetch_mycelium_file(content="CONTENTS-GO-HERE", quiet=True, use_tqdm=False, timeout=15) # Fetch using a Mycelium reference file. See example.mycelium for an example.

Make sure to use version pinning whenever you're writing code that depends on mycelium-client, as it has breaking changes frequently and is still very much not ready for production.

Mycelium reference files

The Mycelium client comes with built-in support for Mycelium reference files (MRFs for short). MRFs are brief files that give the client a list of suggested filenames, their hashes, the Oaks where they can be located, and a human-readable comment (optional). They're roughly equivalent to torrent files in BitTorrent.

Here's the example MRF file found at example.mycelium:

728ccb8dbeacf20d675bf3470481ef6432eb5d34f1da2aefe9e2dbf23abb6a7e:output1.png
00e991bfda1960f0f7b381a2b32f87c29f6204bd9791c76317b84be40ad9015f:output2.png
---
https://oak-f9d2f0e9.fastapicloud.dev/
---
This is an example Mycelium reference file (.mycelium). The first set of lines is a series of hashes followed by a colon and then their suggested file names.

The second set of lines provides suggested Oak servers that may have relevant listings, and the third set of lines is a human-readable comment.