go-lcg/docs/README.md

Linux Command GPT (lcg)

This repo is forked from https://github.com/asrul10/linux-command-gpt.git

Generate Linux commands from natural language. Supports Ollama and Proxy backends, system prompts, different explanation levels (v/vv/vvv), and JSON history.

Installation

Build from source:

git clone --depth 1 https://github.com/Direct-Dev-Ru/linux-command-gpt.git ~/.linux-command-gpt
cd ~/.linux-command-gpt
go build -o lcg

# Add to your PATH
ln -s ~/.linux-command-gpt/lcg ~/.local/bin

Quick start

lcg "I want to extract linux-command-gpt.tar.gz file"

After generation you will see a CAPS warning that the answer is from AI and must be verified, the command, and the action menu:

ACTIONS: (c)opy, (s)ave, (r)egenerate, (e)xecute, (v|vv|vvv)explain, (n)othing

Explanations:

• v — short; vv — medium; vvv — detailed with alternatives.

Clipboard support requires xclip or xsel.

Write the generated script to a file instead of stdout:

lcg --mode file "I want to extract linux-command-gpt.tar.gz file"
# 💾 Файл создан: lcg-out-script.sh

lcg --mode file --output-file ~/bin/unpack.sh "I want to extract linux-command-gpt.tar.gz file"

The file is rewritten on each request: only the code produced for the current query remains, earlier content is removed. Before rewriting an existing file backup copies are created: <file>.bak is the latest one, <file>.bak.1, <file>.bak.2, … are older; the number of kept copies is set by LCG_BACKUP_COUNT (default 3) or --backup-count, 0 disables backups. If the file already exists and is not empty, its content is passed to the model as data (see LCG_CONTEXT_MAX_BYTES): inline when it fits the user message limit, otherwise as a separate message before the query.

The model is asked to return code in markdown fences (```bash, ```python, …): only fenced blocks are written to the file as code, the rest of the answer becomes comments in the syntax of the target file (#, //, --, <!-- -->, … by extension). Shebang and set -euo pipefail are added only for shell scripts; a shebang already present in the model's code is reused, and set -euo pipefail is not duplicated.

What's new in 2.0.14

• Authentication: JWT-based authentication with HTTP-only cookies
• CSRF protection: Full CSRF protection with tokens and middleware
• Security: Enhanced security with token validation and sessions
• Kubernetes deployment: Full set of manifests for Kubernetes deployment with Traefik
• Reverse Proxy: Support for working behind reverse proxy with cookie configuration
• Web interface: Improved web interface with modern design
• Monitoring: Prometheus metrics and ServiceMonitor
• Scaling: HPA for automatic scaling
• Testing: CSRF protection testing tools

Environment

• LCG_PROVIDER (default ollama) — provider type: ollama, proxy or apimira
• LCG_HOST (default http://192.168.87.108:11434/, for apimira: https://apimira.com) — base API URL
• LCG_MODEL (default hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M; for apimira required in vendor/model form, e.g. anthropic/claude-opus-4.7)
• LCG_PROMPT — default system prompt content
• LCG_PROXY_URL (default /api/v1/protected/sberchat/chat) — proxy chat endpoint
• LCG_COMPLETIONS_PATH (default api/chat, for apimira: /v1/chat/completions) — chat endpoint (relative)
• LCG_TIMEOUT (default 300) — request timeout in seconds
• LCG_RETRIES (default 3) — retry attempts on transient errors (network, 429, 5xx) with delays 5s/10s/20s; 0 disables retries; CLI flag --retries overrides it
• LCG_MODE (default stdout) — output mode: stdout or file; CLI flag --mode overrides it
• LCG_OUTPUT_FILE (default ./lcg-out-script.sh) — output file for --mode file; CLI flag --output-file overrides it
• LCG_CONTEXT_MAX_BYTES (default 16000) — limit of output file bytes passed to the model as context in --mode file
• LCG_BACKUP_COUNT (default 3) — number of backup copies (<file>.bak, <file>.bak.1, …) kept for --mode file; 0 disables them
• LCG_RESULT_FOLDER (default ~/.config/lcg/gpt_results) — folder for saved results
• LCG_RESULT_HISTORY (default $(LCG_RESULT_FOLDER)/lcg_history.json) — JSON history path
• LCG_PROMPT_FOLDER (default ~/.config/lcg/gpt_sys_prompts) — folder for system prompts
• LCG_PROMPT_ID (default 1) — default system prompt ID
• LCG_BROWSER_PATH — custom browser executable path for --browser flag
• LCG_DEBUG_FILE / --debug-file — append full activity log (queries, prompts, request and response bodies) to the given file
• LCG_JWT_TOKEN — API key for proxy and apimira providers
• LCG_API_KEY_FILE (default .openai_api_key, for apimira: .apimira_api_key) — API key file in $HOME, stored with 0600 permissions
• LCG_NO_HISTORY — if 1/true, disables history writes for the process
• LCG_ALLOW_EXECUTION — if 1/true, enables command execution via (e) action menu
• LCG_SERVER_PORT (default 8080), LCG_SERVER_HOST (default localhost) — HTTP server settings

Flags

• --file, -f read part of prompt from file
• --sys, -s system prompt content or ID
• --prompt-id, --pid choose built-in prompt (1–5)
• --timeout, -t request timeout (sec)
• --no-history, --nh disable writing/updating JSON history for this run
• --mode output mode: stdout (default) or file
• --output-file, -o output file for --mode file (default ./lcg-out-script.sh)
• --backup-count number of backup copies kept for --mode file (overrides LCG_BACKUP_COUNT, default 3)
• --debug, -d show debug information (request parameters and prompts)
• --version, -v print version; --help, -h help

Commands

• models, health, config
• prompts list|add|delete
• test-prompt <prompt-id> <command>
• update-jwt, delete-jwt (proxy)
• update-key, delete-key (not needed for ollama/proxy)
• history list — list history from JSON
• history view <index> — view by index
• history delete <index> — delete by index (re-numbering)
• serve — start HTTP server to browse saved results (--port, --host, --browser)
• /run — web interface for executing requests
• /execute — API endpoint for programmatic access via curl

Saving results

Files are saved to LCG_RESULT_FOLDER (default ~/.config/lcg/gpt_results).

• Command result: gpt_request_<MODEL>_YYYY-MM-DD_HH-MM-SS.md

  • # <title> — H1 with original request (trimmed to 120 chars: first 116 + ...)
  • ## Prompt
  • ## Response

• Detailed explanation: gpt_explanation_<MODEL>_YYYY-MM-DD_HH-MM-SS.md

  • # <title>
  • ## Prompt
  • ## Command
  • ## Explanation and Alternatives (model: <MODEL>)

History

• Stored as JSON array in LCG_RESULT_HISTORY.
• On new request, if the same command exists, you will be prompted to view or overwrite.
• Showing from history does not call the API; the standard action menu is shown.

Browser Integration

The serve command supports automatic browser opening:

# Start server and open browser automatically
lcg serve --browser

# Use custom browser
export LCG_BROWSER_PATH="/usr/bin/firefox"
lcg serve --browser

# Start on custom host/port with browser
lcg serve --host 0.0.0.0 --port 9000 --browser

Supported browsers (in priority order):

• Yandex Browser (yandex-browser, yandex-browser-stable)
• Mozilla Firefox (firefox, firefox-esr)
• Google Chrome (google-chrome, google-chrome-stable)
• Chromium (chromium, chromium-browser)

API Access

The serve command provides both a web interface and REST API:

Web Interface:

• Browse results at http://localhost:8080/ (or http://localhost:8080<BASE_PATH>/ if LCG_BASE_URL set)
• Execute requests at .../run
• Manage prompts at .../prompts
• View history at .../history

Notes:

• Base path: set LCG_BASE_URL (e.g. /lcg) to prefix all routes and API.
• Custom 404: unknown paths under base path render a modern 404 page.
• Debug: enable via flag --debug or env LCG_DEBUG=1|true.

REST API:

# Start server
lcg serve

# Make API request
curl -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{"prompt": "create directory test", "verbose": "vv"}'

Response:

{
  "success": true,
  "command": "mkdir test",
  "explanation": "The mkdir command creates a new directory...",
  "model": "hf.co/yandex/YandexGPT-5-Lite-8B-instruct-GGUF:Q4_K_M",
  "elapsed": 1.23
}

For complete API documentation, see API_GUIDE.md.

For full guide in Russian, see USAGE_GUIDE.md.