Getting started with Keygen's CLI

Before getting started, you'll need to sign up for an account with Keygen. You will also want to go ahead and create your first product, and an API token for the product. We'll use both of these when publishing releases for our product.

Introduction

Keygen's CLI helps you sign and distribute software releases. It can be used to securely publish software applications from the command line, or from CI/CD environments. Keygen's CLI itself is published using the CLI, and it utilizes our Go SDK for automatic upgrades, which is all backed by Keygen's distribution API (it's dogfooding all the way down!)

The keygen CLI does not require a license — it uses an OPEN distribution strategy, which allows you to distribute releases without a license. (You could still add licensing into the application itself, e.g. a freemium model, but in our case, the CLI is open source and free to use.)

Installation

The keygen CLI is packaged as a single executable for Linux, macOS, Windows, and other platforms. The precompiled binaries have no external dependencies and there is no installation program — all you need to do is download and move the binary to a location of your choice for easy system-wide use, e.g. /usr/local/bin, /usr/bin, or some other location in your $PATH.

To quickly install the keygen CLI, you can run the following script.

curl -sSL https://get.keygen.sh/keygen/cli/install.sh | sh

The script will auto-detect your platform and install keygen into /usr/local/bin.

Manual installation

To install manually, download the appropriate keygen binary for your platform.

Once downloaded, give the binary executable permissions and move it to /usr/local/bin, or some other directory that's in your $PATH.

chmod +x ./keygen_linux_arm64_x_x_x
mv ./keygen_linux_arm64_x_x_x /usr/local/bin/keygen

Finally, confirm it's installed by running the following.

keygen --help

Commands

For all available commands and options, run keygen --help.

CLI to interact with keygen.sh
 
Usage:
keygen [command]
 
Available Commands:
dist publish a new release for a product
genkey generate an ed25519 key pair for code signing
help help for a command
version print the current CLI version
 
Flags:
-h, --help help for keygen
-v, --version version for keygen
 
Use "keygen [command] --help" for more information about a command.

Generate a key pair

Generate an Ed25519 public/private key pair. The private key will be used to sign releases, and the public key will be used to verify upgrades within your app. This key pair proves that a release was created by you, using a cryptographic signature.

keygen genkey

This will generate an Ed25519 key pair, 2 files in the current directory, the private key keygen.key and public key keygen.pub. The public key can be safely embedded within your app to cryptographically verify that releases were signed by yourself. Since only you possess the private key, this will cryptographically prove that you (or your team) created and published a given release.

Never share your private key, keygen.key, with anyone.

For more usage options run keygen genkey --help.

Publish a release

Publish a new release. This command will create a new release object, and then upload the file at <path> to the release's artifact relationship. When the --signing-key flag is provided, the release will be signed using Ed25519ph. In addition, a SHA-512 checksum will be generated for the release.

keygen dist 'build/keygen_darwin_arm64_1_0_0_beta_2' \
--signing-key ~/.keys/keygen.key \
--account '1fddcec8-8dd3-4d8d-9b16-215cac0f9b52' \
--product '2313b7e7-1ea6-4a01-901e-2931de6bb1e2' \
--token 'prod-xxx' \
--platform 'linux/amd64' \
--version '1.0.0-beta.2' \
--channel 'beta'

For more usage options run keygen dist --help.


Environment variables

Some flags can be set using environment variables so that they do not need to be specified, saving them from being logged to your shell's history. This is also useful in CI/CD environments.

export KEYGEN_ACCOUNT_ID='1fddcec8-8dd3-4d8d-9b16-215cac0f9b52'
export KEYGEN_PRODUCT_ID='2313b7e7-1ea6-4a01-901e-2931de6bb1e2'
export KEYGEN_PRODUCT_TOKEN='prod-xxx'
export KEYGEN_SIGNING_KEY_PATH='~/.keys/keygen.key'
export KEYGEN_SIGNING_KEY='xxx'
export KEYGEN_NO_AUTO_UPGRADE=1

Code signing

Signing your releases provides end-to-end guarantees that releases are solely created by you, the software vendor, and no one else. You could distribute your releases via trusted third-parties, such as Keygen, or even an untrusted third-party, and still maintain the guarantee that the binary you built and published is the binary that the end-user is using. This is proven, cryptographically.

As an example, using our Go SDK, you would set the keygen.UpgradeKey config to the value of your hex-encoded Ed25519 public key. This will be the text inside of the keygen.pub file.

This Ed25519 public key is different than your Keygen account's Ed25519 public key. This is a personal public key, where only you possess the private key. This ensures that nobody, not even us, possess the private key which proves a release was created by you.

Your Keygen account's public key is used for verifying the signature of API responses. We keep the private key safe, so that you can prove a given response was actually created by Keygen. We keep the private key secure.

In a similar way, your personal public key is used for verifying release signatures. Our Go SDK uses this public key to prove that a given release was actually created by you. You keep the private key secure.

keygen.UpgradeKey = "5ec69b78d4b5d4b624699cef5faf3347dc4b06bb807ed4a2c6740129f1db7159"

Using your newly generated public key, the SDK will automatically verify the release's signature during the upgrade process, in addition to the SHA-512 checksum, before installing an upgrade. If the signature or checksum fails verification, the upgrade will be aborted with an error.

Always keep your private key in a secure location. If your private key is ever compromised, please generate a new key pair.


Automatic upgrades

You can integrate our Go SDK to add auto-update functionality to a Go application. Installing an upgrade will replace the currently running binary with the latest version for the current platform. Check out the following code snippet to add auto-updates to your Go app.

import "github.com/keygen-sh/keygen-go"
 
const (
// Version is the current version of the app
Version = "1.0.0"
)
 
func init() {
keygen.Account = "<KEYGEN_ACCOUNT_ID>"
keygen.Product = "<KEYGEN_PRODUCT_ID>"
}
 
func AutoUpdate() error {
// Check for an upgrade
release, err := keygen.Upgrade(Version)
switch {
case err == keygen.ErrUpgradeNotAvailable:
fmt.Println("No upgrade available, already on the latest version!")
 
return nil
case err != nil:
fmt.Println("Upgrade check failed!")
 
return err
}
 
// Download the upgrade and automatically install it
err = release.Install()
if err != nil {
fmt.Println("Upgrade install failed!")
 
return err
}
 
fmt.Println("Upgrade complete! Now on v" + release.Version + "!")
}

If you wanted to, you could prompt the user for confirmation between calling keygen.Upgrade and release.Install (which is actually what our CLI does.)


Support

Questions? We'd be happy to help! Reach out at [email protected].