NAME

gmitool - a Net::Gemini command line tool

SYNOPSIS

gmitool get [-A] [-E encoding-layer] [-C cert-file -K key-file] \
            [-H sni-host] [-S] [-V peer|none] \
            [-f] [-l] [-q] [-t seconds] \
            gemini://example.org
gmitool link [-b base-url] < text-gemini-content

DESCRIPTION

gmitool offers various gemini protocol related utilities. It is part of the Net::Gemini module. Subcommands include:

get

Gets a gemini page and prints it to standard out, if all goes well (garbage in, garbage out). Options:

-A

Accept verified leaf certificates without going through the usual TOFU path, assuming that the certificate can be verified. Probably good with sites that use "Let's Encrypt" as these certificates change frequently and would otherwise need the use of the -f flag to force updates, and usually will (but may not) verify correctly.

-C certificate-file

Client certificate file, use with -K for when gmitool must use a custom certificate.

-E encoding-layer

Specifies the output encoding should the remote content have charset associated with it; the default in such a case is to convert to UTF-8. If set to the empty string -E '' then :raw will be used--garbage in, garbage out. Otherwise, the encoding-layer should be something Perl supports such as :encoding(UTF-8).

-K key-file

Client private key file, use with -C.

-H hostname

Use the given hostname as the SNI host instead of the default that is taken from the URL given.

-S

Show various diagnostic information (the META field, redirects, etc).

-V mode

Specifies a custom certificate verification mode. By default Trust On First Use (TOFU) is used, which only checks the first leaf certificate against the known_hosts table.

Verification modes include peer to verify the peer certificates (the full chain), and none to do no verification. See also -A.

The SSL_CERT_FILE and SSL_CERT_DIR environment variables can be used to customize the trusted certificate authority certificates.

-f

Force update of TOFU certificates. Use -q to hide the warnings. Updates to the cache will not happen if -A is used and the certificate can be verified.

-l

Only show the links of the content if the response is text/gemini.

-q

Do not show a warning when force updating a changed certificate.

-t seconds

Custom connect timeout, 30 seconds by default.

link

Extracts link from text/gemini input, and qualifies any relative links if the -b base-url option is given. Only shows relative links if the -r option is given.

ENVIRONMENT

GMITOOL_HOSTS

Custom known hosts file.

SSL_CERT_DIR

Custom directory for SSL certificate authority certificates. The default is the operating system (OS) default, which could be /etc/ssl or similar. Customize this and the next to specify that only certain certificate authorities should be trusted, as opposed to everything that ships with the OS by default.

env SSL_CERT_DIR=/some/where SSL_CERT_FILE=/dev/null gmitool ...

SSL_CERT_FILE

Custom file for SSL certificate authorities.

FILES

~/.cache/gmitool/known_hosts is where the TOFU records are stored by default. JSON format, UTF-8 encoding.

EXIT STATUS

The gmitool utility exits 0 on success, and >0 if an error occurs.

SEE ALSO

Net::Gemini, ftp(1), openssl(1), nc(1)

AUTHOR

Jeremy Mates