Owlibou/owlry
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
owlry/data/owlry.1
T
vikingowl 35f6501de2 docs(phase 3.10): owlry.example.lua + refresh user-facing docs 
Documentation, example config, and one validator-test fix. Version
bump and AUR push intentionally deferred.

data/owlry.example.lua (new):
- Annotated reference config exercising every surface (set / providers
  / tabs / theme / profiles / provider / util). Active section is
  minimal and validates clean.

aur/owlry/PKGBUILD:
- Ships data/owlry.example.lua to /usr/share/doc/owlry/owlry.example.lua.
  pkgver kept at 2.0.1.

README.md:
- Config table puts owlry.lua first (preferred from 2.1), config.toml
  marked legacy/fallback with precedence note linking lua-api.md §2.
- New "Quick Start (Lua config)" section with migrate-config blurb.
- migrate-config row: [--force], deterministic. config validate row:
  exit 1 errors / exit 2 warnings.
- Roadmap section flips Lua config from "lands in 2.1/3.0" to
  "shipped in 2.1"; lists 2.2 follow-ups (dynamic providers,
  owlry.bind, util.http_get).

CLAUDE.md:
- Project shape tree expands lua/ module with per-file descriptions.
- Build section documents the `lua` cargo feature.
- CLI shape line for migrate-config: [--force]. config validate:
  exit codes 1/2 mentioned.
- New "Lua config layer (2.1+)" section covers precedence, the
  notify-based watcher, desktop-notification errors, and the
  Arc<Lua> / LoadedConfig invariants.

data/owlry.1:
- --profile mentions both owlry.profiles (lua) and [profiles.<NAME>]
  (toml).
- config validate paragraph describes the categorised report and
  lists 0/1/2 exit codes.
- migrate-config description no longer says "stub" — covers
  determinism, --force/-f, pre-v2 alias normalisation, links §9.
- FILES adds ~/.config/owlry/owlry.lua and the example .lua;
  config.toml labelled legacy.

ROADMAP.md:
- "Lua-driven configuration" reworded as shipped in 2.1; example
  uses owlry.lua and the v2 API; 2.2 follow-ups listed.

cli.rs help: migrate-config stub-era text → "TOML → owlry.lua
  (--force to overwrite)".

lua/validate.rs: loosen pre_v2_aliases_are_known to assert only
that aliases aren't flagged as unknown ids. is_clean() failed
under --no-default-features --features lua because uuctl
correctly triggered the compiled-out warning (uuctl → systemd,
systemd feature off → silently dropped at runtime).

Test matrix (all green):
- --features full                          352 lib tests
- --no-default-features                    182 lib tests
- --no-default-features --features lua     305 lib tests
Clippy silent in all three configurations.

Smoke (release build, isolated XDG):
1. config validate on the shipped owlry.example.lua → OK exit 0
2. migrate-config: TOML → owlry.lua with the precedence notice
3. Daemon loads, watcher armed; appending owlry.provider triggers
   hot-reload within the debounce window
4. :phase310 prefix routes the empty query to the new provider
5. config validate against the live file still OK
2026-05-13 12:39:48 +02:00

239 lines
5.6 KiB
Groff
Raw Permalink Blame History

.TH OWLRY 1 "2026-05-13" "owlry 2.0.0" "User Commands"
.SH NAME
owlry \- Wayland application launcher with daemon and built-in providers
.SH SYNOPSIS
.B owlry
[\fIOPTIONS\fR] [\fICOMMAND\fR]
.SH DESCRIPTION
.B owlry
is a lightweight Wayland application launcher built with GTK4 and Layer Shell.
It runs as a single binary that hosts both the GTK4 UI client and the IPC
daemon, and ships every provider compiled in.
Invoked with no arguments,
.B owlry
launches the UI client in auto mode (results from all enabled providers).
Subcommands run the daemon, dmenu pipeline, diagnostics, or config tools.
.SH OPTIONS
.TP
.B \-d, \-\-daemon
Run the IPC daemon instead of the UI. Equivalent to the
.B daemon
subcommand. Conflicts with
.BR \-m ", " \-\-profile ", " \-p .
.TP
.BI \-m " MODE\fR, " \-\-mode " MODE"
Start the UI in single-provider mode. Core modes:
.BR app ", " cmd ", " dmenu ", " auto .
Built-in modes:
.BR calc ", " conv ", " power .
Optional modes (depend on cargo features at build time):
.BR bm ", " clip ", " emoji ", " ssh ", " systemd ", " uuctl ", " web ", " file .
.TP
.BI \-\-profile " NAME"
Launch the UI with a named profile. Profiles are defined under
.B owlry.profiles
in
.IR ~/.config/owlry/owlry.lua
or
.B [profiles.<NAME>]
in
.IR ~/.config/owlry/config.toml .
.TP
.BI \-p " TEXT\fR, " \-\-prompt " TEXT"
Custom prompt text for the search input. Most useful in dmenu mode.
.TP
.B \-h, \-\-help
Print help with examples.
.TP
.B \-V, \-\-version
Print the version.
.SH COMMANDS
.TP
.B daemon
Run the IPC daemon. Binds the socket and serves queries until killed.
Equivalent to
.BR "owlry \-d" .
.TP
.BR "dmenu " [\fB\-p\fR\ \fIPROMPT\fR]
Read items from standard input, present them in the launcher UI, print the
selection to standard output. Runs locally; the daemon is not required.
.TP
.B doctor
Print diagnostics: config status, daemon socket reachability, and the list of
registered providers. Non-destructive.
.TP
.BR "providers " [\fIID\fR]
List all registered providers, or print details (icon, prefix, position, tab
label, search noun) for one. Requires a running daemon.
.TP
.B "config validate"
Parse the config file and report errors and warnings. When
.I ~/.config/owlry/owlry.lua
exists it is evaluated and the snapshot is checked for unknown keys,
unknown provider ids, tabs not in
.BR owlry.providers ,
duplicate
.B owlry.provider
ids, and providers compiled out of the running build. Exit codes:
.B 0
clean,
.B 1
on errors (syntax / eval / TOML parse failure),
.B 2
on warnings only.
.TP
.B "config show"
Print the resolved effective configuration (defaults merged with the user file)
as TOML.
.TP
.BR "migrate-config " [\fB\-\-force\fR]
Migrate
.I ~/.config/owlry/config.toml
to
.I ~/.config/owlry/owlry.lua
with equivalent settings. Output is deterministic and minimal — only values
differing from the built-in defaults are emitted. Pre-v2 aliases
.RB ( system " \(-> " power ,
.B badge_sys
\(->
.BR badge_power )
are normalised to v2 names. The migrator refuses to overwrite an existing
.B owlry.lua
unless
.B \-\-force
(or
.BR \-f )
is passed. See
.IR docs/lua-api.md
\(sc9 for the full mapping.
.SH ENVIRONMENT
.TP
.B XDG_RUNTIME_DIR
Used to derive the default IPC socket path
.RI ( $XDG_RUNTIME_DIR/owlry/owlry.sock ).
.TP
.B OWLRY_SOCKET
Full path override for the IPC socket. When set, the daemon binds and the UI
client connects to this exact path, bypassing
.BR XDG_RUNTIME_DIR .
Useful for running a development daemon alongside a production instance.
.TP
.B XDG_CONFIG_HOME
Config root. Defaults to
.IR ~/.config .
.TP
.B XDG_DATA_HOME
Frecency data root. Defaults to
.IR ~/.local/share .
.TP
.B TERMINAL
Auto-detected terminal for items marked as needing a terminal. Overridden by
.B general.terminal_command
in the config.
.SH FILES
.TP
.I ~/.config/owlry/owlry.lua
Lua configuration (preferred from 2.1). Takes precedence over
.B config.toml
when both exist; an info log notes this at daemon start. The daemon
hot-reloads on save; broken edits surface as desktop notifications and
keep the previous state alive. See
.IR docs/lua-api.md
for the API.
.TP
.I ~/.config/owlry/config.toml
TOML configuration (legacy; ignored when
.B owlry.lua
exists). See
.B owlry config show
for the effective state.
.TP
.I ~/.config/owlry/themes/
User CSS themes (referenced from
.BR appearance.theme ).
.TP
.I ~/.config/owlry/style.css
CSS overrides applied last in the cascade.
.TP
.I ~/.local/share/owlry/frecency.json
Frecency state — auto-saved every 5 minutes and on SIGTERM/SIGINT.
.TP
.I $XDG_RUNTIME_DIR/owlry/owlry.sock
IPC Unix socket. See
.B OWLRY_SOCKET
to override.
.TP
.I /usr/share/doc/owlry/owlry.example.lua
Annotated example Lua configuration.
.TP
.I /usr/share/doc/owlry/config.example.toml
Annotated example TOML configuration.
.TP
.I /usr/share/owlry/themes/
Bundled themes.
.TP
.I /usr/lib/systemd/user/owlry.service
systemd user service. Enable with
.BR "systemctl \-\-user enable \-\-now owlry.service" .
.SH EXAMPLES
.PP
Launch the UI (auto mode):
.PP
.RS
.EX
owlry
.EE
.RE
.PP
Run the daemon explicitly (background):
.PP
.RS
.EX
owlry \-d &
.EE
.RE
.PP
dmenu-style script pipeline:
.PP
.RS
.EX
git branch | owlry dmenu \-p "checkout" | xargs git checkout
.EE
.RE
.PP
Diagnose an install:
.PP
.RS
.EX
owlry doctor
.EE
.RE
.PP
Run a development daemon on a separate socket:
.PP
.RS
.EX
OWLRY_SOCKET=/tmp/owlry-dev.sock owlry \-d &
OWLRY_SOCKET=/tmp/owlry-dev.sock owlry providers
.EE
.RE
.SH SEE ALSO
.BR systemctl (1),
.BR systemd.unit (5),
.BR cliphist (1),
.BR wl-copy (1),
.BR fd (1)
.PP
Project homepage:
.UR https://somegit.dev/Owlibou/owlry
.UE
.SH BUGS
Report issues at
.UR https://somegit.dev/Owlibou/owlry/issues
.UE
.SH AUTHORS
Owlibou — see
.I /usr/share/doc/owlry/README.md
for acknowledgments.
Reference in New Issue View Git Blame Copy Permalink