How to automate Bitcoin proof creation with Woleet-CLI


The Woleet command line interface tool allows to scan a folder recursively and to anchor or sign all files found in it. It automatically gathers all the proof receipts and stores them beside anchored or signed files (a proof receipt is a JSON file named <filename>-<anchorID>.(anchor|signature)-receipt.json).

Since proof receipt creation is not a real time operation, the tool is designed to be run on a regular basis (or at least a second time once proof receipts are ready to download). Obviously, the files that were already anchored or signed are not processed twice.

If the option --strict is provided, for each file that already have a proof receipt, the tool checks that the hash of the file still matches the hash in the receipt (to detect file changes). If they differ, the file is re-processed and the old receipt is kept (except if –prune is set: in that case the old receipt is deleted).

If the original file is no longer present and the option --prune is provided, the old receipt/pending file is deleted.

To sum up, the Woleet CLI command line tool allows to automate the creation and maintenance of the timestamped proofs of existence or signature associated with a set of files present in a given directory.

Note: tags are added to the anchors according to the name of sub-folders


Linux / MacOS

To install Woleet CLI on *nix OS

CLI_URL=$(curl --silent | grep 'browser_download_url' | grep -ioE "https://.*$(uname -s)_x86_64.tar.gz") && \
sudo curl -L "$CLI_URL" | sudo tar -xz -C /usr/local/bin woleet-cli && \
sudo chmod +x /usr/local/bin/woleet-cli

Manual installation (Windows included)

Go to and download the archive matching your operating system. Unpack it, and for *nix OS you need to add execution permissions to the binary.


The first and only thing you need is a Woleet API token. To get one, sign in to ProofDesk and follow the indications on this image:

generate API token
generate API token

You now have your API token copied on your clipboard. 🎉


Due to the design of this tool, some files are ignored by the tool:

  • All files and folders beginning by ‘.’
  • Files finished by .(anchor|signature)-(receipt|pending).json
  • Symlinks are not followed
  • Scanned sub-folders cannot have a space in their name
  • The maximum length of the subfolder path (without delimiters) is 128 characters


To anchor the content of a folder there is few mandatory flags to add to the command:

--token <Paste the Woleet API token currently in your clipboard>

--directory <Path: can be absolute or relative> The directory that contains the files you wish to anchor.

There is also some flags that sightly changes the usage of this tool:

--exitOnError If set, woleet-cli stops at the first error it encounter for example, if the API token is not valid or if there is a network issue.

--recursive If set, woleet-cli also anchors subfolders and add a tag to the anchor named as the subfolder

--strict If set, recheck every file and re-anchor the ones that have changed since the last run

--prune If set, deletes the receipts that are not beside the original file. If used with --strict If set, checks the hash of the original file and compares it to the one stored in the receipt, if they do not matches, the outdated receipt is deleted.

--private: If set, create non discoverable proofs


Wait for proofs to be confirmed and you will have this output:


To sign the content of a folder, the flags are the same than the ones used for anchoring and do the exact same things. Some additional mandatory parameters are used to sign via Woleet.ID Server:

--widsSignURL <URL>  Woleet.ID Server sign URL ex: “” (required)

--widsToken <WIDS API Token>   Woleet.ID Server API token (required)

--widsPubKey <Public key>   public key (ie. bitcoin address) to use to sign


Wait for proofs to be confirmed and you will have this output:


Export is a function that allows one to download all receipts available on your woleet account to a folder. To export all your receipts to a folder there is few mandatory flags to add to the command:

--token <Paste the Woleet API token currently in your clipboard>

--directory <Path: can be absolute or relative> The directory will contains all the receipts.

There is also an optional flag used to get all receipts created after a certain date:

--limitDate <yyyy-MM-dd>



It’s advised to automate woleet-cli invocations, you can do it either via a crontab or via the Systemd timers, It’s not necessary to run it more than once every 6 hours


You can use this website to generate a contab schedule, if you are not ‘fluent’ in it’s syntax:

0 0,6,12,18 * * * sh -c '/usr/local/bin/woleet-cli anchor --token ***** --directory /some/path >> /path/to/log/file 2>&1'

You may need to monitor this file, with logrotate for example, to prevent it from getting too big.

Systemd timers

The main advantage of using Systemd timers is that the logging will be handled by Systemd, you will be able to see logs by typing journalctl -u woleet-cli


service: /etc/systemd/system/woleet-cli.service

Description=Execute woleet-cli

ExecStart=/bin/sh -c '/usr/local/bin/woleet-cli anchor --token ***** --directory /some/path'

timer: /etc/systemd/system/woleet-cli.timer

Description=Run woleet-cli.service every 6 hours



And type:

sudo systemctl daemon-reload && \
sudo systemctl start woleet-cli.timer && \
sudo systemctl enable woleet-cli.timer


Wrapping up

With all this information you will be able to automate timestamping and signature for every set of files.

There is additionnal information on the github README: