Make log level better configurable in CLI. Propagate it from client to WM server.

Author: Aksem

docs/cli.md

@@ -55,7 +55,7 @@ python -m finecode run [options] <action> [<action> ...] [payload] [--config.<ke
 | `--project=<name>` | Run only in this project. Repeatable for multiple projects. |
 | `--concurrently` | Run actions concurrently within each project |
 | `--shared-server` | Connect to the shared persistent WM Server instead of starting a dedicated one |
-| `--trace` | Enable verbose (trace-level) logging |
+| `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--no-env-config` | Ignore `FINECODE_CONFIG_*` environment variables |
 | `--no-save-results` | Do not write action results to the cache directory |
 
@@ -114,15 +114,15 @@ python -m finecode run lint --config.ruff.line_length=120
 Create and populate virtual environments for all handler dependencies.
 
 ```
-python -m finecode prepare-envs [--recreate] [--trace] [--debug]
+python -m finecode prepare-envs [--recreate] [--log-level=<level>] [--debug]
 ```
 
 Must be run from the workspace or project root. Creates venvs under `.venvs/<env_name>/` and installs each handler's declared dependencies.
 
 | Option | Description |
 |---|---|
 | `--recreate` | Delete and recreate all venvs from scratch |
-| `--trace` | Enable verbose logging |
+| `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--debug` | Wait for a debugpy client on port 5680 before starting |
 
 ---
@@ -132,15 +132,15 @@ Must be run from the workspace or project root. Creates venvs under `.venvs/<env
 Dump the fully resolved configuration for a project to disk, useful for debugging preset and config merging.
 
 ```
-python -m finecode dump-config --project=<name> [--trace] [--debug]
+python -m finecode dump-config --project=<name> [--log-level=<level>] [--debug]
 ```
 
 Output is written to `<cwd>/finecode_config_dump/`.
 
 | Option | Description |
 |---|---|
 | `--project=<name>` | **(Required)** Project to dump config for |
-| `--trace` | Enable verbose logging |
+| `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--debug` | Wait for a debugpy client on port 5680 |
 
 ---
@@ -160,7 +160,7 @@ python -m finecode start-lsp --stdio | --socket <port> | --ws [--host <host>] [-
 | `--ws` | Start a WebSocket server |
 | `--host <host>` | Host for TCP/WS server (default: 127.0.0.1 for TCP) |
 | `--port <port>` | Port for TCP/WS server |
-| `--trace` | Enable verbose logging |
+| `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--debug` | Wait for a debugpy client on port 5680 |
 
 The LSP server connects to the **FineCode WM Server** on startup (starting one if needed). See [LSP and MCP Architecture](reference/lsp-mcp-architecture.md) for details.
@@ -172,13 +172,13 @@ The LSP server connects to the **FineCode WM Server** on startup (starting one i
 Start the FineCode MCP server on stdio. Connects to a running FineCode WM Server (or starts one) and exposes FineCode tools via the Model Context Protocol.
 
 ```text
-.venvs/dev_workspace/bin/python -m finecode start-mcp [--workdir=<path>] [--trace]
+.venvs/dev_workspace/bin/python -m finecode start-mcp [--workdir=<path>] [--log-level=<level>]
 ```
 
 | Option | Description |
 | --- | --- |
 | `--workdir=<path>` | Workspace root directory (default: current directory). |
-| `--trace` | Enable verbose logging |
+| `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 
 Typically started automatically by MCP-compatible clients (for example, Claude Code) — see [IDE and MCP Setup](getting-started-ide-mcp.md#mcp-setup-for-ai-clients).
 
@@ -189,12 +189,12 @@ Typically started automatically by MCP-compatible clients (for example, Claude C
 Start the FineCode Workspace Manager Server standalone (TCP JSON-RPC), listen for client connections. Shuts down after the last client disconnects and the disconnect timeout expires.
 
 ```text
-python -m finecode start-wm-server [--trace] [--disconnect-timeout=<seconds>]
+python -m finecode start-wm-server [--log-level=<level>] [--disconnect-timeout=<seconds>]
 ```
 
 | Option | Description |
 | --- | --- |
-| `--trace` | Enable verbose logging |
+| `--log-level=<level>` | Set log level: `TRACE`, `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
 | `--disconnect-timeout=<seconds>` | Seconds to wait after the last client disconnects before shutting down (default: 30) |
 
 Usually started automatically by `start-lsp` or `start-mcp`. Can also be started manually for debugging.

src/finecode/cli.py

@@ -172,7 +172,7 @@ def cli(): ...
 
 
 @cli.command()
-@click.option("--trace", "trace", is_flag=True, default=False)
+@click.option("--log-level", "log_level", default="INFO", type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), show_default=True)
 @click.option("--debug", "debug", is_flag=True, default=False)
 @click.option(
     "--socket", "tcp", default=None, type=int, help="start a TCP server"
@@ -186,7 +186,7 @@ def cli(): ...
     "--port", "port", default=None, type=int, help="Port for TCP and WS server"
 )
 def start_lsp(
-    trace: bool,
+    log_level: str,
     debug: bool,
     tcp: int | None,
     ws: bool,
@@ -215,7 +215,7 @@ def start_lsp(
         raise ValueError("Specify either --tcp, --ws or --stdio")
 
     asyncio.run(
-        wm_lsp_server.start(comm_type=comm_type, host=host, port=port, trace=trace)
+        wm_lsp_server.start(comm_type=comm_type, host=host, port=port, log_level=log_level)
     )
 
 
@@ -247,7 +247,7 @@ def run(ctx) -> None:
     workdir_path: pathlib.Path = pathlib.Path(os.getcwd())
     processed_args_count: int = 0
     concurrently: bool = False
-    trace: bool = False
+    log_level: str = "INFO"
     no_env_config: bool = False
     save_results: bool = True
     map_payload_fields: set[str] = set()
@@ -272,8 +272,8 @@ def run(ctx) -> None:
             projects.append(project)
         elif arg == "--concurrently":
             concurrently = True
-        elif arg == "--trace":
-            trace = True
+        elif arg.startswith("--log-level"):
+            log_level = arg.removeprefix("--log-level=").upper()
         elif arg == "--no-env-config":
             no_env_config = True
         elif arg == "--no-save-results":
@@ -287,7 +287,7 @@ def run(ctx) -> None:
             break
         processed_args_count += 1
 
-    logger_utils.init_logger(log_name="cli", trace=trace, stdout=True)
+    logger_utils.init_logger(log_name="cli", log_level=log_level, stdout=True)
 
     # Parse handler config from env vars
     handler_config_overrides: dict[str, dict[str, dict[str, str]]] = {}
@@ -359,6 +359,7 @@ def run(ctx) -> None:
                 save_results,
                 map_payload_fields,
                 own_server=not shared_server,
+                log_level=log_level,
             )
         )
         click.echo(result.output)
@@ -384,11 +385,11 @@ def run(ctx) -> None:
 
 
 @cli.command()
-@click.option("--trace", "trace", is_flag=True, default=False)
+@click.option("--log-level", "log_level", default="INFO", type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), show_default=True)
 @click.option("--debug", "debug", is_flag=True, default=False)
 @click.option("--recreate", "recreate", is_flag=True, default=False)
 @click.option("--shared-server", "shared_server", is_flag=True, default=False)
-def prepare_envs(trace: bool, debug: bool, recreate: bool, shared_server: bool) -> None:
+def prepare_envs(log_level: str, debug: bool, recreate: bool, shared_server: bool) -> None:
     """
     `prepare-envs` should be called from workspace/project root directory.
     """
@@ -402,7 +403,7 @@ def prepare_envs(trace: bool, debug: bool, recreate: bool, shared_server: bool)
         except Exception as e:
             logger.info(e)
 
-    logger_utils.init_logger(log_name="cli", trace=trace, stdout=True)
+    logger_utils.init_logger(log_name="cli", log_level=log_level, stdout=True)
     user_messages._notification_sender = show_user_message
 
     try:
@@ -411,6 +412,7 @@ def prepare_envs(trace: bool, debug: bool, recreate: bool, shared_server: bool)
                 workdir_path=pathlib.Path(os.getcwd()),
                 recreate=recreate,
                 own_server=not shared_server,
+                log_level=log_level,
             )
         )
     except prepare_envs_cmd.PrepareEnvsFailed as exception:
@@ -423,11 +425,11 @@ def prepare_envs(trace: bool, debug: bool, recreate: bool, shared_server: bool)
 
 
 @cli.command()
-@click.option("--trace", "trace", is_flag=True, default=False)
+@click.option("--log-level", "log_level", default="INFO", type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), show_default=True)
 @click.option("--debug", "debug", is_flag=True, default=False)
 @click.option("--project", "project", type=str)
 @click.option("--shared-server", "shared_server", is_flag=True, default=False)
-def dump_config(trace: bool, debug: bool, project: str | None, shared_server: bool):
+def dump_config(log_level: str, debug: bool, project: str | None, shared_server: bool):
     if debug is True:
         import debugpy
 
@@ -441,7 +443,7 @@ def dump_config(trace: bool, debug: bool, project: str | None, shared_server: bo
         click.echo("--project parameter is required", err=True)
         return
 
-    logger_utils.init_logger(log_name="cli", trace=trace, stdout=True)
+    logger_utils.init_logger(log_name="cli", log_level=log_level, stdout=True)
     user_messages._notification_sender = show_user_message
 
     try:
@@ -450,6 +452,7 @@ def dump_config(trace: bool, debug: bool, project: str | None, shared_server: bo
                 workdir_path=pathlib.Path(os.getcwd()),
                 project_name=project,
                 own_server=not shared_server,
+                log_level=log_level,
             )
         )
     except dump_config_cmd.DumpFailed as exception:
@@ -459,18 +462,18 @@ def dump_config(trace: bool, debug: bool, project: str | None, shared_server: bo
 
 @cli.command()
 @click.option("--workdir", "workdir", default=None, type=str, help="Workspace root directory")
-@click.option("--trace", "trace", is_flag=True, default=False)
-def start_mcp(workdir: str | None, trace: bool):
+@click.option("--log-level", "log_level", default="INFO", type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), show_default=True)
+def start_mcp(workdir: str | None, log_level: str):
     """Start the FineCode MCP server (stdio). Connects to a running FineCode WM Server."""
     from finecode import mcp_server
 
-    logger_utils.init_logger(log_name="mcp_server", trace=trace, stdout=False)
+    logger_utils.init_logger(log_name="mcp_server", log_level=log_level, stdout=False)
     workdir_path = pathlib.Path(workdir) if workdir else pathlib.Path(os.getcwd())
     mcp_server.start(workdir_path)
 
 
 @cli.command()
-@click.option("--trace", "trace", is_flag=True, default=False)
+@click.option("--log-level", "log_level", default="INFO", type=click.Choice(["TRACE", "DEBUG", "INFO", "WARNING", "ERROR"], case_sensitive=False), show_default=True)
 @click.option(
     "--port-file",
     "port_file",
@@ -487,11 +490,11 @@ def start_mcp(workdir: str | None, trace: bool):
     show_default=True,
     help="Seconds to wait after the last client disconnects before shutting down.",
 )
-def start_wm_server(trace: bool, port_file: str | None, disconnect_timeout: int):
+def start_wm_server(log_level: str, port_file: str | None, disconnect_timeout: int):
     """Start the FineCode WM Server standalone (TCP JSON-RPC). Auto-stops when all clients disconnect."""
     from finecode.wm_server import wm_server
 
-    log_file_path = logger_utils.init_logger(log_name="wm_server", trace=trace, stdout=False)
+    log_file_path = logger_utils.init_logger(log_name="wm_server", log_level=log_level, stdout=False)
     wm_server._log_file_path = log_file_path
     port_file_path = pathlib.Path(port_file) if port_file else None
     asyncio.run(wm_server.start_standalone(port_file=port_file_path, disconnect_timeout=disconnect_timeout))

src/finecode/cli_app/commands/dump_config_cmd.py

@@ -10,12 +10,12 @@ def __init__(self, message: str) -> None:
 
 
 async def dump_config(
-    workdir_path: pathlib.Path, project_name: str, own_server: bool = True
+    workdir_path: pathlib.Path, project_name: str, own_server: bool = True, log_level: str = "INFO"
 ):
     port_file = None
     try:
         if own_server:
-            port_file = wm_server.start_own_server(workdir_path)
+            port_file = wm_server.start_own_server(workdir_path, log_level=log_level)
             try:
                 port = await wm_server.wait_until_ready_from_file(port_file)
             except TimeoutError as exc:

src/finecode/cli_app/commands/prepare_envs_cmd.py

@@ -12,7 +12,7 @@ def __init__(self, message: str) -> None:
 
 
 async def prepare_envs(
-    workdir_path: pathlib.Path, recreate: bool, own_server: bool = True
+    workdir_path: pathlib.Path, recreate: bool, own_server: bool = True, log_level: str = "INFO"
 ) -> None:
     """Prepare all virtual environments for a workspace.
 
@@ -27,7 +27,7 @@ async def prepare_envs(
     port_file = None
     try:
         if own_server:
-            port_file = wm_server.start_own_server(workdir_path)
+            port_file = wm_server.start_own_server(workdir_path, log_level=log_level)
             try:
                 port = await wm_server.wait_until_ready_from_file(port_file)
             except TimeoutError as exc:

src/finecode/cli_app/commands/run_cmd.py

@@ -26,11 +26,12 @@ async def run_actions(
     save_results: bool = True,
     map_payload_fields: set[str] | None = None,
     own_server: bool = False,
+    log_level: str = "INFO",
 ) -> utils.RunActionsResult:
     port_file = None
     try:
         if own_server:
-            port_file = wm_server.start_own_server(workdir_path)
+            port_file = wm_server.start_own_server(workdir_path, log_level=log_level)
             try:
                 port = await wm_server.wait_until_ready_from_file(port_file)
             except TimeoutError as exc:

src/finecode/logger_utils.py

@@ -8,7 +8,7 @@
 from finecode_extension_runner import logs
 
 
-def init_logger(log_name: str, trace: bool, stdout: bool = False) -> Path:
+def init_logger(log_name: str, log_level: str = "INFO", stdout: bool = False) -> Path:
     venv_dir_path = Path(sys.executable).parent.parent
     logs_dir_path = venv_dir_path / "logs"
 
@@ -25,7 +25,7 @@ def init_logger(log_name: str, trace: bool, stdout: bool = False) -> Path:
     logs.set_log_level_for_group(group="finecode_jsonrpc.client", level=logs.LogLevel.INFO)
     log_file_path = logs.save_logs_to_file(
         file_path=logs_dir_path / log_name / f"{log_name}.log",
-        log_level="TRACE" if trace else "INFO",
+        log_level=log_level,
         stdout=stdout,
     )
 

src/finecode/lsp_server/main.py

@@ -9,8 +9,8 @@ async def start(
     comm_type: communication_utils.CommunicationType,
     host: str | None = None,
     port: int | None = None,
-    trace: bool = False,
+    log_level: str = "INFO",
 ) -> None:
-    logger_utils.init_logger(log_name="lsp_server", trace=trace)
+    logger_utils.init_logger(log_name="lsp_server", log_level=log_level)
     server = create_lsp_server()
     await server.start_io_async()

src/finecode/wm_server/wm_server.py

@@ -1223,7 +1223,7 @@ async def wait_until_ready(timeout: float = 30) -> int:
     )
 
 
-def start_own_server(workdir: pathlib.Path) -> pathlib.Path:
+def start_own_server(workdir: pathlib.Path, log_level: str = "INFO") -> pathlib.Path:
     """Start a dedicated WM server subprocess for exclusive use by one CLI call.
 
     Unlike ``ensure_running()``, this always starts a *fresh* process and writes
@@ -1245,7 +1245,7 @@ def start_own_server(workdir: pathlib.Path) -> pathlib.Path:
 
     logger.info(f"Starting dedicated FineCode WM server in {workdir}")
     subprocess.Popen(
-        [sys.executable, "-m", "finecode", "start-wm-server", "--port-file", str(port_file)],
+        [sys.executable, "-m", "finecode", "start-wm-server", "--port-file", str(port_file), "--log-level", log_level],
         cwd=str(workdir),
         stdout=subprocess.DEVNULL,
         stderr=subprocess.DEVNULL,