Using the CLI

This page shows you how to use the internationalized Command Line Interface of your project, or more specifically, its Key Generator and Key Manager modules. The CLI is provided by the main classes of these modules which are named ${package}.keygen.Main and ${package}.keymgr.Main.

Using the Key Generator CLI

Overview

If you run the standalone JAR of the Key Generator module without arguments, it prints usage instructions:

$ java -jar *-keygen/target/*-keygen-*-standalone.jar
Usage:

    Main <command> [<options>] [<parameters>]

where <command> is one of (case is ignored):

    help        print usage instructions for a command
    version     print version information
    generate    generates a license key

You can get help for a particular command by using the help command. These are the usage instructions for the generate command:

$ java -jar *-keygen/target/*-keygen-*-standalone.jar help generate
Usage:

    generate [[-key]  <license-key-path>   ] |
             [-input  <input-license-path> ] |
             [-output <output-license-path>] |
             [-edition <edition>] |
             [-verbose <boolean>]

Generates a license key and prints its license bean to standard output. If a
<license-key-path> is specified, then the generated license key gets saved to 
the file identified by this path.

If an <input-license-path> is specified, then the license bean gets decoded
from the file identified by this path and transformed into the license key.
Specifying a dash (-) causes the standard input stream to be used instead of a
file. If no <input-license-path> is specified, then a default license bean gets
created and transformed into the license key.

If an <output-license-path> is specified, then the license bean gets encoded to
the file identified by this path for subsequent editing and input to this
command. Specifying a dash (-) causes the standard output stream to be used
instead of a file.

If more than edition has been configured in the licensing schema, then an
<edition> must be specified on the command line.

By default, this command does not write debugging information to the standard
error stream. You can override the default behavior by specifying
`-verbose true` or `-verbose false`.

Generating a License Key

Using Default Properties

You can generate a license key with default properties using:

$ java -jar *-keygen/target/*-keygen-*-standalone.jar generate product.lic \
    -verbose true
net.truelicense.api.License@a7c825cc[subject="Product 1", holder="CN=Anonymous User", issuer="CN=Company Inc.", issued=Thu Mar 28 15:08:51 CET 2013, notBefore=null, notAfter=null, consumerType="User", consumerAmount=1, info=null]

This command creates and initializes a new license bean, encodes it into a license key and writes the result into the file product.lic.

If the property ${verboseCli} is set to true when generating your project, then a brief representation of the encoded license bean is printed to the standard error stream by default. You can override this by specifying -verbose true or -version false.

Supporting Multiple Editions

If the project is supporting multiple editions, then you must specify the -edition option on the command line. For example, you can generate a license key for an edition named standard like this:

$ java -jar *-keygen/target/*-keygen-*-standalone.jar generate product.lic \
    -verbose true -edition standard
net.truelicense.api.License@a7c825cc[subject="Product 1", holder="CN=Anonymous User", issuer="CN=Company Inc.", issued=Thu Mar 28 15:08:51 CET 2013, notBefore=null, notAfter=null, consumerType="User", consumerAmount=1, info=null]

If only one edition is supported, then this option is not required. For brevity, only one edition is assumed in the remainder of this page and this option is not specified.

Property Input

You can specify the -input parameter in order to read a template license bean from a file or the standard input stream. The input syntax needs to conform to the configured license key format. For example, if the license key format is V2/JSON, then you can decode a license bean with the holder and term properties from the standard input stream in JSON format and generate a V2/JSON license key from it like this:

$ echo '{ "holder": "CN=Christian Schlichtherle", "term": 365 }' | \
    java -jar *-keygen/target/*-keygen-*-standalone.jar generate product.lic \
    -verbose true -input -
net.truelicense.api.License@e195716b[subject="Product 1", holder="CN=Christian Schlichtherle", issuer="CN=Company Inc.", issued=Thu Mar 28 15:11:12 CET 2013, notBefore=Thu Mar 28 15:11:12 CET 2013, notAfter=Fri Mar 28 15:11:12 CET 2014, consumerType="User", consumerAmount=1, info=null]

Please refer to the Javadoc for the class net.truelicense.api.License for a list of all predefined properties.

Property Output

You can specify the -output parameter in order to write the encoded license bean to a file or the standard output stream. The output syntax conforms to the configured license key format. For example, if the license key format is V2/JSON, then you can decode a license bean with the issuer property from the standard input stream in JSON format, generate a V2/JSON license key from it and print the encoded license bean to the standard output stream like this:

$ echo '{ "issuer": "CN=Christian Schlichtherle" }' | \
    java -jar *-keygen/target/*-keygen-*-standalone.jar generate product.lic \
    -verbose false -input - -output -
{"consumerAmount":1,"consumerType":"User","holder":"CN=Anonymous User","issued":1364480121566,"issuer":"CN=Christian Schlichtherle","subject":"Product 1"}
Custom Properties

Besides the predefined properties, you can also store custom properties in a license bean. To facilitate this, the License class defines a property with the name extra and the type java.lang.Object. To store an object into this property, it’s type needs to be supported by the codec of the respective license key format, i.e. JSON or XML. Both codecs support java.util.Map without customization. For example, if the license key format is V2/JSON, then you can provide a map with the custom properties named foo and bar like this:

$ echo '{ "extra": { "foo": 1, "bar": "baz" } }' | \
    java -jar *-keygen/target/*-keygen-*-standalone.jar generate product.lic \
    -verbose false -input - -output -
{"extra":{"foo":1,"bar":"baz"},"consumerAmount":1,"consumerType":"User","holder":"CN=Anonymous User","issued":1364480121566,"issuer":"CN=Company Inc.","subject":"Product 1"}

The property extra is not meant to be displayed to users, so you can store any private information in it. If you want to display additional information to the user, then you can use the property with the name info and the type java.lang.String instead.

Using the Key Manager CLI

Overview

Just like the standalone JAR of the Key Generator module, if you run the guarded JAR or the standalone JAR of the Key Manager module without arguments, it prints usage instructions:

$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar
Usage:

    Main <command> [<options>] [<parameters>]

where <command> is one of (case is ignored):

    help       print usage instructions for a command
    version     print version information
    install     installs a license key
    view       prints the installed license key
    verify   verifies the installed license key
    uninstall   Uninstalls the license key
    wizard   starts the licensing wizard

You can get help for a particular command by using the help command. These are the usage instructions for the install command:

$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar help install
Usage:

    install <license-key-path>

Loads and installs the regular license key from the file identified by
<license-key-path>.

Installing a License Key

You can install a license key using:

$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar install product.lic

Note that this example assumes that you have bought a TrueLicense certificate for each edition and completed certifying your project. If this is not the case, then this command still works, but the following notice is printed:

Mar 10, 2015 3:26:59 PM hH$a a
NOTICE:
This software is using TrueLicense 2. TrueLicense 2 is covered by a commercial
license agreement and the AGPLv3 - see
http://truelicense.schlichtherle.de/license.html .

You see this message because this software is currently subject to the terms of
the AGPLv3. This implies that the source code for this software must be
available for free. If this is not the case, please contact the software vendor.

For the remainder of this page, it is assumed that this process has been completed so that this notice is not printed.

Loading the License Key

You can load the installed license key using:

$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar load
net.truelicense.api.License@a7c825cc[subject="Product 1", holder="CN=Anonymous User", issuer="CN=Company Inc.", issued=Thu Mar 28 15:08:51 CET 2013, notBefore=null, notAfter=null, consumerType="User", consumerAmount=1, info=null]

A brief representation of the encoded license bean is written to the standard output stream.

If no license key is installed, then a net.truelicense.api.LicenseManagementException is thrown instead (using the standalone JAR for a readable stack trace):

$ java -jar *-keymgr/target/*-keymgr-*-standalone.jar load
net.truelicense.api.LicenseManagementException: java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:103)
    at net.truelicense.core.TrueLicenseManager.view(BasicLicenseManager.java:61)
    at com.company.product.keymgr.Main$5.run(Main.java:48)
    at com.company.product.keymgr.Main.process(Main.java:115)
    at com.company.product.keymgr.Main.processAndHandleExceptions(Main.java:97)
    at com.company.product.keymgr.Main.main(Main.java:90)
Caused by: java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".
    at net.truelicense.spi.io.PreferencesStore.checkedData(PreferencesStore.java:48)
    at net.truelicense.spi.io.PreferencesStore.input(PreferencesStore.java:64)
    at net.truelicense.v2.base.V2Encryption$2$1.call(V2Encryption.java:61)
    at net.truelicense.v2.base.V2Encryption$2$1.call(V2Encryption.java:57)
    at net.truelicense.core.crypto.BasicEncryption.wrap(BasicPbeEncryption.java:53)
    at net.truelicense.v2.base.V2Encryption.access$300(V2Encryption.java:24)
    at net.truelicense.v2.base.V2Encryption$2.input(V2Encryption.java:57)
    at net.truelicense.v2.base.V2Compression$2.input(V2Compression.java:47)
    at JsonCodec.decode(JsonCodec.java:76)
    at net.truelicense.core.TrueLicenseManager.decodeRepository(BasicLicenseManager.java:177)
    at net.truelicense.core.TrueLicenseManager.authenticate(BasicLicenseManager.java:173)
    at net.truelicense.core.CachingLicenseConsumerManager.authenticate(CachingLicenseConsumerManager.java:87)
    at net.truelicense.core.TrueLicenseManager.decodeLicense(BasicLicenseManager.java:169)
    at net.truelicense.core.TrueLicenseManager$3.call(BasicLicenseManager.java:64)
    at net.truelicense.core.TrueLicenseManager$3.call(BasicLicenseManager.java:61)
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:100)
    ... 5 more

Verifying the License Key

You can verify the installed license key using:

$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar verify

Note that no output is produced.

If no license key is installed, then a net.truelicense.api.LicenseManagementException is thrown instead (using the standalone JAR for a readable stack trace):

$ java -jar *-keymgr/target/*-keymgr-*-standalone.jar verify
net.truelicense.api.LicenseManagementException: java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:103)
    at net.truelicense.core.TrueLicenseManager.verify(BasicLicenseManager.java:70)
    at com.company.product.keymgr.Main$6.run(Main.java:54)
    at com.company.product.keymgr.Main.process(Main.java:115)
    at com.company.product.keymgr.Main.processAndHandleExceptions(Main.java:97)
    at com.company.product.keymgr.Main.main(Main.java:90)
Caused by: java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".
    at net.truelicense.spi.io.PreferencesStore.checkedData(PreferencesStore.java:48)
    at net.truelicense.spi.io.PreferencesStore.input(PreferencesStore.java:64)
    at net.truelicense.v2.base.V2Encryption$2$1.call(V2Encryption.java:61)
    at net.truelicense.v2.base.V2Encryption$2$1.call(V2Encryption.java:57)
    at net.truelicense.core.crypto.BasicEncryption.wrap(BasicPbeEncryption.java:53)
    at net.truelicense.v2.base.V2Encryption.access$300(V2Encryption.java:24)
    at net.truelicense.v2.base.V2Encryption$2.input(V2Encryption.java:57)
    at net.truelicense.v2.base.V2Compression$2.input(V2Compression.java:47)
    at JsonCodec.decode(JsonCodec.java:76)
    at net.truelicense.core.TrueLicenseManager.decodeRepository(BasicLicenseManager.java:177)
    at net.truelicense.core.TrueLicenseManager.authenticate(BasicLicenseManager.java:173)
    at net.truelicense.core.CachingLicenseConsumerManager.authenticate(CachingLicenseConsumerManager.java:87)
    at net.truelicense.core.TrueLicenseManager.decodeLicense(BasicLicenseManager.java:169)
    at net.truelicense.core.CachingLicenseConsumerManager.validate(CachingLicenseConsumerManager.java:76)
    at net.truelicense.core.TrueLicenseManager$4.call(BasicLicenseManager.java:73)
    at net.truelicense.core.TrueLicenseManager$4.call(BasicLicenseManager.java:70)
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:100)
    ... 5 more

If a license key is installed, but the encoded license bean is invalid, then a net.truelicense.api.LicenseValidationException is thrown instead (using the standalone JAR for a readable stack trace):

$ java -jar *-keymgr/target/*-keymgr-*-standalone.jar verify
net.truelicense.api.LicenseValidationException: License validity period has expired at Wednesday, February 11, 2015 4:20:20 PM CET.
    at net.truelicense.core.TrueLicenseValidation.validate(BasicLicenseValidation.java:82)
    at net.truelicense.core.CachingLicenseConsumerManager.validate(CachingLicenseConsumerManager.java:79)
    at net.truelicense.core.TrueLicenseManager$4.call(BasicLicenseManager.java:73)
    at net.truelicense.core.TrueLicenseManager$4.call(BasicLicenseManager.java:70)
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:100)
    at net.truelicense.core.TrueLicenseManager.verify(BasicLicenseManager.java:70)
    at com.company.product.keymgr.Main$6.run(Main.java:54)
    at com.company.product.keymgr.Main.process(Main.java:115)
    at com.company.product.keymgr.Main.processAndHandleExceptions(Main.java:97)
    at com.company.product.keymgr.Main.main(Main.java:90)

Uninstalling the License Key

You can uninstall the license key using:

$ java -jar *-keymgr/target/*-keymgr-*-guarded.jar uninstall

Note that no output is produced.

If no license key is installed or only an auto-generated FTP license key is installed, then a net.truelicense.api.LicenseManagementException is thrown instead:

$ java -jar *-keymgr/target/*-keymgr-*-standalone.jar uninstall
net.truelicense.api.LicenseManagementException: java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:103)
    at net.truelicense.core.TrueLicenseManager.uninstall(BasicLicenseManager.java:80)
    at net.truelicense.core.CachingLicenseConsumerManager.uninstall(CachingLicenseConsumerManager.java:66)
    at com.company.product.keymgr.Main$7.run(Main.java:60)
    at com.company.product.keymgr.Main.process(Main.java:115)
    at com.company.product.keymgr.Main.processAndHandleExceptions(Main.java:97)
    at com.company.product.keymgr.Main.main(Main.java:90)
Caused by: java.io.FileNotFoundException: Cannot locate the key "Product 1" in the user preferences node for the absolute path "/com/company/product/keymgr".
    at net.truelicense.spi.io.PreferencesStore.checkedData(PreferencesStore.java:48)
    at net.truelicense.spi.io.PreferencesStore.input(PreferencesStore.java:64)
    at net.truelicense.v2.base.V2Encryption$2$1.call(V2Encryption.java:61)
    at net.truelicense.v2.base.V2Encryption$2$1.call(V2Encryption.java:57)
    at net.truelicense.core.crypto.BasicEncryption.wrap(BasicPbeEncryption.java:53)
    at net.truelicense.v2.base.V2Encryption.access$300(V2Encryption.java:24)
    at net.truelicense.v2.base.V2Encryption$2.input(V2Encryption.java:57)
    at net.truelicense.v2.base.V2Compression$2.input(V2Compression.java:47)
    at JsonCodec.decode(JsonCodec.java:76)
    at net.truelicense.core.TrueLicenseManager.decodeRepository(BasicLicenseManager.java:177)
    at net.truelicense.core.TrueLicenseManager.authenticate(BasicLicenseManager.java:173)
    at net.truelicense.core.CachingLicenseConsumerManager.authenticate(CachingLicenseConsumerManager.java:87)
    at net.truelicense.core.TrueLicenseManager$5.call(BasicLicenseManager.java:87)
    at net.truelicense.core.TrueLicenseManager$5.call(BasicLicenseManager.java:80)
    at net.truelicense.core.TrueLicenseManager.wrap(BasicLicenseManager.java:100)
    ... 6 more