Rules-based browser launcher for TUI + GNOME.
switchyard.aly.codes
tui
gnome
bowser
go
README.md: clean up, center elements
Aly Raffauf
(Jan 22, 2026, 9:27 AM EST)
18d2ff7c
772b6ff2
+30
-101
+19
-101
README.md
+19
-101
README.md
···
1
-
<h1>
2
-
<img src="data/icons/hicolor/scalable/apps/io.github.alyraffauf.Switchyard.svg" width="64" height="64" align="left" style="margin-right: 10px;">
3
-
Switchyard
4
-
</h1>
5
-
6
-
<br clear="left"/>
7
-
8
-
**A rules-based URL router for Linux.**
9
-
10
-
Set up smart, automatic routing. Or choose your browser on the fly.
11
-
12
-
[](https://github.com/alyraffauf/switchyard/actions/workflows/ci.yml)
1
+
[](https://github.com/alyraffauf/switchyard/actions/workflows/ci.yml) [](http://www.gnu.org/licenses/gpl-3.0)
13
2
14
3
<p align="center">
15
-
<img src="docs/images/switchyard-picker.png" alt="Switchyard Picker" width="600">
4
+
<img src="data/icons/hicolor/scalable/apps/io.github.alyraffauf.Switchyard.svg" width="64" height="64">
5
+
<br>
6
+
<strong style="font-size: 2em;">Switchyard</strong>
7
+
<br><br>
8
+
<strong>A rules-based browser launcher for Linux.</strong>
9
+
<br>
10
+
Set up smart, automatic routing. Or choose your browser on the fly.
16
11
</p>
17
12
18
13
<p align="center">
19
-
<img src="docs/images/switchyard.png" alt="Switchyard Settings" width="600">
14
+
<img src="docs/images/switchyard-picker.png" alt="Switchyard Picker" width="600">
20
15
</p>
21
16
22
17
<p align="center">
23
-
<img src="docs/images/switchyard-rulesedit.png" alt="Switchyard Rule Editor" width="600">
18
+
<a href="https://flathub.org/apps/io.github.alyraffauf.Switchyard"><img src="https://flathub.org/api/badge?locale=en&style=flat" alt="Get it on Flathub"></a>
24
19
</p>
25
20
26
21
## Features
···
38
33
39
34
### Flatpak (Recommended)
40
35
41
-
Requires [just](https://github.com/casey/just) for building.
36
+
Switchyard is available on [Flathub](https://flathub.org/apps/io.github.alyraffauf.Switchyard):
42
37
43
38
```bash
44
-
# Build and install (automatically installs Flatpak runtimes if needed)
45
-
just flatpak
39
+
flatpak install flathub io.github.alyraffauf.Switchyard
46
40
```
47
41
48
42
### Nix Flake
49
43
50
-
A flake is provided for NixOS or Nix users. It also supplies a devShell and a formatter.
51
-
52
-
Add this repository to your flake inputs:
53
-
54
-
```nix
55
-
{
56
-
inputs.switchyard.url = "github:alyraffauf/switchyard";
57
-
}
58
-
```
59
-
60
-
Then, add this to your NixOS configuration:
61
-
62
-
```nix
63
-
# Add to your NixOS configuration
64
-
{
65
-
environment.systemPackages = [
66
-
inputs.switchyard.packages.${system}.default
67
-
];
68
-
}
44
+
```bash
45
+
nix run github:alyraffauf/switchyard
69
46
```
70
47
71
48
### Building from Source
···
73
50
For non-Flatpak builds, requires Go 1.24+, GTK4/libadwaita development libraries, and [just](https://github.com/casey/just).
74
51
75
52
```bash
76
-
# Install dependencies (Fedora)
77
-
just install-deps
78
-
79
-
# Build
53
+
just install-deps # For Fedora
80
54
just build
81
-
82
-
# Install to /usr/local
83
-
sudo just install
84
-
85
-
# Or install to custom prefix
86
-
sudo PREFIX=/usr just install
55
+
sudo just install # To /usr/local
87
56
```
88
57
89
-
### Set as Default Browser
90
-
91
-
After installation, set Switchyard as your default browser so it can route all clicked links:
92
-
93
-
```bash
94
-
xdg-settings set default-web-browser io.github.alyraffauf.Switchyard.desktop
95
-
```
96
-
97
-
Or use your desktop environment's graphical settings to set Switchyard as the default browser.
98
-
99
-
## Usage
58
+
#### Building Flatpak
100
59
101
60
```bash
102
-
# Open settings
103
-
flatpak run io.github.alyraffauf.Switchyard
104
-
105
-
# Open a URL (typically called automatically by the system)
106
-
flatpak run io.github.alyraffauf.Switchyard "https://example.com"
107
-
108
-
# Non-Flatpak
109
-
switchyard
110
-
switchyard "https://example.com"
61
+
just flatpak # Build and install
111
62
```
112
63
113
-
### Keyboard Shortcuts
114
-
115
-
**In the picker:**
116
-
117
-
- `Ctrl+1-9` - Select browser by number
118
-
- `Escape` - Close picker
119
-
120
-
**In settings:**
121
-
122
-
- `Ctrl+Q` - Quit
123
-
124
64
## Documentation
125
65
66
+
- [Using](docs/Using.md) - Set as default browser, usage examples.
126
67
- [Configuration](docs/Configuration.md) - Config file format, rules, and settings.
127
68
- [URI Scheme](docs/URI%20Scheme.md) - Custom `switchyard://` URLs for specifying browser preferences.
128
69
- [Prior Art](docs/Prior%20Art.md) - Similar tools that inspired Switchyard.
129
-
130
-
## Development
131
-
132
-
### Running Tests
133
-
134
-
The project includes unit tests for the core rule matching logic. Tests can run without GTK dependencies.
135
-
136
-
```bash
137
-
# Run tests
138
-
just test
139
-
140
-
# Run tests with coverage report
141
-
just test-coverage
142
-
143
-
# View HTML coverage report
144
-
go tool cover -html=coverage.out
145
-
```
146
-
147
-
Tests are automatically run in CI on every push and pull request.
148
-
149
-
## License
150
-
151
-
[GPL-3.0-or-later](LICENSE.md)
+11
docs/Using.md
+11
docs/Using.md
···
1
+
# Using Switchyard
2
+
3
+
## Set as Default Browser
4
+
5
+
After installation, set Switchyard as your default browser so it can route all clicked links:
6
+
7
+
```bash
8
+
xdg-settings set default-web-browser io.github.alyraffauf.Switchyard.desktop
9
+
```
10
+
11
+
Or use your desktop environment's graphical settings to set Switchyard as the default browser.