gelim.1

.\" Generated by scdoc 1.10.1
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "gelim" "1" "2024-12-14" "" "line-mode smolnet client"
.P
.SH NAME
.P
\fBgelim\fR - a minimalist gemini, spartan, and nex protocol client
.P
.P
.SH SYNOPSIS
.P
\fBgelim\fR [ \fIOPTIONS\fR ] [ \fIURL\fR ]
.P
.P
.SH OPTIONS
.P
\fB--help\fR, -h
.RS 4
get cli help/usage
.P
.RE
\fB--input\fR, -i \fIstring\fR
.RS 4
append "?" + \fIstring\fR percent-encoded to \fIURL\fR (will be ignored if URL not provided)
.P
.RE
\fB--no-interactive\fR, -I
.RS 4
don't enter the line-mode interface (useful for just wanting to view \fIURL\fR then exit)
.P
.RE
\fB--search\fR, -s \fIstring\fR
.RS 4
search \fIstring\fR with the search engine. this takes priority over \fIURL\fR and
\fB--input\fR (which means \fIURL\fR and \fB--input\fR will be ignored if this flag is used)
.P
.RE
\fB--config\fR, -c \fIpath\fR
.RS 4
specify a non-standard config location (see \fBFILES\fR)
.P
.P
.RE
.SH INTERFACE
.P
just run \fIgelim\fR and optionally provide a url. it will start the line-mode interface.
at the prompt, you can directly enter a url, link index, or otherwise a command.
.P
Commands are parsed by spaces, with support for shell-like quoting and escaping.
.P
Gelim uses a lightweight readline-like library for parsing the command line
within the line-mode interface. By default, the prompt shows the current URL and
a ">" symbol, this can be configured (see \fBCONFIGURATION\fR).
.P
At the prompt, common line editing keys are supported. Completion for gelim's
commands are also supported through \fBTAB\fR and \fBShift+TAB\fR.
.P
.SS COMMANDS
.P
For details on each command, please consult the built-in help interface.
.P
\fBhelp\fR, h, ? \fI[command]\fR
.RS 4
get help for the interface
.P
.RE
\fBquit\fR, exit, q, x
.RS 4
exit the program
.P
.RE
\fBback\fR, b
.RS 4
go to previous url in history
.P
.RE
\fBforward\fR, f
.RS 4
go to next url in history
.P
.RE
\fBhistory\fR, hist, his \fI[number]\fR
.RS 4
print history, or visit an item in history
.P
.RE
\fBreload\fR, r
.RS 4
reload current page
.P
.RE
\fBpage\fR, p, view, print, display
.RS 4
reload current page
.P
.RE
\fBlinks\fR, link, peek, l \fI[number]\fR
.RS 4
get link for link-index \fInumber\fR (what the link links to).
if no \fInumber\fR specified, it prints a list of all the links in the current page
.P
.RE
\fBurl\fR, current, cur, u
.RS 4
print current url
.P
.RE
\fBediturl\fR, e, eu, edit
.RS 4
edit and visit current url
.P
.RE
\fBcopyurl\fR, cu
.RS 4
copy current url to clipboard using \fIclipboardCopyCmd\fR (see
\fICONFIGURATION\fR).
.P
.RE
\fBsearch\fR, s \fIquery\fR...
.RS 4
search \fIquery\fR with search engine
.P
.RE
\fBredirects\fR, redir
.RS 4
show redirects
.P
.RE
\fBtour\fR, t, loop [ \fIgo\fR | \fIls\fR | \fIranges or numbers\fR... ]
.RS 4
save a list of URLs into a tour list. on each \fItour\fR invokation, visit the
next item in tour.
.P
.RE
\fBconfig\fR [ \fIe[dit]\fR | \fIr[eload]\fR ]
.RS 4
edit or reload the currently active configuration.
.P
.RE
.SH CONFIGURATION
.P
An optional configuration file can be specified at
\fI$XDG_CONFIG_HOME/gelim/config.toml\fR.
.P
Configuration should be written in TOML format. For example:
.P
.nf
.RS 4
prompt = "-->"
startURL = "example\&.com"
searchURL = "gemini://kennedy\&.gemi\&.dev/search"
clipboardCopyCmd = "pbcopy"
maxRedirects = 5
useCertificates = [
    "gemini://astrobotany\&.mozz\&.us/app",
    "gemini://bbs\&.geminispace\&.org",
]
.fi
.RE
.P
Keys are case-insensitive.
.P
\fBstartURL\fR = \fIURL\fR
.RS 4
The URL to visit when starting gelim without arguments.
Defaults to an empty string, which disables this feature.
.P
.RE
\fBsearchURL\fR = \fIURL\fR
.RS 4
The query will be sent to this URL as \fIURL\fR?\fIquery\fR for the \fIsearch\fR command
and the \fI--search\fR CLI flag.
.P
Default is "gemini://kennedy.gemi.dev/search".
.P
.RE
\fBclipboardCopyCmd\fR = \fISTRING\fR
.RS 4
Contents will be piped as stdin when the \fIcopyurl\fR (or other) command is
used which copies something into the system clipboard.
.P
Defaults to an empty string, which disables this feature.
.P
.RE
\fBmaxRedirects\fR = \fINUMBER\fR
.RS 4
Control whether to ask for confirmation when a page redirects the client.
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
0: Always confirm redirects
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
>0: Ask to confirm redirects after a set number of redirects
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
<0: Never confirm redirects

.RE
.P
This is \fI5\fR by default, following the RFC-2068.
.P
.RE
\fBmaxWidth\fR = \fINUMBER\fR
.RS 4
Each page will be rendered to maximum of max(\fImaxWidth\fR, terminal width)
columns wide for gemtext documents, and centered.
.P
Set to \fI0\fR to always use the terminal width.
.P
Set to negative X to use a maxWidth of X but disable centering.
.P
For plain text documents, Nex directories, and gophermaps, the page will be
centered based on the maximum width of the text in the document.
.P
Default is \fI70\fR.
.P
.RE
\fBuseCertificate\fR = \fILIST\fR
.RS 4
The list of full URL prefixes (including scheme) that should use the client
certificate. The certificate and key files should be in the same directory
as the default config file location. Symlinks are supported.
.P
See \fBCLIENT CERTIFICATES\fR for more information.
.P
By default, this is an empty list.
.P
.RE
\fBprompt\fR = \fISTRING\fR
.RS 4
Newlines are supported. The default prompt is "%Un>". Here are the
available components:
.P
.RE
.TS
allbox;l l lx
l l lx
l l lx
l l lx
l l lx
l l lx
l l lx.
T{
\fBName\fR
T}	T{
\fBReplacement\fR
T}	T{
\fBExample\fR
T}
T{
%U
T}	T{
Full URL including scheme and query
T}	T{
gemini://example.org/file/path.gmi?query
T}
T{
%u
T}	T{
Full URL without scheme and query
T}	T{
example.org/file/path.gmi
T}
T{
%P
T}	T{
Full path
T}	T{
/file/path.gmi
T}
T{
%p
T}	T{
Basename in path
T}	T{
path.gmi
T}
T{
%H
T}	T{
Full hostname with port
T}	T{
x.example.org:1965
T}
T{
%h
T}	T{
Hostname without port
T}	T{
x.example.org
T}
.TE
.sp 1
.RS 4
.P
Note that gopher type selectors are stripped for both \fI%P\fR and \fI%p\fR.
.P
.RE
.SH CLIENT CERTIFICATES
.P
To use a client certificate on certain gemini sites for authentication, you
should prepare PEM-encoded files for the certificate and the key. Place them in
the gelim config directory (see \fBFILES\fR), named \fIcert.pem\fR and \fIkey.pem\fR
respectively. Symlinks are supported.
.P
On startup, gelim will look for these two files in the config directory and
attempt to load these as a client certificate.
.P
To use the client certificate, list the URLs that you want to use it on in the
\fBuseCertificate\fR config option:
.P
.nf
.RS 4
useCertificates = [
    "gemini://example\&.org",
]
.fi
.RE
.P
In this example, or URLs that begins with "gemini://example.org" will use your
client certificate.
.P
.SH FILES
.P
The config directory \fI$XDG_CONFIG_HOME/gelim/\fR is used by default. This is
usually \fI~/.config/gelim/\fR. A different directory can be specified using the
\fB--config\fR option.
.P
The following files are read by gelim, relative to the config directory.
.P
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
config.toml (see \fBCONFIGURATION\fR)
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
cert.pem
.RE
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.IP \(bu 4
.\}
key.pem

.RE
.P
.SH SEE ALSO
.P
A \fIREADME.md\fR file should be included in your \fBgelim\fR installation. \fBgelim\fR also
includes a built-in help functionality accessible through the \fBhelp\fR command.
.P
Up-to-date information and source code can also be found at
\fIhttps://github.com/hedyhli/gelim\fR.
.P
.SH AUTHORS
.P
Created and maintained by ~hedy <\fIhedy.dev@protonmail.com\fR>.