llmq.1

.\" llmq.1
.TH LLMQ 1 "18 May 2023" "Version 0.2.1" "llmq User Manual"

.SH NAME
llmq \- a query CLI and context manager for LLM-powered shell pipelines.

.SH SYNOPSIS
.B llmq
[\fB\-hqiv\fR]
[\fIACTION\fR]
[\fIPLUGIN\fR][://[\fB~\fR]\fICONTEXT\fR]
[\fIOPTIONS\fR]...
[\fB--\fR]
[\fIMSGS\fR]...

.SH DESCRIPTION
.B llmq
is essentially a wrapper for LLM API plugins that manages command-line
arguments, context and configuration files, authentication, and I/O.
See the README to develop your own plugins.
.PP
Each plugin defines paths for configuration and conversation context storage,
which are $XDG_CONFIG_HOME/llmq/PLUGIN and $XDG_DATA_DIR/llmq/PLUGIN by default
(or ~/.config/llmq/PLUGIN and ~/.local/share/llmq/PLUGIN if XDG dirs not defined).
Directories are created if they do not exist.
.PP
llmq can also create and use temporary context files, which are stored in
/tmp/llmq/PLUGIN. Any CONTEXT argument that begins with '~' is stored
relative to the temp directory, not the data directory. Additionally,
calling init without CONTEXT will create a unique temporary file and
print its name.

.SH LLMQ FLAGS
.TP
.B \-h, \-\-help
display a help message and exit.
.TP
.B \-q, \-\-quiet
do not print reply to stdout (chat mode only).
.TP
.B \-i, \-\-no-stdin
does not read from stdin, even if MSGS is missing (query/chat). 
.TP
.B \-v, \-\-verbose
print cURL and other llmq diagnostics to stderr.

.TP
note: any flags after PLUGIN are considered OPTIONS

.SH ACTION
.TP
\fIq query\fR
queries and streams response without saving (context optional).
.TP
\fIc chat\fR
queries, streams response, and updates context.
.TP
\fIi init\fR
(re-)initializes the context file using OPTIONS.
.TP
\fIe edit\fR
edits the context file with $EDITOR or vi.
.TP
\fIa auth\fR
edits the authfile with $EDITOR or vi.
.TP
\fIp path\fR
prints the absolute filepath of the context or datadir.
.TP
\fId del\fR
deletes the CONTEXT file.
.TP
\fIk kill\fR
terminates all llmq processes with CONTEXT open, if able.
.TP
\fIl list\fR
list all available plugins and their descriptions.
.TP
\fIh help\fR
display the plugin help and exit.

.TP
notes:
.P
- ACTION always required, except when using -h
.br
- CONTEXT required for c|e|d|k.
.br
- OPTIONS/MSGS/stdin ingored for e|a|p|d|k|l|h
.br
- stdin ignored for i

.SH PLUGIN
At present, gpt is the only plugin available.
.br
See `llmq help gpt` for more info.

.SH CONTEXT
A YAML-encoded query/chat context file (e.g. model parameters, messages).
.br
CONTEXT omits the '.yml' suffix present on all context files.
.br
If CONTEXT begins with '~', it is stored in the temp directory.

.SH OPTIONS
Named arguments or flags to pass to the plugin.

.SH MSGS
Positional plugin args. Typically messages, but depends on the plugin.
.br
If ACTION is query or chat (without -i), reads stdin into one MSG.

.SH EXAMPLES
.P
Prepare a calculator prompt
.br
.B llmq init gpt://calc -m gpt-4 -s 'act as a calculator and print only the result of the expression'
.P
Send a request and stream the response to stdout
.br
.B llmq query gpt://calc '4 + 36' # 40
.P
Chain invocations
.br
.B echo '24 * 52' | llmq q gpt://calc | sed 's/$/ \\\/ 13/' | llmq q gpt://calc' # 96
.P
Prepare a temporary chat
.br
.B CTX=`llmq init gpt -m gpt-4 -S true`
.P
Update the chat with each new message
.br
.B llmq chat $CTX 'Hello!' # Hello! How can I help you today?
.br
.B llmq chat $CTX 'What did I say before this?' # Before this, you said, \(lqHello!\(rq
.P
Get the path of the chat
.br
.B llmq path $CTX

.SH AUTHOR
Written by Justin Collier.

.SH COPYRIGHT
.P
Copyright (C) 2023 Justin Collier <m@jpcx.dev>
.P
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as
published by the Free Software Foundation, either version 3 of the
License, or (at your option) any later version.
.P
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.
.P
You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.