🚀 gokeenapi

Automate your Keenetic (Netcraze) router management with ease

1729780892144387.mp4

Tired of clicking through Keenetic (Netcraze) web interface? Automate your Keenetic (Netcraze) router management with simple CLI commands.

🇷🇺 Русская версия документации 🇷🇺

🚀 Quick Start • 📖 Documentation • 📋 Config Reference • 🎨 GUI Version • 🤝 Contributing

✨ About

gokeenapi is a CLI tool for automating Keenetic (Netcraze) router management. It handles routes, DNS records, DNS-routing, WireGuard connections, known hosts, and scheduled tasks — all via a YAML config file, with no changes required on the router side. Works over LAN or remotely via KeenDNS.

🚀 Quick Start

The easiest way to get started is by using Docker or by downloading the latest release.

🐳 Docker (Recommended)

Using Docker is the recommended way to run gokeenapi.

Two image tags are available on Docker Hub:

Tag	Description
`stable`	Latest stable release (updated on every release)
`1.7.0`, `1.7.1`, …	Pinned version tag — available starting from `v1.7.0`

# Pull the latest stable image
export GOKEENAPI_IMAGE="noksa/gokeenapi:stable"
# Or pin to a specific version (available since v1.7.0)
# export GOKEENAPI_IMAGE="noksa/gokeenapi:1.7.0"
docker pull "${GOKEENAPI_IMAGE}"

# Run a command
docker run --rm -ti -v "$(pwd)/config_example.yaml":/gokeenapi/config.yaml \
  "${GOKEENAPI_IMAGE}" show-interfaces --config /gokeenapi/config.yaml

📦 Latest Release

Download the latest release for your platform:

⚙️ Configuration

gokeenapi is configured using a yaml file. You can find an example here. For a complete description of every field, see the Config Reference.

To use your configuration file, pass the --config <path> flag with your command.

Reusable Bat-File and Bat-URL Lists

When managing multiple routers with the same routing configuration, you can create a shared YAML file containing bat-file paths, bat-url paths, or both, and reference it across multiple configs.

batfiles/common.yaml:

bat-file:
  - /path/to/discord.bat
  - /path/to/youtube.bat
bat-url:
  - https://example.com/instagram.bat
  - https://example.com/extra.bat

Router config:

routes:
  - interfaceId: Wireguard0
    bat-file:
      - batfiles/common.yaml         # Expanded: only bat-file entries are used
      - /path/to/router-specific.bat # Can mix with regular paths
    bat-url:
      - batfiles/common.yaml         # Expanded: only bat-url entries are used
      - https://example.com/other.bat

The tool automatically detects .yaml/.yml files in the bat-file and bat-url arrays and expands them to their respective list entries. When a YAML file is referenced in bat-file, only its bat-file list is used; when referenced in bat-url, only its bat-url list is used. Relative paths in YAML list files are resolved relative to the YAML file's directory.

Environment Variables

All configuration options can be set via environment variables:

Variable	Description
`GOKEENAPI_CONFIG`	Path to config file (alternative to `--config`)
`GOKEENAPI_KEENETIC_LOGIN`	Router admin login
`GOKEENAPI_KEENETIC_PASSWORD`	Router admin password
`GOKEENAPI_INSIDE_DOCKER`	When set, uses `/etc/gokeenapi` as the data directory

GOKEENAPI_KEENETIC_LOGIN and GOKEENAPI_KEENETIC_PASSWORD are particularly useful for keeping sensitive credentials out of config files. GOKEENAPI_INSIDE_DOCKER is set automatically in the official Docker image.

Security recommendation: Store credentials using environment variables instead of writing them directly into the config file. Config files stored with world-readable permissions (e.g. 0644) will trigger a runtime warning. Restrict permissions with chmod 600 config.yaml and use GOKEENAPI_KEENETIC_LOGIN / GOKEENAPI_KEENETIC_PASSWORD to pass credentials. Add config.yaml and config_*.yaml to your .gitignore to prevent accidental commits (the project's default .gitignore already includes these patterns).

TLS Certificate Verification

When connecting to a router over HTTPS with a self-signed certificate, set tls_skip_verify: true under the keenetic key:

keenetic:
  url: https://192.168.1.1
  login: admin
  password: secret
  tls_skip_verify: true  # Disable TLS verification for self-signed certificates

Note: Only use tls_skip_verify on trusted local networks. Disabling certificate verification exposes the connection to man-in-the-middle attacks.

📋 Config Reference

For the complete reference of all config.yaml fields, see docs/config-reference.md.

See also config_example.yaml for a fully annotated example.

🔧 Supported Routers

gokeenapi has been tested with the following Keenetic (Netcraze) router models:

Keenetic (Netcraze) Start
Keenetic (Netcraze) Viva
Keenetic (Netcraze) Giga

Since the utility works with Keenetic (Netcraze) Start (the most affordable model in the lineup), it should be compatible with all Keenetic (Netcraze) router models.

🎬 Video Demos

Check out these video demonstrations (in Russian) to see gokeenapi in action:

Routes Management

🕐 Scheduler - Automated Task Execution

The scheduler allows you to automate router management by running tasks at specified intervals or fixed times. This is perfect for keeping routes and DNS records up-to-date automatically.

Key Features

Interval-based execution: Run tasks every N hours/minutes (e.g., every 3 hours)
Time-based execution: Run tasks at specific times (e.g., at 02:00, 06:00, 12:00)
Command chaining: Execute multiple commands sequentially (e.g., delete-routes → add-routes)
Multi-router support: Manage multiple routers with a single task
Retry mechanism: Automatically retry failed tasks with configurable delay
Sequential execution: Tasks run in a queue to avoid conflicts

Quick Start

# Run scheduler with config
./gokeenapi scheduler --config scheduler.yaml

Example Configuration

tasks:
  - name: "Update routes every 3 hours"
    commands:
      - add-routes
    configs:
      - /path/to/router1.yaml
      - /path/to/router2.yaml
      - /path/to/router3.yaml
    interval: "3h"
  
  - name: "Refresh routes daily with retry"
    commands:
      - delete-routes
      - add-routes
    configs:
      - /path/to/router1.yaml
    times:
      - "02:00"
    retry: 3           # Retry up to 3 times on failure
    retryDelay: "30s"  # Wait 30 seconds between retries

📖 Read full Scheduler documentation →

📚 Commands

Here are some of the things you can do with gokeenapi. For a full list of commands and options, use the --help flag.

./gokeenapi --help

`show-interfaces`

Aliases: showinterfaces, si, showinterface, show-interface

Displays all available interfaces on your Keenetic (Netcraze) router.

# Show all interfaces
./gokeenapi show-interfaces --config my_config.yaml

# Show only WireGuard interfaces
./gokeenapi show-interfaces --config my_config.yaml --type Wireguard

`add-routes`

Aliases: addroutes, ar

Adds static routes to your router.

./gokeenapi add-routes --config my_config.yaml

`delete-routes`

Aliases: deleteroutes, dr

Deletes static routes for a specific interface.

# Delete routes for all interfaces in the config file
./gokeenapi delete-routes --config my_config.yaml

# Delete routes for a specific interface
./gokeenapi delete-routes --config my_config.yaml --interface-id <your-interface-id>

# Delete routes without confirmation prompt
./gokeenapi delete-routes --config my_config.yaml --force

Tip: To find interface IDs, run show-interfaces.

`delete-all-routes`

Aliases: deleteallroutes, dar

Deletes all static routes from the router in a single request, regardless of interface.

# Delete all routes (with confirmation prompt)
./gokeenapi delete-all-routes --config my_config.yaml

# Delete all routes without confirmation
./gokeenapi delete-all-routes --config my_config.yaml --force

Warning: This removes every user-defined static route on the router at once. Use with caution.

`add-dns-records`

Aliases: adddnsrecords, adr

Adds static DNS records.

./gokeenapi add-dns-records --config my_config.yaml

`delete-dns-records`

Aliases: deletednsrecords, ddr

Deletes static DNS records based on your configuration file.

./gokeenapi delete-dns-records --config my_config.yaml

`add-dns-routing`

Aliases: adddnsrouting, adnsr, adddnsroutes, add-dns-routes

Adds DNS-routing rules (policy-based routing by domain) to your router. This feature allows you to route traffic for specific domains through designated network interfaces.

Requirements: Keenetic firmware version 5.0.1 or higher

./gokeenapi add-dns-routing --config my_config.yaml

How it works:

Loads domains from local .txt files and remote URLs
Creates domain groups (object-groups) containing your specified domains and IP addresses
Associates each group with a network interface via dns-proxy routes
Traffic for domains in a group is automatically routed through the specified interface

Domain sources:

Local .txt files with one domain per line (supports comments with #)
Remote URLs serving domain lists
YAML files containing lists of domain-file or domain-url paths (for organization)

YAML expansion: The tool automatically detects .yaml/.yml files in the domain-file and domain-url arrays and expands them to their contained domain paths (similar to bat-file/bat-url expansion).

Key rule: when a .yaml file is referenced in domain-file, only its domain-file list is extracted; when referenced in domain-url, only its domain-url list is extracted. To use both files and remote URLs from a single YAML manifest, reference it in both keys:
# domains/social.yaml
domain-file:
  - social.txt           # local domains
domain-url:
  - https://example.com/social-extra.txt  # remote domains
# Router config group
- name: social
  domain-file:
    - domains/social.yaml   # extracts domain-file list → social.txt
  domain-url:
    - domains/social.yaml   # extracts domain-url list → remote URL
  interfaceId: Wireguard0
If you reference the YAML only in domain-file, the remote URLs inside it are silently ignored — and vice versa.

NEW: Reusable DNS Routing Groups

You can now create shared YAML files containing complete DNS routing group definitions and import them across multiple router configs. This is different from domain-file/domain-url expansion - you're importing entire group definitions, not just domain lists.

custom/common_dns_groups.yaml:

groups:
  - name: youtube
    domain-url:
      - domains/youtube.yaml
    interfaceId: Wireguard0
  - name: telegram
    domain-url:
      - domains/telegram.yaml
    interfaceId: Wireguard0
  - name: trackers
    domain-file:
      - domains/trackers.yaml
    interfaceId: Wireguard0

Router config:

dns:
  routes:
    groups:
      - common_dns_groups.yaml    # Import all groups from file
      - name: router-specific     # Mix with router-specific groups
        domain-file:
          - domains/local.txt
        interfaceId: GigabitEthernet0

This allows you to maintain common DNS routing rules in one place and share them across all your routers. When you add telegram to one router, just update common_dns_groups.yaml and all routers using it will get the update.

There are two ways to import a shared groups file:

groups:
  # Simple string — import all groups as-is
  - common_dns_groups.yaml

  # Object with file: key — same import, but with interfaceId override
  # All groups from the file will use Wireguard1 instead of their original interface
  - file: common_dns_groups.yaml
    interfaceId: Wireguard1

The file: + interfaceId form is useful when the same common groups file is shared across routers that use different WireGuard interfaces (e.g., Wireguard0 on one router, Wireguard1 on another) — you define interface names once per router config rather than duplicating the entire groups file.

Example use cases:

Route social media traffic through a VPN (Wireguard0)
Route streaming services through a different connection
Split traffic by domain for load balancing or privacy
Use community-maintained domain lists from URLs

`delete-dns-routing`

Aliases: deletednsrouting, ddnsr, deletednsroutes, delete-dns-routes

Deletes DNS-routing rules that match your configuration file.

# Delete DNS-routing rules with confirmation prompt
./gokeenapi delete-dns-routing --config my_config.yaml

# Delete DNS-routing rules without confirmation prompt
./gokeenapi delete-dns-routing --config my_config.yaml --force

The command will:

Identify dns-proxy routes and object-groups matching your configuration
Display the rules to be deleted
Request confirmation (unless --force flag is used)
Remove dns-proxy routes first, then object-groups

`delete-all-dns-routing`

Aliases: deletealldnsrouting, dadnsr

Deletes all DNS-routing groups from the router in a single operation, regardless of what is defined in the config file. Useful for fully resetting DNS-routing before re-applying a new or updated configuration.

# Delete all DNS-routing groups (with confirmation prompt)
./gokeenapi delete-all-dns-routing --config my_config.yaml

# Delete all DNS-routing groups without confirmation
./gokeenapi delete-all-dns-routing --config my_config.yaml --force

Warning: This removes every DNS-routing group on the router. Use before re-applying after renaming or reorganising groups.

Requirements: Keenetic firmware version 5.0.1 or higher

`add-awg`

Aliases: addawg, aawg

Adds a new WireGuard connection from a .conf file.

./gokeenapi add-awg --config my_config.yaml --conf-file <path-to-conf> --name MySuperInterface

`update-awg`

Aliases: updateawg, uawg

Updates an existing WireGuard connection from a .conf file. Supports AmneziaWG (AWG 2.0) parameters.

./gokeenapi update-awg --config my_config.yaml --conf-file <path-to-conf> --interface-id <interface-id>

# Preview changes without applying them
./gokeenapi update-awg --config my_config.yaml --conf-file <path-to-conf> --interface-id <interface-id> --dry-run

Tip: To find interface IDs, run show-interfaces. Use --dry-run to see a unified diff of what would change before applying.

`delete-known-hosts`

Aliases: deleteknownhosts, dkh

Deletes known hosts by name or MAC using regex pattern.

# Delete hosts by name pattern
./gokeenapi delete-known-hosts --config my_config.yaml --name-pattern "pattern"

# Delete hosts by MAC pattern
./gokeenapi delete-known-hosts --config my_config.yaml --mac-pattern "pattern"

# Delete hosts without confirmation prompt
./gokeenapi delete-known-hosts --config my_config.yaml --name-pattern "pattern" --force

`scheduler`

Aliases: schedule, sched

Runs automated tasks at specified intervals or fixed times. See Scheduler documentation for the full configuration reference.

./gokeenapi scheduler --config scheduler.yaml

`exec`

Aliases: e

Execute custom Keenetic (Netcraze) CLI commands directly on your router.

# Show system information
./gokeenapi exec --config my_config.yaml show version

# Display interface statistics
./gokeenapi exec --config my_config.yaml show interface

# Show routing table
./gokeenapi exec --config my_config.yaml show ip route

🤝 Contributing

Contributions are welcome! If you have any ideas, suggestions, or bug reports, please open an issue or create a pull request.

📄 License

This project is licensed under the MIT License. See the LICENSE file for details.

Name		Name	Last commit message	Last commit date
.github		.github
.kiro/steering		.kiro/steering
batfiles		batfiles
cmd		cmd
docs		docs
internal		internal
pkg		pkg
scripts		scripts
.dockerignore		.dockerignore
.gitignore		.gitignore
.golangci.yml		.golangci.yml
AGENTS.md		AGENTS.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
README_RU.md		README_RU.md
SCHEDULER.md		SCHEDULER.md
SCHEDULER_RU.md		SCHEDULER_RU.md
config_example.yaml		config_example.yaml
docker_integration_test.go		docker_integration_test.go
docker_scheduler_integration_test.go		docker_scheduler_integration_test.go
docker_suite_test.go		docker_suite_test.go
docker_test_helpers.go		docker_test_helpers.go
go.mod		go.mod
go.sum		go.sum
logo.png		logo.png
main.go		main.go
scheduler_example.yaml		scheduler_example.yaml

Latest commit

History

Folders and files

Repository files navigation

🚀 gokeenapi

🇷🇺 Русская версия документации 🇷🇺

✨ About

🚀 Quick Start

🐳 Docker (Recommended)

📦 Latest Release

⚙️ Configuration

Reusable Bat-File and Bat-URL Lists

Environment Variables

TLS Certificate Verification

📋 Config Reference

🔧 Supported Routers

🎬 Video Demos

🕐 Scheduler - Automated Task Execution

Key Features

Quick Start

Example Configuration

📚 Commands

show-interfaces

add-routes

delete-routes

delete-all-routes

add-dns-records

delete-dns-records

add-dns-routing

delete-dns-routing

delete-all-dns-routing

add-awg

update-awg

delete-known-hosts

scheduler

exec

🤝 Contributing

📄 License

About

Resources

Contributing

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages