Files

T

Your Name 23eede637a feat: pos ai gemini — CLI + Telegram AI chat (ask, chat, models)

- bin/pos-ai-gemini: one-shot ask (stdout-only, pipe-friendly), interactive
  multi-turn chat REPL (q/Ctrl+C, /reset), models list; --model override,
  default gemini-2.5-flash; key via x-goog-api-key header, never printed.
- Config scope 'ai' (AI_GEMINI_API_KEY secret, AI_GEMINI_MODEL) in
  ~/.config/linux_post_install/ai.env via 'pos config ai'; config/ai.env
  template installed no-clobber by postinstall.
- Telegram listener: non-command text starting with 'ai ' (case-insensitive)
  is answered by Gemini via 'pos ai gemini ask'; owner-chat only, errors
  reply with the pos config ai hint. Future intents slot in as case arms.
- ai-gemini added to INTERACTIVE_CMDS (chat reads stdin).
- Docs: POS.md ai section + listener bridge, howto/ai.md, HOWTO/README
  index rows, bin/pos usage example; make gen refreshed context/completions.

2026-08-09 14:40:15 +00:00

4.0 KiB

Raw Blame History

`pos` HOW-TO Guides

Hands-on, copy-paste guides for every pos category. These are the tutorial layer: flags, examples, configuration, recipes, and troubleshooting. For the authoritative one-line reference (every command + flag), see DOC/POS.md.

Quick start — pick your category

Category	What you can do	Guide
`pos ai`	Chat with Google Gemini from CLI or Telegram	ai
`pos network`	IP info, hotspot, scan, port check	network
`pos docker`	Compose services, container dashboards, disposable VMs	docker
`pos media`	Download audio/video via yt-dlp	media
`pos system`	Backups, firewall, health dashboard	system
`pos ssh`	Load keys into the agent	ssh
`pos usb`	Share USB devices over the network	usb
`pos communication`	Send Telegram messages/files/alerts	communication
`pos entertainment`	Scheduled auto-messages from public APIs	entertainment

Every tool is bin/pos-<category>-<command>; run pos <category> --help to list a category, and any tool's --help/--help-style usage for full flags.

Cross-cutting concepts (read once)

These apply to several categories at once.

Config files — `~/.config/linux_post_install/`

Runtime tool config lives here as <tool>.env files (chmod 600). Precedence is always flags > environment > config file. postinstall.sh installs the templates (without overwriting an existing file):

File	Used by	Keys
`telegram.env`	`pos communication telegram sender` / `listener`, everything that alerts	`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`
`notify.env`	`lib/notify.sh` (all alerting)	`NOTIFY_PLATFORM` (e.g. `telegram,matrix`)
`system.env`	`pos system health`, `pos system backup`	`BACKUP_SERVICE_ROOTS`, `HEALTH_BACKUP_MAX_AGE_DAYS`
`compose.env`	`pos docker compose`	`TS_AUTHKEY`, `TZ`, `DNS_SERVER`, `SERVICES_BASE`
`entertainment.env`	`pos entertainment *`	plugin keys (`WEATHER_LAT`…), `ENABLED`
`ai.env`	`pos ai gemini`	`AI_GEMINI_API_KEY`, `AI_GEMINI_MODEL`

pos config telegram                     # set TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID
pos entertainment config set WEATHER_LAT=36.51 WEATHER_LON=40.75

The notify system — `lib/notify.sh`

Any tool that "announces" something calls notify_send, which delivers to every platform in NOTIFY_PLATFORM (default telegram). It is silent-fail: if no platform is configured it warns and never breaks the calling tool.

# ~/.config/linux_post_install/notify.env
NOTIFY_PLATFORM=telegram        # comma-separated to send to all

Adding a platform later (e.g. Matrix/Synapse) = create bin/pos-communication-<p> implementing send <value> [--markdown] and list it. See DOC/DEV.md → Alerting for the contract.

Scheduling

Daily health digest (pos system health --send at 08:00) — systemd/pos-health.{service,timer}, enabled by postinstall once telegram.env exists. See system.
Entertainment auto-triggers — per-plugin pos entertainment enable <plugin> <interval>, uses systemd user timers (or cron fallback). See entertainment.

Gotcha: run from anywhere

install.sh copies bin/pos* + lib/* to /usr/local/bin, so pos works after the repo is deleted. After pulling new changes, re-run ./install.sh (or just copy the changed bin//lib/ files) to refresh the installed copies.

How the guides relate to `DOC/POS.md`

DOC/POS.md = reference. One table row per command, full flag lists, compose/ScaleTail config strategy. Use it when you need the exact flag.
This guide set = how-to. Examples, recipes, config walk-throughs, and troubleshooting, linking back to POS.md rather than duplicating it.

4.0 KiB Raw Blame History

pos HOW-TO Guides