AdGuard DNS CLI

A cross-platform lightweight DNS client for AdGuard DNS. It operates as a DNS server that forwards DNS requests to the corresponding upstream resolvers.

Quick start

Supported operating systems:

• Linux;
• macOS;
• Windows.

Supported CPU architectures:

• 64-bit ARM;
• AMD64;
• i386.

Getting started

Unix-like

1. 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.

2. Install it as a service by running:

   ./adguarddns-cli -s install -v

3. Edit the configuration file config.yaml.

4. 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'

Windows

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"

Developing and contributing

See CONTRIBUTING.md for more details on how to contribute.

Development quick start

You will need Go 1.27 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, ./scripts/make/build-msi.sh, and ./scripts/make/pack-release.sh.

Command-line options

Each option overrides the corresponding value provided by the configuration file and the environment.

Help

Option -h makes AdGuard DNS CLI print out a help message to standard output and exit with a success status-code.

Service

Option -s <value> 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;

Verbose

Option -v enables the verbose log output.

Version

Option --version makes AdGuard DNS CLI print out the version of the application to standard output and exit with a success status-code.

Configuration

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.

Exit codes

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.