OmaGem

A small Ruby DSL for configuring and managing Omarchy Linux systems: themes, backgrounds, packages, services, the shell bar, plugins, toggles, snapshots, git-installed software, and system operations. It wraps the single omarchy CLI, so it stays in sync with the real command surface.

Designed to be used both in scripts and inside a Rails application.

Requirements

• Ruby 3.0+
• An Omarchy system with the omarchy CLI on your PATH

Installation

As a dependency (Bundler)

Add this line to your application's Gemfile:

gem "omagem"

Then execute:

bundle install

Or install directly from the repository:

gem "omagem", github: "azzenabidi/OmaGem", branch: "main"

Standalone (scripts and one-off use)

If you just want the DSL in a plain Ruby script or from the terminal:

gem install omagem

Verify the gem is installed and loadable:

ruby -e 'require "omagem"; puts OmaGem::VERSION'

Uninstalling

Remove from a Bundler project

bundle remove omagem

(Or delete the gem "omagem" line from your Gemfile and run bundle install.)

Uninstall the gem

gem uninstall omagem

To remove it from every RubyGems environment on the machine:

gem uninstall omagem --all

Usage

require "omagem"

OmaGem.run do
  theme "catppuccin"
  background "/home/me/Pictures/forest.png"

  add_packages "docker", "git"
  add_packages "yay-bin", aur: true

  install_service "tailscale"
  install_dev_env "ruby"
  install_browser "firefox"

  nightlight :on
  touchpad :on

  bar_set "omarchy.clock", "format", "HH:mm"
  clone_plugin "omarchy.workspaces"

  update(yes: false)
end

Every method is documented on OmaGem::Config. The block is evaluated against a fresh Config, so you can call any DSL method directly:

config = OmaGem.run do
  theme "catppuccin"
  add_packages "git"
end

config.executed            # => [["theme", "set", "catppuccin"], ["pkg", "add", "git"]]
config.client.run("theme", "current").stdout  # raw command passthrough

DSL reference

Themes & backgrounds

theme "catppuccin"              # apply a theme ("Tokyo Night" or "tokyo-night" both work)
themes                          # list available themes
install_theme "https://...git"  # install from a git repo
remove_theme "my-theme"         # remove a user-installed theme
refresh_theme                   # re-apply current theme from templates
update_themes                   # update installed git themes

background "/path/to/image.png" # set the desktop background
background_next                 # cycle to next background
background_switcher             # open the background switcher

Packages

add_packages "docker", "git"      # install Arch packages if missing
add_packages "yay-bin", aur: true # install from the AUR
drop_packages "vim"               # remove packages if installed

package_present?("docker")          # true unless ALL listed are installed
package_installed?("docker", "git") # true when ALL listed are installed

Services, apps, tools

install_service "tailscale"     # 1password, dropbox, nordvpn, once, signal, spotify, sunshine, tailscale
remove_service "tailscale"

install_browser "firefox"       # chrome, brave, brave-origin, edge, firefox, zen
install_editor "helix"          # emacs, helix, vscode, zed
install_terminal "kitty"        # alacritty, foot, ghostty, kitty
install_dev_env "ruby"          # ruby, node, bun, deno, go, laravel, symfony, php, python, elixir, phoenix, rust, java, zig, ocaml, dotnet, clojure, scala
install_game "steam"            # steam, heroic, lutris, retroarch, battlenet, geforce-now, xbox-cloud, xbox-controllers, gpu-lib32
install_app "ChatGPT", "openai-chatgpt"

System

update(yes: true)        # full system + Omarchy update (-y skips prompts)
version                  # installed version
lock                     # lock screen
reboot / shutdown / logout

channel "stable"         # stable, rc, edge, dev
default_terminal "kitty" # alacritty, foot, ghostty, kitty
default_browser "zen"    # chromium, chrome, brave, brave-origin, edge, firefox, zen
default_editor "nvim"    # code, cursor, zed, sublime_text, helix, vim, emacs, nvim

font "JetBrainsMono Nerd Font"
current_font

create_snapshot / restore_snapshot
debug

Bar, plugins, toggles

bar "local.neon-bar"              # switch bar layout
bar_position "top"                # top, bottom, left, right
bar_transparent true              # true, false, :toggle
bar_set "omarchy.clock", "format", "HH:mm"
bar_move "omarchy.clock", ["--section", "center", "--index", "0"]

add_plugin "https://...git", enable: true
clone_plugin "omarchy.workspaces"
enable_plugin "omarchy.clock"
disable_plugin "omarchy.clock"
remove_plugin "omarchy.clock"
list_plugins(json: false)

nightlight :on               # :on, :off, :toggle
touchpad :off
touchscreen :on
idle :toggle
bar_visible :toggle
notification_silencing       # do-not-disturb

Git-installed software

valid_git_url? "https://...git" # true when git can clone the URL
git_themes                      # names of user themes cloned from git
git_plugins                     # IDs of third-party plugins added from git

update_git_installs             # pull every git theme + plugin (yes: true skips prompts)
update_git_installs(yes: false) # keep the plugin update confirmation prompt

Everything installed through the DSL from a git URL — install_theme, add_plugin — is already captured in config.executed. The Git methods above track what is currently git-managed and keep it up to date.

Misc

screenshot
screenrecord(fullscreen: true, desktop_audio: true, webcam: false)
stop_screenrecord
reminder 15, "Pick up Jack"
focus_app "org.mozilla.firefox"

From a Rails app

Because OmaGem.run returns the Config (and records every executed command), you can invoke it from a controller, job, or service and inspect the results:

result = OmaGem.run { theme params[:theme] }
flash[:notice] = result.current_theme

Reusable, non-destructive configuration

Pass a fake (recording) client to build a config without touching the system:

config = OmaGem::Config.new(client: OmaGem::Client::Fake.new)
config.theme "catppuccin"
config.executed # => [["theme", "set", "catppuccin"]]

Use cases

1. Machine bootstrap / dotfiles as code

Declare the desired state of a fresh Omarchy install in a single script you can re-run on any machine:

OmaGem.run do
  theme "catppuccin"
  add_packages "docker", "git", "lazygit"
  add_packages "yay-bin", aur: true
  install_service "tailscale"
  default_terminal "kitty"
  update(yes: true)
end

2. Rails admin panel

Expose theme, package, and service management through a web UI. Because OmaGem.run returns the Config, controllers apply an operation and immediately inspect the result:

class ThemesController < ApplicationController
  def update
    result = OmaGem.run { theme params[:theme] }
    render json: { current: result.current_theme }
  end
end

3. Scheduled automation

Drive background jobs — switches your environment on a schedule or keeps the system up to date without touching the terminal:

class NightlightJob < ApplicationJob
  def perform(on:)
    OmaGem.run { nightlight(on ? :on : :off) }
  end
end

4. Dry-run / preview

Preview exactly which commands a config would run, without mutating the system, using the recording fake client (see Reusable, non-destructive configuration):

config = OmaGem::Config.new(client: OmaGem::Client::Fake.new)
config.theme "tokyo-night"
config.add_packages "docker"
config.executed
# => [["theme", "set", "tokyo-night"], ["pkg", "add", "docker"]]

5. Remote management

Ship an apply script to an Omarchy box and run it over SSH:

scp apply.rb omarchy-box:
ssh omarchy-box "ruby apply.rb"

Errors

• OmaGem::CommandFailed — a command exited non-zero (set ignore_errors: true in OmaGem.run to raise nothing and keep going).
• OmaGem::CommandNotFound — the omarchy binary isn't on PATH (ensure_command!).
• OmaGem::ArgumentError — an invalid enum value (e.g. an unknown terminal).

Development

bundle install
bundle exec rake test
bundle exec rubocop

License

MIT