The Hogan application runs a full set of servers from its binary, but it also provides CLI options for accomplishing a variety of tasks. This document provides those options and details about how to use them.
To view the options, simply invoke hogan from the CLI with the -h option. This will be different depending on how you installed the application.
Linux (.deb)
If you installed with the Linux .deb installer, invoke Hogan CLI like this.
sudo hogan -h
Windows
If you installed into a local directory on Windows, invoke it like this from within the root hogan install directory. This is the directory with hogan.bat file.
hogan -h
Other System
If you installed on Linux, Unix, MacOS, or some other system from the binary distribution, invoke hogan from the root hogan application directory like this.
sh hogan.sh -h
Once you run the help option, you should get a response something like this.
usage: hogan [options]
-a,--api generate the OpenAPI API definition for file
-ac,--admin-creds sets the admin credentials
-d,--doc generate aussomdoc for file
-e,--encrypt <arg> encrypts the provided string argument
-h,--help print this message
-k,--genKey generates a random SHA1 key and prints to stdout
-o,--outdir <arg> the output directory to place the generated file
-v,--version print the version information
These are the various options which I'm going to describe in detail now. I think the 'version' one is self-explanatory, so I won't cover it here, it prints version information.
This option generates a new random SHA1 key. This is helpful if you're just getting stared with Hogan and don't already have a key. You can use this function to generate one that you'll need. The key is important because one needs to be set for the application which is used in the Web Admin Interface authentication as well as for encrypted properties within your own apps.
This option starts the interactive process to set the Web Admin Interface credentials. This needs to be done prior to starting up the Hogan server, or you won't be able to log in to the Web Admin Interfce.
This option is really useful. It encrypts the string you provide as an argument. If the string to encrypt has special characters or spaces, it's a good idea to enclose it in quotes. The result is an encrypted string that you can safely use in your application instead of a plain text value such as a username or password. This function uses the encryption key you set for the application on installation and in your app code, you can decode it with the props decrypt function like this.
encrypted_str = "GGj3kdOJ ... 7sSa+Q==";
decrypted_str = props.decrypt(encrypted_str);
The -d option is used with the -o option to specify that you want to create a doc and the -o provides an optional output directory to place the generated doc. So if not specified (with -o) the program will put the generated doc in the same directory as the source file. Here's an example of how to use it.
hogan -d -o docs libs/user.aus
In this example, the -d tells the app we want to genreate a doc. The -o with 'docs' right after it tells it to put the output file in the 'docs' subdirectory. Finally, the -d option takes a final string argument that is the .aus file to generate the doc from. This process is accomplished by the Aussom interpreter reading source code comments for classes, variables, functions, and the file itself and converting them into a markdown document. In this example, the generated doc would be written to docs/user.aus.md.
The -a option is used with the -o option to specify that you want to create an OpenAPI specification and the -o provides an optional output directory to place the generated API. So if not specified (with -o) the program will put the generated API in the same directory as the source file. Here's an example of how to use it.
hogan -a -o . test-apps/hogan_xapi/hogan_xapi.aus
In this example, the -a tells the app we want to genreate an API. The -o
with '.' right after it tells it to put the output file in the current
directory. Finally, the -a option takes a final string argument that is
the .aus file to generate the API from. This process is accomplished by
the Aussom interpreter reading source code comments for classes, variables,
functions, and the file itself and converting them into an OpenAPI
specification.
Note: The Aussom class name inside the .aus file is expected to be the same as the file name without the extension. So in this case the file name is 'hogan_xapi.aus', the class name needs to be 'hogan_xapi'.