Files

T

Your Name 4d8f70d770 refactor: telegram config via pos config telegram; fix listener pipe + entertainment bugs

- Drop sender 'config'/'config set' subcommand — redundant with 'pos config
  telegram' (same POS_CONFIG registry: masked token input/display, chat-id
  validation, chmod 600); sender/listener error hints now point there.
- Listener: load_map now uses a \x1f delimiter, so mapped /commands
  containing '|' are no longer truncated at the first pipe.
- entertainment send: forward extra plugin args (previously dropped); pass
  '--' before the message so leading '-' plugin output isn't parsed as an
  option.
- write_config_key/cfg_write: replace unescaped sed writes with grep-v+append
  so values with &, |, \ round-trip safely.
- sync_systemd: daemon-reload after removing timer units.
- config-ui: 'digits' validation accepts negative group/supergroup chat ids.

2026-08-09 12:22:12 +00:00

3.8 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 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`

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.

3.8 KiB Raw Blame History

pos HOW-TO Guides