# Mariner [![PyPI version](https://badge.fury.io/py/mariner.svg)](https://badge.fury.io/py/mariner) [![Pipeline status](https://gitlab.com/radek-sprta/mariner/badges/master/pipeline.svg)](https://gitlab.com/radek-sprta/mariner/commits/master) [![Coverage report](https://gitlab.com/radek-sprta/mariner/badges/master/coverage.svg)](https://gitlab.com/radek-sprta/mariner/commits/master) [![Downloads](http://pepy.tech/badge/mariner)](http://pepy.tech/project/mariner)

Navigate torrents in CLI with Mariner. It offers a simple interface for a streamlined experience without annoying ads and pop-up windows.

## Features

- Works on Linux and Windows
- Download torrent files and copy magnet links to clipboard
- Open torrents in your default torrent application
- Show detailed torrent information (seeders, leechers, upload date, size)
- Interactive and non-interactive modes
- Asynchronous I/O for responsive performance
- Extensible via YAML-based tracker definitions
- Supports multiple trackers:
  - LimeTorrents
  - LinuxTracker
  - Nyaa
  - TokyoTosho

![Mariner demonstration](docs/assets/mariner.svg)

## Installation

Mariner requires Python 3.10 or newer.

### Python package

Install from PyPI using pip:

```bash
pip3 install mariner
```

### From source

Clone the repository and build locally:

```bash
git clone git@gitlab.com:radek-sprta/mariner.git
cd mariner
uv build
pip install dist/*.whl
```

## Usage

### Interactive Mode

Start the interactive shell:

```bash
mariner
```

Then search for torrents:

```
(mariner) search Ubuntu -t linuxtracker
(mariner) download 0
(mariner) quit
```

### Non-Interactive Mode

Search for torrents:

```bash
mariner search Ubuntu -t linuxtracker
```

Download results:

```bash
mariner download 0 1 2
```

Copy magnet link to clipboard:

```bash
mariner magnet 0
```

Open in torrent application:

```bash
mariner open 0
```

View torrent details:

```bash
mariner details 0
```

For more information and options, run:

```bash
mariner search --help
```

## Contributing

For information on how to contribute to the project, please check the [Contributor's Guide][contributing]

## Disclaimer

I do not encourage anyone to act in conflict with their local laws and I do not endorse any illegal activity. Some content in the search results provided be Mariner might be illegal in your country and it is up to you to check your local laws before using it. Neither I, nor Mariner can be held liable for any action taken against you as the result of using it.

## Contact

[mail@radeksprta.eu](mailto:mail@radeksprta.eu)

[incoming+radek-sprta/mariner@gitlab.com](incoming+radek-sprta/mariner@gitlab.com)

## Acknowledgements

Mariner uses excellent open-source libraries:

- [BeautifulSoup](https://www.crummy.com/software/BeautifulSoup/) — HTML parsing
- [Cliff](https://github.com/openstack/cliff) — CLI framework
- [httpx](https://github.com/encode/httpx) — Async HTTP client
- [ruamel.yaml](https://yaml.readthedocs.io/) — YAML parsing and serialization
- [Cachalot](https://github.com/lmmx/cachalot) — Caching
- [platformdirs](https://github.com/platformdirs/platformdirs) — Platform-specific paths

## License

GNU General Public License v3.0

[contributing]: https://gitlab.com/radek-sprta/mariner/blob/master/CONTRIBUTING.md
