AdGuard DNS CLI
<img src="https://cdn.adtidy.org/website/images/AdGuardDNS_black.svg" width="300px" />
</picture>
A cross-platform lightweight DNS client for AdGuard DNS. It operates as a DNS server that forwards DNS requests to the corresponding upstream resolvers.
Supported operating systems:
Supported CPU architectures:
-
Download and unpack the .tar.gz or .zip archive from the releases page.
> [!WARNING]
> On macOS, it's crucial that globally installed daemons are owned by root (see the launchd documentation), so the adguarddns-cli executable must be placed in the /Applications/ directory or its subdirectory.
-
Install it as a service by running:
./adguarddns-cli -s install -v
-
Edit the configuration file config.yaml.
-
Start the service:
./adguarddns-cli -s start -v
To check that it works, use any DNS checking utility. For example, using nslookup:
nslookup -debug 'www.example.com' '127.0.0.1'
Just download and install using the MSI installer from the releases page.
To check that it works, use any DNS checking utility. For example, using nslookup.exe:
nslookup -debug "www.example.com" "127.0.0.1"
See CONTRIBUTING.md for more details on how to contribute.
You will need Go 1.25 or later. First, register our pre-commit hooks:
make init
Then, install the necessary tools and dependencies:
make go-deps
That’s pretty much it! You should now be able to lint, test, and build the adguarddns-cli binary:
make go-lint
make go-test
make go-build
For building packages, you might need additional tools, such as GnuPG, MSI Tools (v0.103 and later), etc. See ./scripts/make/build-release.sh.
Each option overrides the corresponding value provided by the configuration file and the environment.
Option -h makes AdGuard DNS CLI print out a help message to standard output and exit with a success status-code.
Option -s specifies the OS service action. Possible values are:
install: installs AdGuard DNS CLI as a service;restart: restarts the running AdGuard DNS CLI service.start: starts the installed AdGuard DNS CLI service;status: shows the status of the installed AdGuard DNS CLI service;stop: stops the running AdGuard DNS CLI;uninstall: uninstalls AdGuard DNS CLI service;
Option -v enables the verbose log output.
Option --version makes AdGuard DNS CLI print out the version of the application to standard output and exit with a success status-code.
The YAML configuration file is described in its own article, and there is also a sample configuration file config.dist.yaml. Some configuration parameters can also be overridden using the environment.
There are a few different exit codes that may appear under different error conditions:
-
0: Successfully finished and exited, no errors.
-
1: Internal error, most likely a misconfiguration.
-
2: Bad command-line argument or value.