Skip to main content

Overview

What is 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​

caution

AdGuard DNS CLI is still in the Beta stage. It may be unstable.

Supported operating systems:

  • Linux
  • macOS
  • Windows

Supported CPU architectures:

  • 64-bit ARM
  • AMD64
  • i386

Getting started​

Unix-like operating systems​

  1. Download and unpack the .tar.gz or .zip archive from the releases page.

    caution

    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"

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​

File​

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.