get.1

.\" get.1 — manual page for get(1)
.\"
.\" Author:  WaterRun
.\" GitHub:  https://github.com/Water-Run/get
.\" License: AGPL-3.0
.\"
.TH GET 1 "2026-04-19" "get 1.0" "User Commands"
.\"
.\" ====================================================================
.SH NAME
get \- get anything from your computer
.\"
.\" ====================================================================
.SH SYNOPSIS
.B get
.RI \(dq query \(dq
.RI [ flags ]
.br
.B get set
.I option
.RI [ value ]
.br
.B get config
.RI [ \-\-reset | \-\- option ]
.br
.B get cache
.RI [ \-\-clean | "\-\-unset \(dq" query \(dq ]
.br
.B get log
.RI [ \-\-clean ]
.br
.B get get
.RI [ \-\-intro | \-\-version | \-\-license | \-\-github ]
.br
.B get version
.br
.B get isok
.br
.B get help
.\"
.\" ====================================================================
.SH DESCRIPTION
.B get
accepts a natural-language
.I query,
sends it to an OpenAI-API-compatible large language model (LLM),
and executes the resulting shell command on the local device to
retrieve the requested information.
All generated commands are restricted to
.B read-only
operations and pass through multiple safety layers before execution.
.PP
.B get
ships with a bundled
.I bin/
directory containing high-performance CLI tools
.RB ( rg ,
.BR fd ,
.BR sg ,
.BR pmc ,
.BR tokei ,
.BR bat ,
.BR mdcat ,
.BR lua " (Linux only),"
and
.BR tree / treepp )
which are prepended to PATH when executing generated commands.
A lightweight edition without
.I bin/
is also available; in that case only system-installed tools are used.
.PP
Two execution modes are supported:
.TP
.B Instance mode
A single LLM call produces one command whose output is displayed
directly.
Enable with
.B "get set instance true"
or the
.B \-\-instance
per-query flag.
.TP
.B Agent mode (default)
A multi-round loop in which the LLM may execute intermediate commands
to gather information before producing a final answer.
Each response carries a protocol marker
.RB ( "<!-- CONTINUE -->" ,
.BR "<!-- FINAL -->" ,
or
.BR "<!-- INTERPRET -->" )
that controls loop continuation.
The loop is bounded by
.B max\-rounds
(default
.IR 3 ).
.\"
.\" ====================================================================
.SH COMMANDS
.\"
.SS "Query (default)"
.BI "get \(dq" query "\(dq [" flags "]"
.PP
Sends
.I query
to the configured LLM.
In agent mode the LLM may run intermediate commands before issuing a
final answer; in instance mode a single command is generated and
executed immediately.
Every command passes through the full safety pipeline.
See
.B QUERY FLAGS
for per-invocation overrides.
.\"
.SS set
.BI "get set " option " [" value ]
.PP
Sets a persistent configuration option.
Omitting
.I value
resets boolean and integer options to their defaults and clears string
options.
.B command\-pattern
has special three-way semantics; see
.B SET OPTIONS.
.\"
.SS config
.B get config
.PP
Displays all current configuration values.
The API key is displayed only as
.I set
or
.IR "not set" ;
the stored value is encrypted and cannot be retrieved.
When
.B command\-pattern
is at its default, the full built-in regex is shown followed by
.IR "(default: built-in)" .
.TP
.B \-\-reset
Resets all configuration to defaults and removes the stored API key.
.TP
.BI \-\- option
Displays the current value of one option, where
.I option
is any name from the
.B SET OPTIONS
table (e.g.\&
.BR \-\-model ,
.BR \-\-timeout ,
.BR \-\-command\-pattern ).
.\"
.SS cache
.B get cache
.PP
Displays cache status: enabled/disabled, total and per-mode entry
counts, configured limits, and file location.
.TP
.B \-\-clean
Removes all cached entries.
.TP
.BI "\-\-unset \(dq" query \(dq
Removes all entries whose query text matches
.I query
(case-insensitive).
.\"
.SS log
.B get log
.PP
Displays log status: enabled/disabled, configured maximum, entry
count, file location, and file size.
.TP
.B \-\-clean
Removes all log entries.
.\"
.SS get
.B get get
.PP
Displays all application information (name, version, author,
introduction, license, GitHub URL).
.TP
.B \-\-intro
Displays the one-line introduction.
.TP
.B \-\-version
Displays the version string (equivalent to
.BR "get version" ).
.TP
.B \-\-license
Displays the SPDX license identifier.
.TP
.B \-\-github
Displays the GitHub repository URL.
.\"
.SS version
.B get version
.PP
Prints the version string and exits.
.\"
.SS isok
.B get isok
.PP
Verifies configuration readiness.
Checks that the API key, URL, and model are all set, then sends a
minimal probe request
.RI ( max_tokens =32)
to the LLM endpoint and expects the single-word reply
.IR ok .
Exits 0 on success, 1 on failure.
.\"
.SS help
.B get help
.PP
Displays comprehensive usage help.
Also triggered by
.B \-\-help
and
.BR \-h .
.\"
.\" ====================================================================
.SH QUERY FLAGS
Per-invocation flags placed after the query string override the
persisted configuration for that query only.
.TP
.B \-\-no\-cache
Bypass the cache for this query.
.TP
.B \-\-cache
Force cache lookup and storage for this query.
.TP
.B \-\-manual\-confirm
Prompt for confirmation before executing each command.
.TP
.B \-\-no\-manual\-confirm
Skip the confirmation prompt.
.TP
.B \-\-double\-check
Enable the second LLM safety review.
.TP
.B \-\-no\-double\-check
Skip the second LLM safety review.
.TP
.B \-\-instance
Single-call instance mode.
.TP
.B \-\-no\-instance
Multi-round agent mode.
.TP
.B \-\-hide\-process
Suppress intermediate output; show only the final result.
.TP
.B \-\-no\-hide\-process
Show intermediate output.
.TP
.B \-\-vivid
Enable vivid output mode.
.TP
.B \-\-no\-vivid
Plain-text output mode.
.TP
.BI \-\-model " name"
Override the LLM model for this query.
.TP
.BI \-\-timeout " seconds"
Override the request timeout for this query.
.\"
.\" ====================================================================
.SH SET OPTIONS
Integer options accept
.B false
to disable the feature entirely (equivalent to 0).
Omitting
.I value
resets the option to its default; for string options it clears the
stored value.
.TP
.BI "key " string
LLM API key.
Stored with platform-specific secure storage
(Linux: file mode 0600; Windows: DPAPI).
Omitting
.I value
removes the stored key.
Default: empty.
.TP
.BI "url " URL
LLM API endpoint URL (OpenAI-compatible).
Default:
.IR https://api.poe.com/v1 .
.TP
.BI "model " string
LLM model identifier.
Default:
.IR gpt\-5.3\-codex .
.TP
.BI "manual\-confirm " bool
Require interactive y/N confirmation before executing each command,
including intermediate agent-mode commands.
Default:
.IR false .
.TP
.BI "double\-check " bool
Submit every generated command to a second LLM safety review.
The reviewer may revise or reject the command.
Default:
.IR true .
.TP
.BI "instance " bool
Use single-call instance mode.
.B false
enables the multi-round agent loop.
Default:
.IR false .
.TP
.BI "timeout " "int | false"
Timeout per API request, in seconds.
.B false
removes the limit.
Default:
.IR 300 .
.TP
.BI "max\-token " "int | false"
Maximum token consumption per request.
Default:
.IR 20480 .
.TP
.BI "max\-rounds " "int | false"
Maximum loop rounds in agent mode.
When the cap is reached any pending
.B "<!-- CONTINUE -->"
is forced to
.B "<!-- FINAL -->"
so the run always terminates with a concrete answer.
Ignored in instance mode.
Default:
.IR 3 .
.TP
.BI "command\-pattern " regex
Forbidden-command regex.
Three distinct invocation forms:
.RS
.TP
.B "get set command\-pattern"
(no value) — restore the built-in default blocklist.
.TP
.B "get set command\-pattern \(dq\(dq"
Disable pattern filtering entirely.
Emits a warning.
.TP
.BI "get set command\-pattern " pattern
Use a custom regex.
If the pattern does not cover the core dangerous command names a
safety warning is emitted.
.RE
.IP
Default: built-in blocklist (see
.BR SAFETY ).
.TP
.BI "system\-prompt " string
Custom system prompt appended to every LLM request.
Default: empty.
.TP
.BI "shell " string
Shell used to execute commands.
Default:
.I powershell
(Windows),
.I bash
(Linux).
.TP
.BI "log " bool
Append each query execution to the log file.
Default:
.IR true .
.TP
.BI "hide\-process " bool
Suppress intermediate output; display only the final result.
When enabled,
.B get
also suppresses its own warning/progress text for the query path
(for example external-display checks, model advisory warnings, and
cache-decision progress text).
Default:
.IR false .
.TP
.BI "cache " bool
Enable response caching.
Default:
.IR true .
.TP
.BI "cache\-expiry " "int | false"
Cache entry lifetime in days.
.B false
disables expiry.
Default:
.IR 30 .
.TP
.BI "cache\-max\-entries " "int | false"
Maximum number of cache entries to retain.
Oldest entries are removed when the cap is exceeded.
Default:
.IR 1000 .
.TP
.BI "log\-max\-entries " "int | false"
Maximum number of log entries to retain.
Oldest entries are removed when the cap is exceeded.
Default:
.IR 1000 .
.TP
.BI "vivid " bool
Vivid output mode: ANSI colours, animated Braille-dot spinners, and
optional external rendering.
Default:
.IR true .
.TP
.BI "external\-display " bool
Use bundled
.BR bat (1)
and
.BR mdcat (1)
for rendering in vivid mode.
Has no effect in plain mode; enabling it while
.B vivid
is
.I false
emits a warning.
Default:
.IR true .
.\"
.\" ====================================================================
.SH AGENT MODE
In agent mode (default;
.B instance
=
.IR false )
.B get
runs a multi-round conversation.
Each LLM response must follow one of four formats:
.TP
.B "CONTINUE — intermediate command"
A command in a
.B sh
fenced code block, followed by
.B "<!-- CONTINUE -->"
on a new line after the closing fence.
The command is executed; its output is fed back as the next user
message.
Requires further rounds.
.TP
.B "FINAL — terminal command, direct output"
A command in a
.B sh
fenced code block, followed by
.B "<!-- FINAL -->"
or no marker.
FINAL is the default when a code block is present without a
recognised marker.
The command is executed and its raw output is displayed to the user.
Terminates the loop.
.TP
.B "INTERPRET — terminal command, summarised output"
A command in a
.B sh
fenced code block, followed by
.BR "<!-- INTERPRET -->" .
The command is executed; its output is sent back to the LLM which
produces a human-readable summary.
Use sparingly; prefer FINAL.
Terminates the loop.
.TP
.B "ANSWER — direct text"
No fenced code block.
The LLM's plain-text response is displayed directly.
Used when no shell command can satisfy the query.
Terminates the loop.
.PP
The loop is hard-capped at
.B max\-rounds
(default 3).
When the final round is reached any
.B "<!-- CONTINUE -->"
is forcibly converted to
.B "<!-- FINAL -->"
so execution always yields a concrete answer.
Every command — intermediate or final — passes through the full
safety pipeline.
.\"
.\" ====================================================================
.SH SAFETY
Every generated command passes three validation layers in sequence.
.TP
.B "1. Forbidden-command pattern"
A regex match against the active
.B command\-pattern
rejects the command before execution.
.IP
The built-in blocklist uses
.B \eb\&...\eb
word boundaries and covers:
.BR rm ,
.BR rmdir ,
.BR del ,
.BR erase ,
.BR mv ,
.BR move ,
.BR cp ,
.BR copy ,
.BR mkdir ,
.BR touch ,
.BR chmod ,
.BR chown ,
.BR chgrp ,
.BR mkfs ,
.BR dd ,
.BR fdisk ,
.BR kill ,
.BR killall ,
.BR pkill ,
.BR shutdown ,
.BR reboot ,
.BR halt ,
.BR poweroff ,
.BR passwd ,
.BR useradd ,
.BR userdel ,
.BR usermod ,
.BR groupadd ,
.BR groupdel ,
.BR Set\-Content ,
.BR New\-Item ,
.BR Remove\-Item ,
.BR Move\-Item ,
.BR Rename\-Item ,
.BR Clear\-Content ,
and
.BR Add\-Content .
.IP
.BR md " and " rd
are intentionally absent: the pattern
.B \ebmd\eb
would produce false positives on extensions such as
.IR README.md .
.TP
.B "2. Double-check (default: enabled)"
A second LLM call reviews the command.
The reviewer may revise the command (returning it in a
.B sh
code block) or reject it entirely by responding with the single word
.BR UNSAFE ,
which terminates execution with exit code 1.
.TP
.B "3. Manual confirmation (default: disabled)"
An interactive y/N prompt before each command execution.
Declining exits with code 0.
.\"
.\" ====================================================================
.SH MODEL STRENGTH
At startup
.B get
normalises the configured model name (lowercase; underscores and
hyphens treated as equivalent) and checks it against a built-in
whitelist of known high-performance models.
An advisory warning is emitted when the model is unrecognised or
belongs to a reduced-capability variant; execution is not blocked.
.PP
Recognised strong families and minimum versions:
.TP
.B GPT / CodeX
version \(>= 5 (e.g.\&
.IR gpt\-5.3\-codex ).
.TP
.B Claude
.I Opus
or
.I Sonnet
version \(>= 3.5, or any Claude with version \(>= 3.7.
.TP
.B Gemini
version \(>= 3.
.TP
.B Grok
version \(>= 4.
.TP
.B MiniMax
version \(>= 2.7.
.TP
.B GLM / ChatGLM
version \(>= 4.7.
.TP
.B DeepSeek
Full variants only (non-distilled).
.TP
.B OpenAI o-series
version \(>= 3.
.PP
Models whose name contains
.BR mini ,
.BR nano ,
.BR lite ,
.BR small ,
.BR fast ,
.BR flash ,
.BR haiku ,
.BR light ,
.BR tiny ,
.BR micro ,
or
.B instant
are always treated as weak.
The families
.BR Doubao ,
.BR Qwen ,
.BR Ernie / Wenxin ,
.BR Hunyuan ,
.BR Spark ,
.BR Baichuan ,
and
.B Yi
are explicitly excluded from the whitelist.
.\"
.\" ====================================================================
.SH OUTPUT MODES
.TP
.B "plain (vivid = false)"
Unformatted text; no colours, no animations, no external rendering.
Progress spinners are replaced with dotted lines.
.TP
.B "vivid (vivid = true, default)"
ANSI colours, animated Braille-dot spinners during API requests, bold
section headers, and optional external rendering via bundled
.BR bat (1)
(help text) and
.BR mdcat (1)
(LLM-produced Markdown replies).
On Windows, virtual terminal processing is enabled automatically.
.PP
External rendering applies only to Markdown-formatted LLM replies and
help text.
Raw command output is always written to stdout directly, bypassing any
external renderer, to avoid encoding problems on Windows.
If the required binaries are absent from
.IR bin/ ,
a built-in colouriser is used and a warning listing the missing tools
is emitted.
.\"
.\" ====================================================================
.SH CACHING
.B get
uses a deferred-decision caching mechanism.
Queries are
.B not cached on first execution.
The first run merely records the query in a lightweight "seen" set.
Only when the same query is executed a second time (or when the
.B --cache
flag is explicitly passed) does
.B get
invoke the LLM to determine the optimal caching strategy.
In normal process mode, this step shows the progress text:
.I checking whether to cache...
.PP
Five caching strategies are supported:
.TP
.B GLOBAL_COMMAND
The command works in any directory; the output changes over time.
Only the command is cached globally.
On a hit the command is re-executed through the full safety pipeline
to produce fresh output.
.TP
.B GLOBAL_RESULT
The answer is universally stable (e.g.& OS name, command syntax).
The output is cached globally and returned directly on a hit.
.TP
.B CONTEXT_COMMAND
The command depends on the current working directory; the output may
change.
Only the command is cached for this directory context.
On a hit it is re-executed.
.TP
.B CONTEXT_RESULT
The result is stable within the same working directory (e.g.&
directory name, static config file content).
The output is cached for this context and returned directly.
.TP
.B NOCACHE
Neither command nor output is cached.
.PP
Three hash levels are used.
A
.I query hash
(MD5 of the lowercased query text) tracks the "seen" set.
A
.I global hash
(query + shell + model + flags + OS + arch, without the working
directory) keys global entries.
A
.I context hash
(global hash fields plus the working directory) keys context entries.
.PP
On a cache lookup the four possible hit types are checked in
priority order:
context result (most precise, fastest),
global result,
context command,
global command.
.PP
When the configuration option
.B cache
is set to
.IR false ,
all caching logic is completely disabled, including seen tracking.
When process output is not hidden, this condition emits:
.I warning: cache is disabled in config; all cache logic is bypassed
.PP
Cache behaviour is controlled by
.BR cache ,
.BR cache-expiry ,
and
.BR cache-max-entries .
Use
.B --no-cache
to bypass the cache for a single query.
Use
.B --cache
to force the caching pipeline for a single query (triggers the LLM
decision immediately, without waiting for a second execution).
.\" ====================================================================
.SH LOGGING
Each query execution is appended to the log file in timestamped lines
of the form:
.PP
.RS
.I "[YYYY-MM-DD HH:MM:SS] field: value"
.RE
.PP
Fields logged per entry: query, command, exit code, and up to 4096
characters of output.
In agent mode each intermediate round is logged separately; the query
field carries a
.RI ( "round N" )
suffix.
When the entry count exceeds
.B log\-max\-entries
the oldest entries are automatically removed.
.\"
.\" ====================================================================
.SH BUNDLED TOOLS
The following tools ship in the
.I bin/
directory and are prepended to PATH before every generated command
runs.
The LLM system prompt instructs the model to prefer these tools.
Write-mode flags (e.g.\&
.BR "pmc \-o" ,
.BR "pmc \-c" ,
.BR "tree \-o" ,
.BR "treepp /O" ,
.BR "fd \-x"
with write commands) are explicitly forbidden in the prompt.
.TP
.B rg
ripgrep — ultra-fast regex search in files.
.TP
.B fd
Fast file and directory finder.
.TP
.B sg
ast-grep — AST-level structural code search.
.TP
.B pmc
pack-my-code — packages source files into a single text block for LLM
context.
.TP
.BR tree " (Linux) / " treepp " (Windows)"
Directory tree listing.
.TP
.B tokei
Code statistics (lines of code by language).
.TP
.BR lua " (Linux only)"
Lua 5.x interpreter for calculations and text processing.
Read-only use only.
.TP
.B bat
Syntax-highlighting cat replacement.
Used by vivid mode to render help text.
.TP
.B mdcat
Terminal Markdown renderer.
Used by vivid mode to render interpreted LLM replies.
.\"
.\" ====================================================================
.SH SYSTEM REQUIREMENTS
.B get
requires a 64-bit platform (amd64 or arm64); this is enforced at
compile time.
At runtime
.B get
checks for Windows 10+ or Linux kernel 6.0+ and emits an advisory
warning if the requirement is not met.
.\"
.\" ====================================================================
.SH STATIC BUILDS
To produce a fully statically linked binary (requires static OpenSSL
libraries):
.PP
.RS
.B nim c \-d:release \-d:staticBuild src/get.nim
.RE
.\"
.\" ====================================================================
.SH ENVIRONMENT
.TP
.BR HTTPS_PROXY ", " HTTP_PROXY ", " ALL_PROXY
Proxy URL applied to all outbound LLM API requests.
Both upper- and lower-case forms are checked, in that order.
On Windows, if none of these variables is set,
.B get
falls back to the user's Internet Settings registry proxy
.RI ( ProxyServer ).
.TP
.B GET_TEST_KEY
API key used by the test suite for live LLM connectivity tests.
Not used during normal operation.
.TP
.B GET_TEST_URL
API endpoint URL used by the test suite.
.TP
.B GET_TEST_MODEL
Model name used by the test suite.
.\"
.\" ====================================================================
.SH FILES
.TP
.I ~/.config/get/config.json
Configuration file (Linux).
.TP
.I ~/.config/get/key
API key storage (Linux, mode 0600).
.TP
.I ~/.config/get/get.log
Append-only execution log (Linux).
.TP
.I ~/.config/get/cache.json
Response cache (Linux).
.TP
.I %APPDATA%/get/config.json
Configuration file (Windows).
.TP
.I %APPDATA%/get/key
API key storage (Windows, DPAPI-encrypted).
.TP
.I %APPDATA%/get/get.log
Append-only execution log (Windows).
.TP
.I %APPDATA%/get/cache.json
Response cache (Windows).
.TP
.IR <exe>/bin/ " or " <exe>/src/bin/
Bundled binary tools directory.
The production layout
.RI ( <exe>/bin/ )
is checked first; the development layout
.RI ( <exe>/src/bin/ )
is used as a fallback.
.\"
.\" ====================================================================
.SH EXIT STATUS
.TP
.B 0
Successful completion, or manual confirmation declined.
.TP
.B 1
Configuration error, LLM communication failure, safety-check
rejection, or general error.
.TP
.B 130
Interrupted by Ctrl+C (SIGINT).
.TP
.I N
When a generated command exits with a non-zero code, that code is
propagated as the exit code of
.BR get .
.\"
.\" ====================================================================
.SH EXAMPLES
Query the system version:
.PP
.RS
.B get \(dqsystem version\(dq
.RE
.PP
Bypass the cache for a single query:
.PP
.RS
.B get \(dqdisk usage\(dq \-\-no\-cache
.RE
.PP
Override the model and enable vivid output for one query:
.PP
.RS
.B get \(dqlist files\(dq \-\-model gpt\-5.3\-codex \-\-vivid
.RE
.PP
Force instance (single-call) mode:
.PP
.RS
.B get \(dqsystem uptime\(dq \-\-instance
.RE
.PP
Configure the API key, endpoint, and model:
.PP
.RS
.B get set key sk\-your\-api\-key
.br
.B get set url https://api.openai.com/v1
.br
.B get set model gpt\-5.3\-codex
.RE
.PP
Remove the stored API key:
.PP
.RS
.B get set key
.RE
.PP
Disable the request timeout:
.PP
.RS
.B get set timeout false
.RE
.PP
Increase the agent-mode round budget:
.PP
.RS
.B get set max\-rounds 5
.RE
.PP
Restore the built-in forbidden-command pattern:
.PP
.RS
.B get set command\-pattern
.RE
.PP
Disable forbidden-command filtering entirely:
.PP
.RS
.B get set command\-pattern \(dq\(dq
.RE
.PP
Inspect a single configuration option:
.PP
.RS
.B get config \-\-timeout
.RE
.PP
Reset all configuration to defaults:
.PP
.RS
.B get config \-\-reset
.RE
.PP
Show cache status and clear entries matching a query:
.PP
.RS
.B get cache
.br
.B get cache \-\-unset \(dqsystem version\(dq
.RE
.PP
Clear all cache and log entries:
.PP
.RS
.B get cache \-\-clean
.br
.B get log \-\-clean
.RE
.PP
Verify the configuration is ready to use:
.PP
.RS
.B get isok
.RE
.\"
.\" ====================================================================
.SH BUGS
Report bugs at
.UR https://github.com/Water\-Run/get/issues
.UE .
.\"
.\" ====================================================================
.SH AUTHOR
Written by WaterRun.
.\"
.\" ====================================================================
.SH LICENSE
.B get
is free software licensed under the GNU Affero General Public License
version 3 or later
.RB ( AGPL\-3.0\-or\-later ).
See
.UR https://www.gnu.org/licenses/agpl\-3.0.html
.UE
for the full licence text.
.\"
.\" ====================================================================
.SH SEE ALSO
.BR bash (1),
.BR powershell (1),
.BR rg (1),
.BR fd (1),
.BR bat (1),
.BR mdcat (1),
.BR tokei (1),
.BR tree (1),
.BR lua (1)