AdGuard-Tui

Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance

About

Getting Started

There are several options for running...

Docker

docker run -it obaraelijah/adguard-tui

You may also pass in your AdGuard info with env vars (using -e), see the Configuring section for an example, and list of availible config params.
If you experience issues with DockerHub, or would rather use a different registry, the image is also available via GHCR - just replace the image name with: ghcr.io/lissy93/adguard-tui. Alternatively, if you'd like to build it yourself from source, you can do so with docker buildx build -t adguard-tui . then run it with docker run -it adguard-tui.

Executable

Head to the Releases tab, and download the executable for your system. Then, just run it by either double-clicking on it, or for Linux/Mac users, by running ./adguard-tui-linux from the command line (don't forget to make it executable first with chmod +x adguard-tui-linux)

Install from Crates.io

cargo install adguard-tui
adguard-tui

adguard-tui is published as a crate to crates.io/crates/adguard-tui. So providing you've got Cargo installed, you can pull the binary directly, and then execute it as above. Again, see the Configuring section below for how to pass in your AdGuard info.

Build from Source

git clone git@github.com:obaraelijah/adguard-tui.git && \
cd adguard-tui && \
make

You'll need git, cargo and make (see here for installation notes). You can also run the cargo commands defined in the Makefile directly, e.g. cargo run

One-Liner

Configuring

The app requires the details of an AdGuard instance to connect to. This info can be provided either as environmental variables, or passed in as flag parameters. If any of these fields are missing or incomplete, you'll be prompted to enter a value once the app starts.

The following params are accepted:

• ADGUARD_IP / --adguard-ip - The IP address of your local AdGuard Home instance
• ADGUARD_PORT / --adguard-port - The port that AdGuard is running on
• ADGUARD_USERNAME / --adguard-username - An AdGuard Home username
• ADGUARD_PASSWORD / --adguard-password - An AdGuard Home password

adguard-tui -- \
	--adguard-ip "192.168.180.1" \
	--adguard-port "3000" \
	--adguard-username "admin" \
	--adguard-password "bobs-your-uncle"

ADGUARD_IP="192.168.180.1" ADGUARD_PORT="3000" ADGUARD_USERNAME="admin" ADGUARD_PASSWORD="bobs-your-uncle" adguard-tui

docker run \
	-e "ADGUARD_IP=192.168.180.1" \
	-e "ADGUARD_PORT=3000" \
	-e "ADGUARD_USERNAME=admin" \
	-e "ADGUARD_PASSWORD=bobs-your-uncle" \
	-it obaraelijah/adguard-tui

Web Mode

The terminal dashboard can also be viewed via a browser, thanks to ttyd.

Development

Prerequisites

You'll need Rust installed. Run: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - see the installation docs. You'll also need Git, if you don't already have it.

Then clone the repo, and cd into it, with: git clone git@github.com:obaraelijah/adguard-tui.git && cd adguard-tui

You can view the full list of availible project commands in the Makefile

Run

To build and run the project for development, run cargo run

Technical Docs

The documentation can be viewed at:

Testing and Quality

• cargo test - Run unit tests
• cargo check - Ensure app is compilable
• cargo bench - Execute benchmarks
• cargo clippy - Analyse areas for improvement
• cargo doc - Generate the documentation

Building

Once your finished developing, you can build the project for production with: cargo build --release The binaries for your system will then be available in the ./target/release/ directory of the project. You can execute this directly, e.g. by running ./target/release/adguard-tui (add .exe if on Windows)

Credits

Contributors

Sponsors

Dependencies

Mirror

Contributing

Contributions of any kind are very welcome (and would be much appreciated!) For Code of Conduct, see Contributor Convent. For project setup, see the Development section.

New here?

To get started, fork the repo, make your changes, add, commit and push the code, then come back here to open a pull request. If you're new to GitHub or open source, this guide or the git docs may help you get started, but feel free to reach out if you need any support.

Not a coder?

You can support the project in other ways too, drop us a star, consider sponsoring us on GitHub, share within your network, and report any bugs you come across.

License

obaraelijah/adguard-tui is licensed under MIT © Elijah Samson 2025.
^{For information, see TLDR Legal > MIT}

The MIT License (MIT)
Copyright (c) Elijah Samson <elijahsam@omg.com> 

Permission is hereby granted, free of charge, to any person obtaining a copy 
of this software and associated documentation files (the "Software"), to deal 
in the Software without restriction, including without limitation the rights 
to use, copy, modify, merge, publish, distribute, sub-license, and/or sell 
copies of the Software, and to permit persons to whom the Software is furnished 
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included install 
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANT ABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

© Elijah Samson 2025
Licensed under MIT

^{Thanks for visiting :)}