# Browser Integration

`transtui` can add a torrent and immediately open its normal TUI so you see
it land in the list - handy for registering it as the target when you click
a magnet link or open a downloaded `.torrent` file.

## `--add` mode

```sh
transtui --add "magnet:?xt=urn:btih:..."
transtui --add /path/to/file.torrent
transtui --add "file:///path/to/file.torrent"   # file:// URIs are supported too
```

Adds the torrent to the daemon (using the usual host/port/user/pass
configuration from `config.ini`, optionally overridden with
`-H`/`-P`/`-u`/`-p`, see [Configuration](Configuration.md)), then opens the
regular ncurses UI with the result ("Torrent added: ..." or "Could not add
torrent: ...") shown in the status bar.

`file://` URIs are decoded (percent-decoding, e.g. `%20` → space) before
the file is read, since desktop environments often send a `file://` URI
rather than a plain path when invoking an "open with" handler.

Only one transtui instance runs at a time (enforced via a per-user lock
file). Clicking a second magnet link while transtui is already open adds
the torrent to the daemon and exits immediately instead of opening a second
UI - the running instance picks it up on its next poll. Launching plain
`transtui` (no `--add`) while one is already running just prints
`transtui: already running` and exits.

## Registering as the default handler

`make install` runs this automatically as long as it's not run as root:

```sh
make install PREFIX=$HOME/.local   # binary + desktop/magnet registration, no sudo needed
```

`sudo make install` (system-wide binary install) skips it, since it would
otherwise register the magnet handler under root's `$HOME` instead of yours.
Run it yourself afterward, as your normal user:

```sh
make install-desktop   # installs desktop/transtui-add.desktop and runs xdg-mime
```

`make install-desktop`:

1. Installs `desktop/transtui-add.desktop`
   (`Exec=transtui --add %u`, `Terminal=true`) to
   `~/.local/share/applications/`.
2. Runs `update-desktop-database`.
3. Runs `xdg-mime default transtui-add.desktop x-scheme-handler/magnet`
   and the same for `application/x-bittorrent`.

After that: clicking a magnet link in the browser, or "Open with" on a
downloaded `.torrent` file in the file manager, opens a terminal window
running transtui - `Terminal=true` is required here since ncurses needs a
real TTY to draw itself, which a desktop launcher doesn't provide on its
own.

## Troubleshooting

- **Nothing happens when you click a magnet link**: check that `transtui`
  is on `PATH` (`which transtui`) and that
  `xdg-mime query default x-scheme-handler/magnet` points at
  `transtui-add.desktop`.
- **"Could not add torrent" in the status bar**: the same connection
  problems as in the regular TUI mode can happen here too (wrong host/port/
  password) - see
  [Daemon: setup & troubleshooting](Daemon-Setup-and-Troubleshooting.md).
  If the daemon can't be reached at all, transtui falls back to its normal
  reconnect-help screen instead of showing the add result.