Skip to main content
The GOBL CLI is a useful tool to get to grips with using and understanding some of the underlying concepts. For the sake of the examples here, we’ll be using the note package’s Message type.

​
Installation

The CLI is built from the gobl.dev repository, which bundles the core GOBL library with every addon. Our recommendation is to head over to the gobl.dev releases page and download the latest version for your platform and copy the binary to a directory of your choosing. If you already have a working Go environment you may also find it easy to install the latest version with:
Once downloaded and installed or built, check it’s working:
You should get version information back like the following, where version is the gobl.dev release and core is the version of the GOBL library it bundles:

​
Building a Message

The notes.Message type is great for setting up a simple test. For this tutorial open your text editor and a simple JSON file called message.json that looks like:
If you’re using an editor like VSCode which has built-in support for JSON Schemas, it may already have performed some pre-validations on the document which will all be positive for this simple example. The GOBL CLI also supports YAML input, but in general, thanks to the schemas and powerful text editors, we find it a bit easier to write files in JSON. Now send the document to the gobl build command with the --envelop flag indicating that we want the message wrapped in an envelope. The -i flag produces prettier output:
You should get something similar to the following:
The original message has now been placed into a GOBL Envelope with a header that allows us to ensure that the contents of the document cannot be modified without creating a new digest. Both the envelope and the message received a uuid.

​
Keys

GOBL has built in support for digital signatures using JSON Web Keys. The CLI makes this process trivial, but you do need to have generated a private key. The keygen command will create a key pair inside the ~/.gobl directory by running:
Check the contents of the key:
Outputs something like:
IMPORTANT: Private keys should never be shared! The GOBL CLI generates a second public key which can be shared with others to validate a document is from you:
Outputs:
If anyone ever needs to verify the source of a GOBL Envelope that you signed, simply send them a copy or provide them access to your public key.

​
Signing

Now we have a private key, we can sign the original message. Run the following command:
The output produced should be something like:
Essentially the doc and head fields are identical to the original message, but we’ve now added the sigs array at the end. Combined with your public key, anyone can easily verify the contents of your message where indeed signed with your private key. If you’re interested, you can check the contents of the signature here: jwt.io.