initial commit

ask.1

@@ -0,0 +1,93 @@
+.TH ASK 1 "July 2026" "ask" "User Commands"
+.SH NAME
+ask \- answer command-line questions using an LLM
+.SH SYNOPSIS
+.B ask
+[OPTION...] \fIquestion\fR
+.SH DESCRIPTION
+.B ask
+consults an OpenAI-compatible LLM backend to answer questions about
+Unix/Linux command-line tools. It has three operating modes.
+.PP
+In the default (command) mode,
+.B ask
+identifies the relevant tool, fetches its TLDR page and man page for
+context, and returns a single runnable command line with placeholders
+for arguments you need to customize.
+.PP
+In question mode (\fB\-q\fR), it answers general command-line questions
+and renders the response in markdown through
+.BR glow (1).
+.PP
+In history mode (\fB\-H\fR), it reads the last 200 lines of your shell
+history (\fI~/.zsh_history\fR, \fI~/.bash_history\fR, or
+\fI~/.history\fR) and answers questions about commands you have run.
+.SH OPTIONS
+.TP
+.B \-h
+Display help text and exit.
+.TP
+.B \-q
+Question mode. Answer general command-line questions with markdown
+output rendered through
+.BR glow (1).
+.TP
+.B \-H
+History mode. Answer questions about your shell history.
+.TP
+.B \-p
+Paginate output through
+.BR less (1)
+with raw character support (\fB\-R\fR).
+.SH ENVIRONMENT
+.TP
+.B OPENAI_BASE_URL
+API endpoint URL.
+Default: \fBhttp://10.0.2.145:8090/v1\fR
+.TP
+.B OPENAI_API_KEY
+API key to include as a Bearer token in requests.
+Optional, depending on the server.
+.TP
+.B OPENAI_MODEL
+Model identifier to use.
+Default: \fBgpt-4o-mini\fR
+.SH EXAMPLES
+.TP
+Generate a command to find large files:
+.B ask how to find large files
+.TP
+Explain how rsync works (question mode):
+.B ask \-q how does rsync work
+.TP
+Check recent Docker usage (history mode):
+.B ask \-H what command did I use for docker yesterday
+.TP
+Paginate output with less:
+.B ask \-p how to compress a directory
+.SH EXIT STATUS
+.TP
+0
+Successful execution.
+.TP
+1
+No question provided, or an API error occurred.
+.SH FILES
+.TP
+.I ~/.zsh_history
+.TP
+.I ~/.bash_history
+.TP
+.I ~/.history
+Shell history files consulted in \fB\-H\fR mode.
+.SH DEPENDENCIES
+The following tools are expected at runtime:
+.BR tldr (1),
+.BR man (1),
+.BR col (1),
+.BR glow (1),
+.BR less (1).
+.SH BUGS
+Report issues at \fIhttps://github.com/anomalyco/opencode/issues\fR.
+.SH AUTHORS
+Ole