feat(cli): print one configuration line by default

- reduce the CLI banner to the credential source unless --verbose
- print the env-file line too when a command fails
- omit the MCP stdio hint from CLI error messages
- flush the banner so it survives a buffered stderr

Author: LukasGold

docs/cli-and-mcp.md

@@ -78,7 +78,9 @@ Global options apply to every command:
 - `--json` / `-j` writes machine-readable JSON to stdout and keeps osw's own
   progress output on stderr, so it pipes cleanly into `jq`.
 - `--read-only` refuses write operations.
-- `--verbose` / `-v` shows full tracebacks instead of a one-line message.
+- `--verbose` / `-v` shows full tracebacks instead of a one-line message, and
+  adds the env-file line to the source report described under
+  [Where settings come from](#where-settings-come-from).
 
 Failures exit non-zero with a short message on stderr and no traceback.
 
@@ -253,13 +255,29 @@ these forms:
 - `(accounts.pwd.yaml found in the working directory)`
 - `(accounts.pwd.yaml found in the working directory, ignored: no entry for domain '<domain>')`, when the discovered file is rejected for the reason given in step 2 above.
 
+Those four forms all belong to a line labelled `credential file`. When no
+credential file is used at all, the line is labelled `credentials` instead and
+takes one of these forms:
+
+- `OSW_USERNAME/OSW_PASSWORD (from the environment)`
+- `OSW_USERNAME/OSW_PASSWORD (from the env file)`
+- `not configured (set OSW_CRED_FILEPATH, or OSW_USERNAME/OSW_PASSWORD)`
+
+The MCP server always prints both lines, the credential one first, then the
+env-file one. The CLI prints one line by default, naming where the
+credential came from. Pass `--verbose` to also print the env-file line. A
+failing command prints both lines regardless of `--verbose`, so a report
+still names every source that was checked.
+
 For example, a verbose CLI run or the MCP server prints:
 
 ```text
 [osw] credential file: /home/me/project/accounts.pwd.yaml (accounts.pwd.yaml found in the working directory)
 [osw] env file       : /home/me/project/.env (found from the working directory upward)
 ```
 
+A non-verbose, successful CLI run prints only the first of those two lines.
+
 ### Credentials
 
 Keep credentials in a gitignored file. They are read once per process, into that

src/osw/cli/main.py

@@ -117,16 +117,20 @@ def _run(op: Operation, typer_ctx: typer.Context, kwargs: dict[str, Any]) -> Non
             kwargs["content"] = json_value(content)
 
     try:
+        verbose = bool(opts.get("verbose"))
+        # Before anything that can fail, so every error still reports which
+        # files were read. --instance is validated against the credential file
+        # this names, so the banner belongs above that check too. The env-file
+        # line is suppressed unless the command is verbose or fails.
+        config.log_config_sources(verbose=verbose)
+
         instance = opts.get("instance")
         if instance:
             try:
                 config.set_active_instance(instance)
             except ValueError as exc:
                 raise errors.UnknownInstance(str(exc)) from exc
 
-        # Before load(), so a misconfiguration that makes loading raise still
-        # reports which files were read.
-        config.log_config_sources()
         settings = config.load(strict=False)
         policy = Policy(
             capture_stdout=bool(opts.get("as_json")),
@@ -138,11 +142,15 @@ def _run(op: Operation, typer_ctx: typer.Context, kwargs: dict[str, Any]) -> Non
         bound = bind(op, context)
         result = bound(**kwargs)
     except OpError as exc:
+        if not verbose:
+            config.log_env_file_source()
         typer.echo(f"{exc.type}: {exc}", err=True)
         raise typer.Exit(exc.exit_code)
     except Exception as exc:
         if opts.get("verbose"):
             raise
+        # A failing command still reports every source, even non-verbosely.
+        config.log_env_file_source()
         typer.echo(f"{type(exc).__name__}: {exc}", err=True)
         raise typer.Exit(1)
 

src/osw/service/config.py

@@ -415,26 +415,45 @@ def _resolve_cred_file() -> Optional[str]:
     return None
 
 
-def log_config_sources(stream=None) -> None:
-    """Print where configuration was read from, one line per source.
+def _describe_env_file() -> str:
+    """Describe where the ``.env`` file came from, for the startup banner."""
+    return {
+        "explicit": f"{_env_file_path} (from {ENV_FILE[0]})",
+        "discovered": f"{_env_file_path} (found from the working directory upward)",
+        "none": "none found (searched from the working directory upward)",
+        "not searched": f"not configured (set {ENV_FILE[0]} to use one)",
+    }[_env_file_origin]
+
+
+def log_config_sources(stream=None, verbose: bool = True) -> None:
+    """Print where configuration was read from, to stderr.
 
     Loads the ``.env`` file first if that has not happened yet, and reads the
     environment directly rather than a ``Settings``. Both so this can run
     *before* settings are loaded: a misconfiguration makes loading raise, and
     that is exactly when knowing which files were read matters most.
 
+    The credential line is printed first, since it is the one line that
+    still appears when ``verbose`` is ``False``; the env-file line is then
+    printed after it, only when ``verbose`` is ``True``. This keeps the two
+    lines in the same relative order regardless of ``verbose``, including in
+    the CLI's failure path, which prints the env-file line (via
+    :func:`log_env_file_source`) after this one has already run.
+
+    ``verbose`` defaults to ``True``, which keeps both lines and matches the
+    MCP server's behaviour (it never passes a value here). The CLI passes
+    ``verbose=False`` for a successful, non-verbose command, and prints the
+    env-file line separately (via :func:`log_env_file_source`) on failure or
+    when the user passed ``--verbose``.
+
     Always writes to ``stderr``: under MCP ``stdout`` carries the JSON-RPC
     stream, and under ``osw --json`` it carries the result payload.
     """
     _load_env_file()
+    # Every print below flushes: stderr is block-buffered whenever it is not a
+    # terminal (a pipe, a file, or a test runner's capture buffer), and these
+    # lines must appear before the command's own output and before any error.
     out = sys.stderr if stream is None else stream
-    described = {
-        "explicit": f"{_env_file_path} (from {ENV_FILE[0]})",
-        "discovered": f"{_env_file_path} (found from the working directory upward)",
-        "none": "none found (searched from the working directory upward)",
-        "not searched": f"not configured (set {ENV_FILE[0]} to use one)",
-    }[_env_file_origin]
-    print(f"[osw] env file       : {described}", file=out)
     _resolve_cred_file()
     if _cred_file_path:
         cred_described = {
@@ -446,7 +465,42 @@ def log_config_sources(stream=None) -> None:
                 f"ignored: no entry for domain '{_first_env(ENV_DOMAIN)}')"
             ),
         }[_cred_file_origin]
-        print(f"[osw] credential file: {_cred_file_path} {cred_described}", file=out)
+        print(
+            f"[osw] credential file: {_cred_file_path} {cred_described}",
+            file=out,
+            flush=True,
+        )
+    else:
+        username = _first_env(ENV_USERNAME)
+        password = _first_env(ENV_PASSWORD)
+        if username or password:
+            username_name = next((n for n in ENV_USERNAME if os.getenv(n)), None)
+            password_name = next((n for n in ENV_PASSWORD if os.getenv(n)), None)
+            from_env_file = (
+                username_name in _env_file_supplied
+                or password_name in _env_file_supplied
+            )
+            source = "from the env file" if from_env_file else "from the environment"
+            cred_described = f"OSW_USERNAME/OSW_PASSWORD ({source})"
+        else:
+            cred_described = (
+                "not configured (set OSW_CRED_FILEPATH, or OSW_USERNAME/OSW_PASSWORD)"
+            )
+        print(f"[osw] credentials    : {cred_described}", file=out, flush=True)
+    if verbose:
+        print(f"[osw] env file       : {_describe_env_file()}", file=out, flush=True)
+
+
+def log_env_file_source(stream=None) -> None:
+    """Print only the env-file line, for the CLI's failure path.
+
+    Does *not* call :func:`_load_env_file`, so it is safe to call after
+    :func:`load` has already raised: prints the line that
+    ``log_config_sources(verbose=False)`` suppressed, using whatever
+    ``_env_file_origin`` that earlier call already recorded.
+    """
+    out = sys.stderr if stream is None else stream
+    print(f"[osw] env file       : {_describe_env_file()}", file=out, flush=True)
 
 
 def load(strict: bool = True) -> Settings:
@@ -542,15 +596,24 @@ def load(strict: bool = True) -> Settings:
             )
         else:
             fallback_hint = ""
+        # The stdio-hang rationale only applies to the MCP server: a CLI user
+        # is not running a stdio server, so it would only confuse them.
+        stdio_hint = (
+            ""
+            if _discover_env_file
+            else (
+                " The server refuses to start without them to avoid an "
+                "interactive credential prompt that would hang the stdio "
+                "transport."
+            )
+        )
         raise RuntimeError(
             "Missing required OSW credential environment variables: "
             + ", ".join(missing)
             + ". Set them in your environment or a .env file "
             "(pointed to by OSW_ENV_FILE / OSW_MCP_ENV_FILE), or configure a "
             "credential file via OSW_CRED_FILEPATH (or its OSW_MCP_CRED_FILEPATH "
-            "/ OSL_CRED_FILEPATH aliases)." + fallback_hint + " The server "
-            "refuses to start without them to avoid an interactive credential "
-            "prompt that would hang the stdio transport."
+            "/ OSL_CRED_FILEPATH aliases)." + fallback_hint + stdio_hint
         )
 
     kwargs: dict = dict(

tests/test_cli.py

@@ -77,12 +77,17 @@ def runner():
 
 
 def _error_lines(stderr: str) -> list[str]:
-    """``stderr`` minus the ``[osw]`` config banner every command prints."""
+    """``stderr`` minus the ``[osw]`` configuration lines."""
     return [
         line for line in stderr.strip().splitlines() if not line.startswith("[osw] ")
     ]
 
 
+def _banner_lines(stderr: str) -> list[str]:
+    """The ``[osw]`` configuration lines of ``stderr``, in the order printed."""
+    return [line for line in stderr.strip().splitlines() if line.startswith("[osw] ")]
+
+
 def _fake_osw_with_page(exists=True):
     page = MagicMock()
     page.exists = exists
@@ -424,6 +429,48 @@ def test_instance_flag_unknown_iri_exits_cleanly(runner, monkeypatch, tmp_path):
     result = runner.invoke(app, ["--instance", "nope.example.org", "instance", "list"])
 
     assert result.exit_code == 3  # UnknownInstance
-    assert result.stderr.strip().startswith("UnknownInstance:")
+    assert _error_lines(result.stderr)[0].startswith("UnknownInstance:")
     assert "wiki-a.example.org" in result.stderr
     assert "Traceback" not in result.stderr
+
+
+def test_successful_command_reports_only_the_credential_source(
+    runner, configured_env, monkeypatch, tmp_path
+):
+    monkeypatch.chdir(tmp_path)  # no accounts.pwd.yaml to discover
+
+    result = runner.invoke(app, ["instance", "list"])
+
+    assert result.exit_code == 0, result.stderr
+    lines = _banner_lines(result.stderr)
+    assert len(lines) == 1
+    assert lines[0].startswith("[osw] credentials    :")
+
+
+def test_verbose_adds_the_env_file_line(runner, configured_env, monkeypatch, tmp_path):
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(app, ["--verbose", "instance", "list"])
+
+    assert result.exit_code == 0, result.stderr
+    lines = _banner_lines(result.stderr)
+    assert len(lines) == 2
+    assert lines[0].startswith("[osw] credentials    :")
+    assert lines[1].startswith("[osw] env file       :")
+
+
+def test_failing_command_reports_every_source_without_verbose(
+    runner, monkeypatch, tmp_path
+):
+    # No credentials at all, so the command fails inside the operation.
+    monkeypatch.chdir(tmp_path)
+
+    result = runner.invoke(app, ["instance", "list"])
+
+    assert result.exit_code == 1
+    lines = _banner_lines(result.stderr)
+    assert len(lines) == 2
+    assert lines[0].startswith("[osw] credentials    :")
+    assert lines[1].startswith("[osw] env file       :")
+    # The stdio-hang rationale belongs to the MCP server, not to the CLI.
+    assert "stdio transport" not in result.stderr

tests/test_service_config.py

@@ -819,6 +819,108 @@ def test_log_config_sources_reports_cred_file_from_environment(
     assert "from the OSW_CRED_FILEPATH environment variable" in captured.err
 
 
+def test_log_config_sources_verbose_false_prints_only_credential_line(
+    monkeypatch, capsys
+):
+    monkeypatch.setenv("OSW_USERNAME", "alice")
+    monkeypatch.setenv("OSW_PASSWORD", "secret")
+
+    config.log_config_sources(verbose=False)
+
+    captured = capsys.readouterr()
+    lines = captured.err.splitlines()
+    assert len(lines) == 1
+    assert lines[0].startswith("[osw] credentials    :")
+
+
+def test_log_config_sources_verbose_true_prints_both_lines_credential_first(
+    monkeypatch, capsys
+):
+    monkeypatch.setenv("OSW_USERNAME", "alice")
+    monkeypatch.setenv("OSW_PASSWORD", "secret")
+
+    config.log_config_sources()
+
+    captured = capsys.readouterr()
+    lines = captured.err.splitlines()
+    assert len(lines) == 2
+    assert lines[0].startswith("[osw] credentials    :")
+    assert lines[1].startswith("[osw] env file       :")
+
+
+def test_log_config_sources_reports_username_password_from_env_file(
+    monkeypatch, tmp_path, capsys
+):
+    env = tmp_path / "creds.env"
+    env.write_text("OSW_USERNAME=alice\nOSW_PASSWORD=secret\n", encoding="utf-8")
+    monkeypatch.setenv("OSW_ENV_FILE", str(env))
+
+    config.log_config_sources()
+
+    captured = capsys.readouterr()
+    assert "OSW_USERNAME/OSW_PASSWORD (from the env file)" in captured.err
+
+
+def test_log_config_sources_reports_username_password_from_environment(
+    monkeypatch, capsys
+):
+    monkeypatch.setenv("OSW_USERNAME", "alice")
+    monkeypatch.setenv("OSW_PASSWORD", "secret")
+
+    config.log_config_sources()
+
+    captured = capsys.readouterr()
+    assert "OSW_USERNAME/OSW_PASSWORD (from the environment)" in captured.err
+
+
+def test_log_config_sources_reports_credentials_not_configured(monkeypatch, capsys):
+    config.log_config_sources()
+
+    captured = capsys.readouterr()
+    assert (
+        "not configured (set OSW_CRED_FILEPATH, or OSW_USERNAME/OSW_PASSWORD)"
+        in captured.err
+    )
+
+
+def test_log_env_file_source_prints_only_env_file_line(monkeypatch, tmp_path, capsys):
+    env = tmp_path / "creds.env"
+    env.write_text("", encoding="utf-8")
+    monkeypatch.setenv("OSW_ENV_FILE", str(env))
+    config._load_env_file()
+
+    config.log_env_file_source()
+
+    captured = capsys.readouterr()
+    lines = captured.err.splitlines()
+    assert len(lines) == 1
+    assert lines[0].startswith("[osw] env file       :")
+    assert str(env) in lines[0]
+
+
+def test_missing_credentials_message_has_stdio_hint_when_discovery_disabled(
+    monkeypatch,
+):
+    with pytest.raises(RuntimeError) as exc:
+        config.load()
+
+    assert "stdio transport" in str(exc.value)
+
+
+def test_missing_credentials_message_omits_stdio_hint_when_discovery_enabled(
+    monkeypatch, tmp_path
+):
+    # chdir away from the repo root: it has its own accounts.pwd.yaml for local
+    # dev, which discovery would otherwise pick up and satisfy the check with.
+    monkeypatch.chdir(tmp_path)
+    config.set_env_file_discovery(True)
+
+    with pytest.raises(RuntimeError) as exc:
+        config.load()
+
+    assert "stdio transport" not in str(exc.value)
+
+
 # -- Settings validation (pydantic) ------------------------------------------