GOLF(2gg)

💖 GOLF(2gg) — the command-line glow-up 💖

okay bestie, this is the GOLF(2gg) page, and it's the one about running your Golf app as an actual command-line program. Come sit with me, we're doing this properly. ✨

---

🌸 NAME 🌸

command-line — Golf documentation (running-application). That's the whole vibe. It's giving "how do I run this thing from a terminal". 🫶

---

✨ DESCRIPTION ✨

So a Golf application can run as a web application, or a command-line program, or honestly both — like when some requests can either be fulfilled through the web interface or executed otherwise (such as on the command line). Versatile queen behavior. 👑

Lowkey important: Golf produces two separate executables — a service one and a command-line one. They are different because the command-line program does not need the service library and thus is smaller. Baby executable. Tiny. Precious. 🎀

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). Same energy, different destination. 💅

💀 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. So like, it will leave on its own, but if you want it to leave on purpose, that's your move. 🙈

🔥 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"

no cap, that last one just spits the shell code out at you instead of running it. chef's kiss. 😌

🦋 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). Not optional bestie, all three. ✋

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. Order matters, do it before, not after. ⭐

👑 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. So: same result, but make it global. 🌍

💜 URL-ENCODING THE INPUT 💜

Any data in "--req" option (and consequently in PATH_INFO or QUERY_STRING environment variables 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. Lucky you, skip away. 🧚

🍓 CGI 🍓

You can also use a command-line program with CGI (Common Gateway Interface). Yes really. Retro but make it cute. 🌸

---

⭐ SEE ALSO ⭐

• Running application
• application-setup
• CGI
• command-line
• service
• See all documentation

---

and that's the whole page, bestie!! 💖 go forth and run your little executable, it's gonna slay. This was $VERSION of the docs, dated $DATE, from the GOLF(2gg) Development era — ily, mwah, bye!! 🫶✨🎀🦋