the vinos-* reference

One command per job. Composable. Boring.

vinOS ships ~90 vinos-* bins in /usr/local/bin. Each is a plain script — bash or python, no daemons, no magic. Pipe them, hook them, read them, replace them. Nothing on this page is undocumented; each script's top comment is the source of truth.

Founder utilities

The four you'll use daily. Wired into the default keybindings and the routines that ship in the ISO.

vinos-standup Plain-English daily standup from your git activity. vinos-standup --yesterday · vinos-standup --week
vinos-commit AI-drafted commit message from your staged diff. Edit / Accept / Retry / Quit. vinos-commit -y to skip the prompt.
vinos-focus [minutes] Enter DND mode for N minutes — notifications muted, mako paused, waybar shows a timer. Default 25.
vinos-brief [routine] Show today's routine outputs. No arg dumps everything; an argument shows only that routine's latest.

Agent shortcuts

Interactive AI helpers. Pipe stdin in, get plain-English answers back. Route to local or Claude per ~/.config/vinos/ai.toml.

vinos-ai [chat|code|prompt] Stable CLI over ollama, claude-code, and aichat — one command instead of three tools to remember.
vinos-fix Pipe an error → AI diagnostic + fix suggestion. some-command 2>&1 | vinos-fix
vinos-explain Pipe anything → plain-English explanation. cat script.sh | vinos-explain

Routines

The scheduled-agent runtime. Full walkthrough on the routines page.

vinos-routine list All routines + next-run + last status
vinos-routine enable <name> Activate the systemd user timer for a routine
vinos-routine run <name> Ad-hoc run of a routine, streaming to stdout
vinos-routine cost --today Ledger summary — tokens, dollars, top spenders
vinos-routine load <path> Install every routine from a repo's .vinos/routines.yaml
vinos-brief Open today's routine outputs in a walker panel

System

Health checks, first-boot flow, menus, hooks.

vinos-doctor Health check. Prints PASS/FAIL per check; non-zero exit if anything fails. Super+Ctrl+S.
vinos-first-run Finish the install with items that can only run after your first login (services, keys, tuning).
vinos-menu Walker/dmenu-style hub for user actions — installs, wifi, updates, themes. Super+Ctrl+O.
vinos-cheatsheet Pretty-print the shipped Hyprland keybindings. Parses ~/.config/hypr/hyprland.conf live. Super+K.
vinos-hook [name] [args...] Run a named hook from ~/.config/vinos/hooks/<name> and the .d/ directory.
vinos-hook-install <type> <path> Install a hook into ~/.config/vinos/hooks/<type>.d/
vinos-sudo-keepalive Prompt for sudo once; keep the credential alive in the background for long-running installers.
vinos-notification-send <glyph> <headline> [body] Send a desktop notification with a vinOS glyph and correct body spacing.
vinos-reminder <min> [msg] | show | clear Set and show lightweight desktop notification reminders.
vinos-restart-waybar Restart Waybar cleanly after a config edit.

Hardware helpers

Small, composable primitives waybar and hyprland call. All safe to script against; each prints one line.

Battery + power

vinos-battery-statusFormatted battery status: percentage + power draw/charge.
vinos-battery-capacityBattery full capacity in Wh, rounded.
vinos-battery-presentTrue if a battery is present on the system.
vinos-battery-remaining-timeBattery time-to-empty (or full) in a compact format.
vinos-ac-presentTrue if AC power is connected.
vinos-powerprofiles-initSet the correct power profile on boot based on current AC/battery state.
vinos-powerprofiles-set <level>Set the power profile, falling back to balanced.

Brightness + audio

vinos-brightness-display <+N%|N%-|N%|off|on>Adjust brightness on the most-likely display device.
vinos-brightness-display-appleAdjust brightness on Apple Studio + XDR Displays via asdcontrol.
vinos-brightness-keyboardAdjust keyboard backlight through available steps.
vinos-brightness-keyboard-muteSet the mic-mute indicator LED on laptops that expose platform::micmute.
vinos-audio-input-muteToggle microphone mute. Drives the hardware mic-mute LED where available.
vinos-audio-output-switchSwitch between audio outputs while preserving mute status.
vinos-swayosd-brightnessShow display brightness via SwayOSD on the current monitor.
vinos-swayosd-kbd-brightnessShow keyboard brightness via SwayOSD on the current monitor.
vinos-swayosd-clientWrapper for swayosd-client that targets the focused monitor.

Reporting

vinos-hw-reportMarkdown hardware report suitable for a GitHub issue or a HARDWARE.md row.
vinos-hw-hintsDetect hardware quirks and post one-shot notifications.
vinos-hw-touchpadPrint the detected Hyprland touchpad or trackpad device name.
vinos-hw-external-monitorsTrue when an external monitor is physically connected.
vinos-cmd-present <cmd>…Check whether all required commands are available.
vinos-cmd-terminal-cwdPrint the current working directory of the active terminal window.

Launch helpers

Small floating-window launchers for TUIs and pickers. Every one respects your theme and terminal choice.

vinos-launch-wifiOpen the impala Wi-Fi TUI in a floating foot window. Super+Ctrl+W.
vinos-launch-bluetoothOpen the bluetui pairing TUI in a floating window. Super+Ctrl+B.
vinos-launch-audioOpen a floating audio mixer (wiremix). Super+Ctrl+U.
vinos-launch-browserLaunch the default browser as determined by xdg-settings.
vinos-launch-editor <path>Launch the default editor from $EDITOR (falls back to nvim).
vinos-launch-tui <cmd>Launch a TUI command in the default terminal with vinOS styling.
vinos-launch-walkerLaunch Walker and ensure its Elephant data provider is running.
vinos-launch-webapp <url>Launch a URL as a web app in the default supported browser.

Hyprland integration

Monitor + window helpers wired into the shipped Hyprland config.

vinos-hyprland-toggleToggle permanent Hyprland flags by copying them into a directory sourced entirely.
vinos-hyprland-toggle-enabled / -disabledCompanion helpers for the toggle pipeline.
vinos-hyprland-monitor-focusedPrint the currently focused monitor name.
vinos-hyprland-monitor-focused-appleApple-Display-aware variant of the above.
vinos-hyprland-monitor-internalPrint the internal display name.
vinos-hyprland-monitor-internal-mirrorMirror the internal display to any external.
vinos-hyprland-monitor-scaling-cycleCycle scaling factors (1.0 / 1.25 / 1.5 / 2.0) on the focused monitor.
vinos-hyprland-monitor-watchReact to monitor hotplug events (used by the systemd hook).
vinos-hyprland-window-close-allClose every window on the current workspace.
vinos-hyprland-window-gaps-toggleToggle gaps on/off for zen-mode work.
vinos-hyprland-window-popPop the focused window into a temporary floating overlay.
vinos-hyprland-window-single-square-aspect-toggleToggle single-square aspect for the focused window (useful for pinned utilities).
vinos-hyprland-window-transparency-toggleToggle transparency on the focused window.
vinos-hyprland-workspace-layout-toggleCycle workspace layouts (dwindle ↔ master).

Screen capture

Screenshots + OCR. All output routes to the clipboard by default; keep them piped-composable.

vinos-capture-screenshotTake a screenshot (region → annotate → clipboard). Super+P.
vinos-capture-text-extractionOCR the selected region and copy plain text to the clipboard.

Install bundles

Opt-in package sets. Each bundle is idempotent — safe to re-run. Full list: the bundles page.

vinos-install-aiOllama, llama.cpp, huggingface-cli, python-{openai,anthropic,torch}, aichat, open-webui, CUDA (on NVIDIA).
vinos-install-browserChromium (base) plus firefox/brave alternatives.
vinos-install-commsChat, video, and file-share apps (Signal, Slack, Zoom, Discord).
vinos-install-devServer + devops + language runtimes (postgres, docker, jdk, rust, go, mise).
vinos-install-diskOne-command installer from the live ISO to a disk. Wraps archinstall with a hardware-aware preset.
vinos-install-gamingSteam, Lutris, gamemode, mangohud, protontricks.
vinos-install-mediampv, kdenlive, obs-studio, imv, pinta, gpu-screen-recorder, spotify.
vinos-install-officeLibreOffice + Thunderbird.
vinos-install-productivityNotes + writing tools (obsidian, notion, typora, 1password).
vinos-install-onceFirst-boot wrapper — launches vinos-welcome from a Hyprland exec-once.
vinos-install-commonShared helpers sourced by every vinos-install-* bundle. Not run directly.

Missing something? Every script lives at bin/ in the repo — the top comment of each file is authoritative. If a description here drifts from the script, file an issue and we'll fix the page.