{"id":21981648,"url":"https://github.com/soft/run-or-raise","last_synced_at":"2025-08-21T22:31:12.949Z","repository":{"id":47235973,"uuid":"82081559","full_name":"Soft/run-or-raise","owner":"Soft","description":"Utility for launching applications or focusing their windows","archived":false,"fork":false,"pushed_at":"2022-11-11T19:46:41.000Z","size":73,"stargazers_count":69,"open_issues_count":2,"forks_count":5,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-12-13T04:26:09.347Z","etag":null,"topics":["application-launcher","rust","shortcut","shortcuts","utility","window-management","work-flow","x11","xbindkeys"],"latest_commit_sha":null,"homepage":"https://soft.github.io/run-or-raise/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Soft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-02-15T16:30:48.000Z","updated_at":"2024-11-09T11:23:02.000Z","dependencies_parsed_at":"2022-09-01T03:00:14.839Z","dependency_job_id":null,"html_url":"https://github.com/Soft/run-or-raise","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soft%2Frun-or-raise","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soft%2Frun-or-raise/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soft%2Frun-or-raise/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soft%2Frun-or-raise/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Soft","download_url":"https://codeload.github.com/Soft/run-or-raise/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230537062,"owners_count":18241515,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["application-launcher","rust","shortcut","shortcuts","utility","window-management","work-flow","x11","xbindkeys"],"created_at":"2024-11-29T17:18:54.796Z","updated_at":"2024-12-20T05:08:41.260Z","avatar_url":"https://github.com/Soft.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# run-or-raise 🏃‍\n\n[![Build Status](https://travis-ci.org/Soft/run-or-raise.svg?branch=master)](https://travis-ci.org/Soft/run-or-raise)\n[![Latest Version](https://img.shields.io/crates/v/run-or-raise.svg)](https://crates.io/crates/run-or-raise)\n[![GitHub release](https://img.shields.io/github/release/Soft/run-or-raise.svg)](https://github.com/Soft/run-or-raise/releases)\n[![dependency status](https://deps.rs/repo/github/soft/run-or-raise/status.svg)](https://deps.rs/repo/github/soft/run-or-raise)\n[![AUR version](https://img.shields.io/aur/version/run-or-raise.svg)](https://aur.archlinux.org/packages/run-or-raise/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n\n`run-or-raise` is a utility for launching applications or focusing their windows\nif they are already running. When invoked, `run-or-raise` tries to find a window\nthat matches a specified criteria and focus it or, if no matching window is\nfound, execute a specified program.\n\nThis can be useful when combined with a tiling window manager such as\n[i3](https://i3wm.org) or a general purpose keyboard shortcut manager such as\n[xbindkeys](http://www.nongnu.org/xbindkeys/) that allow binding arbitrary\ncommands to keybindings. In such setup, one might use `run-or-raise` to, for\nexample, launch or focus a web browser with a single key press.\n\n`run-or-raise` is designed to work with X11 based Linux systems.\n\n## Installation\n\n`run-or-raise` can be installed using\n[cargo](https://doc.rust-lang.org/cargo/index.html):\n\n``` shell\ncargo install run-or-raise\n```\n\nCompiling and running `run-or-raise` requires [libxcb](https://xcb.freedesktop.org)\nlibrary to be installed.\n\nTo get the latest development version of `run-or-raise`, you can direct cargo to\ninstall from the git repository:\n\n``` shell\ncargo install --git 'https://github.com/Soft/run-or-raise.git'\n```\n\nNote that cargo will not install man pages. To install `run-or-raise` along with\nits manual invoke `make install` in the project directory. By default, the\ninstallation script will place the files under `/usr/local/` hierarchy.\n\n## Usage\n\n``` text\nrun-or-raise CONDITION PROGRAM [ARGS...]\n```\n\nWhen invoked, `run-or-raise` matches existing windows against `CONDITION`. If a\nmatching window is found, it is focused. If none of the windows match the\ncriteria, `run-or-raise` executes `PROGRAM` passing any `ARGS` to it as\narguments.\n\n## Conditions\n\nConditions select windows based on their properties. In X11, each window can\nhave any number of properties associated with them. Examples of window\nproperties include *name* (typically what is visible in window's title bar),\n*class* (an identifier that can be usually used to select windows of a\nparticular applications) and *role* (a representation of window's logical role,\neg. a web browser). The [xprop](https://www.x.org/releases/X11R7.5/doc/man/man1/xprop.1.html)\nutility can be used to inspect windows and their properties.\n\nThe simplest possible window matching condition simply compares one of the\nproperties with a value:\n\n``` shell\nrun-or-raise 'name = \"Spotify\"' spotify\n```\n\nThis would find and focus a window with the title “Spotify” or run the command\n`spotify`.\n\nConditions support two comparison operators: `=` for exact equality comparison\nwith a string literal and `~` for comparing using a [regular\nexpression](https://en.wikipedia.org/wiki/Regular_expression).\n\nComparisons can be combined using logical operators: `\u0026\u0026` for logical *AND*,\n`||` for logical *OR*, and `!` for logical *NOT*. Operators in matching\nexpressions are left-associative and `!` (not) binds stronger than `\u0026\u0026` (and)\nwhich, in turn, binds stronger than `||` (or). Possible properties are `class`,\n`name`, and `role`. Additionally, parentheses can be used to alter evaluation\norder. Strings and regular expressions are written inside double quotes. If\nmultiple windows match the criteria, the first matching window is selected.\n\nBellow are some examples of how conditions can be used to select windows in\nvarious ways:\n\n``` shell\n# Launch or focus emacs\nrun-or-raise 'class = \"Emacs\"' emacs\n\n# You can also use regular expressions for matching.\n# Match windows with title ending with the string \"Firefox\"\nrun-or-raise 'name ~ \".*Firefox$\"' firefox\n\n# You can combine multiple comparisons with logical operators.\n# Match windows with the role \"browser\" that do not have the class \"Chromium\".\nrun-or-raise 'role = \"browser\" \u0026\u0026 ! class = \"Chromium\"' firefox\n\n# Even more complex conditions are possible.\n# This is getting silly\nrun-or-raise '! name ~ \".*\\d+.*\" || role = \"browser\" \u0026\u0026 ! class = \"Emacs\"' urxvt\n```\n\n## Integration with External Tools\n\n`run-or-raise` can be combined with just about any tool that allows executing\narbitrary commands in response to key events. Bellow are some hints about\nconfiguring `run-or-raise` to work with various applications:\n\n### xbindkeys Keyboard Shortcut Manager\n\n[xbindkeys](http://www.nongnu.org/xbindkeys/) is an application for executing\ncommands based on key events. `run-or-raise` can be combined with it to only\nlaunch applications if they are not already running. For example, to launch or\nfocus Firefox by pressing `Shift+Mod4+b`, one could use the following\n`xbindkeys` configuration:\n\n``` shell\n\"run-or-raise 'role = \\\"browser\\\"' firefox\"\n\tShift+Mod4+b\n```\n\n### i3 Window Manager\n\n[i3](https://i3wm.org) is a tiling window manager that, among other things,\nsupports binding arbitrary commands to arbitrary keys. To bind `run-or-raise`\ninvocation to a key with i3, one might specify something like the following in\ni3's configuration file:\n\n``` shell\nbindsym Mod4+Shift+b exec --no-startup-id \\\n\trun-or-raise 'role = \"browser\"' firefox\n```\n\n### KDE Custom Shortcuts\n\n[KDE](https://www.kde.org) allows binding arbitrary commands to key presses\nusing [Custom Shortcuts manager](https://docs.kde.org/trunk5/en/kde-workspace/kcontrol/khotkeys/index.html#intro).\nThrough this graphical configuration utility, `run-or-raise` can be used to\nlaunch or focus applications.\n\n### Desktop Entries\n\n[Desktop Entries](https://developer.gnome.org/integration-guide/stable/desktop-files.html.en)\nare used to define shortcuts that appear in application menus and launchers. In\naddition to application name and icon they also define what commands should be\nexecuted when an application is launched. `run-or-raise` can be used as a part\nof a desktop file to mandate that only a single instance of a particular\napplication should be started. For example, Spotify on Linux does not currently\nenforce that only a single instance of the application can be launched, this is\nannoying since having multiple audio players open is rarely what one wants.\nIntegrating `run-or-raise` into a desktop file means replacing the `Exec` key\nwith a one that invokes `run-or-raise` to check if the application is already\nrunning:\n\n``` desktop\n[Desktop Entry]\nName=Spotify\nExec=run-or-raise 'class = \"Spotify\"' spotify %U\n...\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoft%2Frun-or-raise","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoft%2Frun-or-raise","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoft%2Frun-or-raise/lists"}