Add antctl debug mode configuration (v0.3.26)

- Added --antctl_debug option for antctl process manager
- Environment variable: ANTCTL_DEBUG
- Enables debug output for all antctl commands by adding --debug flag
- Automatically enabled when WNM logging level is set to DEBUG
- Added antctl_debug field to Machine model (boolean/integer)
- Updated AntctlManager to check debug mode during initialization
- Updated configuration system for persistent and temporary debug mode
- Added comprehensive documentation to USER-GUIDE-PART3.md

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: ambled

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 ## [Unreleased]
 
+## [0.3.26] - 2025-12-28
+
+### Added
+- **Antctl debug mode configuration**: Added `--antctl_debug` option for antctl process manager
+  - Environment variable: `ANTCTL_DEBUG`
+  - Default: `False` (automatically enabled when `--loglevel DEBUG` is set)
+  - Enables debug output for all antctl commands by adding `--debug` flag to antctl invocations
+  - Automatically enabled when WNM logging level is set to DEBUG
+  - Use cases: Troubleshooting antctl issues, debugging node management problems, development and testing
+  - Only affects `antctl+user` and `antctl+sudo` process managers
+  - Added to Machine model with database field `antctl_debug` (boolean/integer)
+  - Added command-line option and configuration system support
+  - Updated AntctlManager to check debug mode during initialization and add `--debug` to command
+  - Debug mode can be enabled persistently (updates database) or temporarily via command-line
+  - Documentation added to USER-GUIDE-PART3.md with comprehensive usage examples
+  - Examples:
+    - Via flag: `wnm --antctl_debug`
+    - Via env: `export ANTCTL_DEBUG=1; wnm`
+    - Auto with debug logging: `wnm --loglevel DEBUG`
+    - Persistent: `wnm --force_action update_config --antctl_debug`
+
 ## [0.3.25] - 2025-12-16
 
 ### Added

docs/USER-GUIDE-PART3.md

@@ -606,6 +606,62 @@ No user configuration is currently needed.
   - `--antctl_path /usr/local/bin/antctl`
   - `--antctl_path /opt/homebrew/bin/antctl` (Homebrew on Apple Silicon)
 
+### Antctl Debug Mode
+
+**`--antctl_debug`**
+- Environment variable: `ANTCTL_DEBUG`
+- Type: Boolean flag
+- Default: `False` (automatically enabled when `--loglevel DEBUG` is set)
+- Description: Enable debug output for antctl commands by adding `--debug` flag to all antctl invocations
+- Use cases:
+  - **Troubleshooting antctl issues**: Get detailed output from antctl operations
+  - **Debugging node management problems**: See verbose antctl command execution
+  - **Understanding antctl behavior**: View internal antctl decision-making
+  - **Development and testing**: Monitor antctl operations in detail
+- Notes:
+  - Only affects `antctl+user` and `antctl+sudo` process managers
+  - Automatically enabled when WNM logging level is set to DEBUG
+  - When enabled, all antctl commands run with `--debug` flag (e.g., `antctl --debug start`, `antctl --debug add`)
+  - Debug output from antctl appears in WNM logs
+  - Can be enabled persistently in database or temporarily via command-line
+- Examples:
+
+**Enable debug mode for all antctl operations:**
+```bash
+# Via command-line flag
+wnm --antctl_debug
+
+# Via environment variable
+export ANTCTL_DEBUG=1
+wnm
+
+# Automatically enabled with DEBUG logging
+wnm --loglevel DEBUG
+```
+
+**Persistent debug configuration:**
+```bash
+# Enable for all future runs (updates database)
+wnm --force_action update_config --antctl_debug
+
+# Or add to config file
+echo "antctl_debug=True" >> ~/.local/share/wnm/config
+```
+
+**Temporary debug session:**
+```bash
+# Debug a specific operation
+wnm --antctl_debug --force_action add --count 1
+```
+
+**Disable debug mode:**
+```bash
+# Debug mode stays enabled once set in database
+# To disable, you must explicitly turn it off
+# Setting the environment varialbe to false should persist
+ANTCTL_DEBUG=false
+```
+
 ### Process Manager Selection
 
 **`--process_manager`**

src/wnm/__init__.py

@@ -1,3 +1,3 @@
 """A service to manage a cluster of decentralized Autonomi nodes"""
 
-__version__ = "0.3.25"
+__version__ = "0.3.26"

src/wnm/config.py

@@ -542,6 +542,12 @@ def load_config():
         env_var="ANTCTL_PATH",
         help="Path to the antctl binary (default: ~/.local/bin/antctl)",
     )
+    c.add(
+        "--antctl_debug",
+        env_var="ANTCTL_DEBUG",
+        help="Enable debug output for antctl commands (also enabled when --loglevel DEBUG is set)",
+        action="store_true",
+    )
 
     options = c.parse_known_args()[0] or []
 
@@ -755,6 +761,11 @@ def merge_config_changes(options, machine_config):
     # Only update antctl_path if explicitly provided (not None)
     if options.antctl_path and options.antctl_path != machine_config.antctl_path:
         cfg["antctl_path"] = options.antctl_path
+    # Only update antctl_debug if explicitly provided (check if in command line or env var)
+    # Don't update based on store_true default value of False
+    if "--antctl_debug" in sys.argv or "--antctl-debug" in sys.argv or os.getenv("ANTCTL_DEBUG"):
+        if bool(options.antctl_debug) != bool(machine_config.antctl_debug):
+            cfg["antctl_debug"] = bool(options.antctl_debug)
 
     return cfg
 
@@ -906,6 +917,9 @@ def load_anm_config(options):
         _get_option(options, "antctl_path") or "~/.local/bin/antctl"
     )
 
+    # antctl debug mode (defaults to False)
+    anm_config["antctl_debug"] = bool(_get_option(options, "antctl_debug", False))
+
     return anm_config
 
 
@@ -1012,6 +1026,7 @@ def define_machine(options):
         "no_upnp": bool(_get_option(options, "no_upnp", False)),
         "antnode_path": _get_option(options, "antnode_path") or "~/.local/bin/antnode",
         "antctl_path": _get_option(options, "antctl_path") or "~/.local/bin/antctl",
+        "antctl_debug": bool(_get_option(options, "antctl_debug", False)),
     }
 
     # Set default process manager based on platform if not specified

src/wnm/models.py

@@ -121,6 +121,9 @@ class Machine(Base):
     antctl_path: Mapped[Optional[str]] = mapped_column(
         UnicodeText, default="~/.local/bin/antctl"
     )
+    antctl_debug: Mapped[bool] = mapped_column(
+        Integer, default=0
+    )  # SQLite uses 0/1 for boolean
 
     # Relationships
     containers: Mapped[list["Container"]] = relationship(
@@ -177,6 +180,7 @@ def __init__(
         no_upnp=True,
         antnode_path="~/.local/bin/antnode",
         antctl_path="~/.local/bin/antctl",
+        antctl_debug=False,
         survey_delay=0,
         action_delay=0,
     ):
@@ -227,6 +231,7 @@ def __init__(
         self.no_upnp = no_upnp
         self.antnode_path = antnode_path
         self.antctl_path = antctl_path
+        self.antctl_debug = antctl_debug
 
     def __repr__(self):
         return (

src/wnm/process_managers/antctl_manager.py

@@ -73,6 +73,25 @@ def __init__(
         else:
             self.antctl_cmd = [antctl_path]
 
+        # Check if we should enable debug mode
+        # Debug is enabled if either:
+        # 1. antctl_debug flag is set in machine config
+        # 2. Current logging level is DEBUG
+        debug_mode = False
+
+        # Check machine config for antctl_debug setting
+        if machine_config and hasattr(machine_config, 'antctl_debug') and machine_config.antctl_debug:
+            debug_mode = True
+
+        # Also enable debug mode if logging level is DEBUG
+        if logging.getLogger().getEffectiveLevel() == logging.DEBUG:
+            debug_mode = True
+
+        # Add --debug flag to command if debug mode is enabled
+        if debug_mode:
+            self.antctl_cmd.append("--debug")
+            logging.debug("AntctlManager: Debug mode enabled for antctl commands")
+
     def _run_antctl(
         self, args: list, capture_output: bool = True
     ) -> subprocess.CompletedProcess: