NAME¶

command-line - Golf documentation (running-application)

DESCRIPTION¶

A Golf application can run as a web application or a command-line program, or both - such as when some requests can be either fulfilled through web interface or executed otherwise (such as on the command line). Note that Golf produces two separate executables: a service one and a command-line one - they are different because command-line program does not need the service library and thus is smaller.

The name of the command-line executable is the same as the application name, and its path is (assuming <app name> is the application name):

/var/lib/gg/bld/<app name>/<app name>

OUTPUT

A command-line program works the same way as a service executable, and the output is the same, except that it is directed to stdout (standard output) and stderr (standard error).

EXIT CODE

To specify the exit code of a command-line program, use exit-status. To exit the program, use exit-handler, or otherwise the program will exit when it reaches the end of a request.

EXECUTING A REQUEST

Here is how to execute a request "add-stock" in application "stock" with parameters "name" having a value of "ABC" and "price" a value of "300":

gg -r --app="/stock" --req="/add-stock?name=ABC&price=300" --exec

Note that you if specify parameters as part of the path, you could write the above the same way as in a URL:

gg -r --app="/stock" --req="/add-stock/name=ABC/price=300" --exec

You can generate the shell code to execute the above without using gg by omitting "--exec" option, for instance:

gg -r --app="/stock" --req="/add-stock/name=ABC/price=300" 

INCLUDING A REQUEST BODY

You can include a request body when executing a singe-run program. It is always included as the standard input (stdin) to the program.

You must provide the length of this input and the type of input, as well as a request method (such as POST, PUT, PATCH, GET, DELETE or any other).

Here is an example of using a request body to make a POST request on the command line - the application name is "json" and request name is "process". File "prices.json" is sent as request body:

gg -r --app=/json --req='/process?act=get_total&period=YTD' --method=POST --content=prices.json --content-type=application/json --exec

You can generate the shell code for the above by omitting "--exec" option of gg utility.

Note that you can also include any other headers as environment variables by using the "HTTP_" convention, where custom headers are capitalized with use of underscore for dashes and prefixed with "HTTP_", for example header "Golf-Header" would be set as:

export HTTP_GOLF_HEADER="some value"

You would set the "HTTP_" variable(s) prior to executing the program.

SUPPRESSING HTTP HEADER OUTPUT FOR THE ENTIRE APPLICATION

If you wish to suppress the output of HTTP headers for all requests, use "--silent-header" option in "gg -r":

gg -r --app="/stock" --req="/add-stock/name=ABC/price=300" --exec --silent-header

This will suppress the output of HTTP headers (either the default or with out-header), or for any other case where headers are output. This has the same effect as silent-header, the only difference is that the environment variable applies to the entire application.

URL-ENCODING THE INPUT

Any data in "--req" option (and consequently in PATH_INFO or QUERY_STRING environment vairables if calling directly from shell) must be formatted to be a valid URL; for example, data that contains special characters (like "&" or "?") must be URL-encoded, for instance:

gg -r --app="/stock" --req="/add-stock/name=ABC%3F/price=300" 

In this case, parameter "name" has value of "ABC?", where special character "?" is encoded as "%3F".

To make sure all your input parameters are properly URL-encoded, you can use Golf's v1 code processor:

$($(gg -l)/v1 -urlencode '<your data>')

For instance, to encode "a?=b" as a parameter:

gg -r --app="/stock" --req="/add-stock/name=$($(gg -l)/v1 -urlencode 'AB?')/price=300" 

If your parameters do not contain characters that need URL encoding, then you can skip this.

CGI

You can also use a command-line program with CGI (Common Gateway Interface).

SEE ALSO¶

Running application

application-setup CGI command-line service See all documentation