Vely logo install | documentation | examples | articles | changelog
16.6.0 released on Mar 08, 2023 | articles updated on Mar 20, 2023

Command line

Command-line programs

A Vely 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 the command line. Note that Vely produces two separate executables: a FastCGI server one and a command-line one - they are different because command-line program does not need the FastCGI 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/vv/bld/<app name>/<app name>


A command line program works the same way as a FastCGI 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-code. To exit the program, use exit-request, or otherwise the program will exit when it reaches the end of a request.

Executing a request

A command line program must obtain its request URL via environment variables, for example if the application name is "stock", here is how to execute a request "add-stock" with input-parameters "name" having a value of "ABC" and "price" a value of "300":
export SCRIPT_NAME="/stock"
export PATH_INFO="/add-stock"
export QUERY_STRING="name=ABC&price=300"

Note that you if specify parameters as part of the path, you could write the above the same way as in a URL:
export SCRIPT_NAME="/stock"
export PATH_INFO="/add-stock/name/ABC"
export QUERY_STRING="price=300"


Including a request body

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

You must provide the length of this input (as CONTENT_LENGTH environment variable), the type of input (as CONTENT_TYPE), as well as 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:
#length of the request body (of file prices.json). Use ${#VAR} for length if the content is in bash variable $VAR. 
export CONTENT_LENGTH=$(stat -c%s prices.json)

#content type (in this case application/json)
export CONTENT_TYPE="application/json"

#state the URL
export SCRIPT_NAME="/json"
export PATH_INFO="/process"
export QUERY_STRING="act=get_total&period=YTD"

#request method (POST, PUT, PATCH, GET, DELETE...)

#provide request body as the standard input to the command-line program by piping a file into it
cat prices.json | /var/lib/vv/bld/ordering/ordering
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 "Vely-Header" would be set as:
export HTTP_VELY_HEADER="some value"

Suppressing HTTP header output for the entire application

If you wish to suppress the output of HTTP headers for all requests, set environment variable VV_SILENT_HEADER to "yes" before executing the program:
This will suppress the effect of out-header, or for any other case where headers are output. This has the same effect as silent-header, the only difference is that it applies to the entire application.

URL-encoding the input

Any data in QUERY_STRING or PATH_INFO must be formatted to be a valid URL; for example, data that contains special characters (like "&" or "?") must be URL-encoded, for instance:
export QUERY_STRING="action=show&data=a%3Fb"
In this case, field "data" has value of "a?b", where special character "?" is encoded as "%3F".

To make sure all your input parameters are properly URL-encoded, use Vely's v1 code processor:
$($(vv -l)/v1 -urlencode '<your data>')
For instance, to encode "a?=b" as a parameter:
export QUERY_STRING="act=show&data=$($(vv -l)/v1 -urlencode 'a?=b')"


You can also use a command line program with CGI (Common Gateway Interface). Note that CGI programs generally exhibit much lower performance; use CGI only when warranted by a specific situation.

See also

Running application ( application_setup   CGI   Client_API   command_line   containerize_application   FastCGI   FastCGI_client   plain_C_FCGI  )  SEE ALL (documentation)

Copyright (c) 2017-2023 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Vely elephant logo (c) 2022 DaSoftver LLC. This web page is licensed under CC-BY-SA-4.0. Contact email