Skip to content

README.md

Latest commit

 

History

History
163 lines (126 loc) · 6 KB

README.md

File metadata and controls

163 lines (126 loc) · 6 KB
Raw

◆ opt

opt — the Option family CLI.

It is a thin dispatcher in the spirit of git / cargo: opt <app> [args...] forwards to the matching app binary and mirrors its exit status. It also offers family-level tools: gui, status, doctor, install, sys and version.

◆ opt — the Option family

  files     ◆   terminal file manager
  music     ♪   CLI music player
  cal       ◷   minimal local calendar
  terminal  ◇   GTK4 terminal with tiling splits
  opsh      ❯   small local shell
  search    ⌕   instant local file search

Marks come from optionSDK — it owns the family glyphs, and a test keeps opt from drifting from it.

Install

Requires Rust 1.85+.

cargo install optioncli        # binary: `opt`

Or from the checkout:

cargo run --release -- status

Usage

opt                        # list the family
opt files                  # run optionFiles interactively
opt gui files              # open the desktop file manager
opt music play song.mp3 -v 80
opt status                 # installed apps + versions
opt doctor                 # check each app's system dependencies
opt install                # install the whole family
opt install music          # install one app
opt update                 # update the whole family
opt sys clean              # remove each app's ~/.option/<id>/cache
opt sys info               # OS, arch, home and option root
opt sys path               # list PATH
opt version                # opt's own version

After the app id, every argument is forwarded untouched, so flags and spaces reach the underlying binary as written:

opt files list "/tmp/com espaço"
opt music dl https://youtu.be/… --audio

opt gui <app> [args...] runs the app's desktop front-end instead of its CLI (gui is a reserved verb, like status): files → optionfiles-gtk, fls-gtk; music → optionmusic-gpui; search → optionsearch-gtk, needle. opt gui terminal runs optionterm itself, since it is already a desktop app. Bare opt gui lists every app with a desktop surface (including terminal) and its installed state; OPTION_GUI_BIN_<ID> overrides the lookup.

Front-ends ship in their own packages, so a missing one is reported with the package that provides it:

App GUI cargo package GUI on the AUR
files optionfiles-gui — (the optionfiles package installs only the CLI)
music optionmusic-gpui — (the optionmusic package installs only the CLI)
search optionsearch-gui optionsearch (ships optionsearch-gtk)

Aliases

f → files, file → files, m → music, c → cal, s → search, needle → search, nld → search.

Environment

Variable Meaning
OPTION_BIN_<ID> Force an app's binary path (e.g. OPTION_BIN_MUSIC); surrounding spaces are trimmed, a blank value is ignored
OPTION_GUI_BIN_<ID> Force an app's GUI binary path (e.g. OPTION_GUI_BIN_FILES)
OPTION_PKG install/update manager: cargo (default) | yay | paru | pacman (aur = paru if present, else yay)
NO_COLOR Disable color in output (per no-color.org)

Routing & packages

App Binary candidates GUI (opt gui) cargo AUR
files optionfiles, fls optionfiles-gtk, fls-gtk optionfiles optionfiles
music optionmusic, msc optionmusic-gpui optionmusic optionmusic
cal optioncalendar, oca — optioncalendar optioncalendar
terminal optionterm — optionterm optionterm
opsh opsh — opsh opsh
search optionsearch, nld, needle optionsearch-gtk, needle optionsearch-cli optionsearch

The first candidate on PATH wins; OPTION_BIN_<ID> overrides it. The same table is printed by opt (menu) and opt help. needle/nld stay as compat aliases of the needle → optionSearch rename (opt needle resolves to search).

install / update

opt install            # whole family (cargo install <each>)
opt install music      # one app
opt update             # cargo install --force <each> | yay -Syu <family pkgs>
opt update music       # update one app

With OPTION_PKG=yay|paru, install runs <helper> -S --noconfirm <aur> and update runs <helper> -Syu --noconfirm <aur...> (a real refresh upgrade, not a reinstall). OPTION_PKG=pacman uses sudo pacman -S/-Syu.

doctor

For each app, opt doctor reports whether its binary is installed and checks the system dependencies it needs. Each dep is tagged [req] (required) or [opc] (optional):

  • files: xdg-open (req), $EDITOR — $EDITOR/$VISUAL (a bare name is resolved on PATH, a path is checked in place; either way it has to be executable) or a vi/nano fallback (req), imagemagick (magick or convert), clipboard (wl-copy/xclip/xsel/pbcopy), gio/trash (all optional).
  • music: mpv binary + libmpv (ldconfig -p, pkg-config --exists mpv or the mpv binary; both req), cava, yt-dlp, ffmpeg (optional).
  • terminal: gtk4, libadwaita, vte-2.91-gtk4 via pkg-config --exists with a pacman -Q fallback (req), plus optional pkg-config probe note.
  • search: pdftotext (optional; sqlite is embedded, no check needed).
  • cal, opsh: no extra system deps.

Missing required deps show as faltando (req), missing optional ones as ausente (opc), each with a pacman hint plus the apt/dnf equivalents. The report is visual only — it never changes the exit status.

Local-first

opt reads ~/.option only for identity (marks, bundle ids via optionSDK); it never creates files or services beyond cache cleanup. It is deliberately small and local — no daemon, account, telemetry or cloud.

Development

cargo fmt --check
cargo test
cargo build --release

License

Apache License 2.0 — see LICENSE.