agent-cli 0.90.0__tar.gz → 0.91.0__tar.gz

{agent_cli-0.90.0 → agent_cli-0.91.0}/.pre-commit-config.yaml

@@ -11,13 +11,13 @@ repos:
       - id: end-of-file-fixer
       - id: mixed-line-ending
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.15.11"
+    rev: "v0.15.12"
     hooks:
       - id: ruff
         args: ["--fix"]
       - id: ruff-format
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: "v1.20.1"
+    rev: "v1.20.2"
     hooks:
       - id: mypy
         additional_dependencies: ["types-PyYAML"]

{agent_cli-0.90.0 → agent_cli-0.91.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-cli
-Version: 0.90.0
+Version: 0.91.0
 Summary: A suite of AI-powered command-line tools for text correction, audio transcription, and voice assistance.
 Project-URL: Homepage, https://github.com/basnijholt/agent-cli
 Author-email: Bas Nijholt <bas@nijho.lt>
@@ -263,6 +263,7 @@ The setup scripts automatically install:
   - [Installation Commands](#installation-commands)
     - [Installing Optional Extras](#installing-optional-extras)
   - [Configuration](#configuration)
+    - [Environment variable overrides](#environment-variable-overrides)
     - [Managing Configuration](#managing-configuration)
     - [Provider Defaults](#provider-defaults)
   - [`autocorrect`](#autocorrect)
@@ -571,15 +572,36 @@ agent-cli install-extras rag memory vad
 
 ### Configuration
 
-All `agent-cli` commands can be configured using a TOML file. The configuration file is searched for in the following locations, in order:
+All `agent-cli` commands can be configured using a TOML file.
+The configuration file is searched for in the following locations, in order:
 
-1.  `./agent-cli-config.toml` (in the current directory)
-2.  `~/.config/agent-cli/config.toml`
+1.  CLI flag (`--config` on agent commands, `--path` on `agent-cli config ...`)
+2.  `$AGENT_CLI_CONFIG_HOME/config.toml` if set
+3.  `./agent-cli-config.toml` (in the current directory)
+4.  `$XDG_CONFIG_HOME/agent-cli/config.toml` if `XDG_CONFIG_HOME` is set and non-empty, otherwise `~/.config/agent-cli/config.toml`
 
 You can also specify a path to a configuration file using the `--config` option, e.g., `agent-cli transcribe --config /path/to/your/config.toml`.
 
 Command-line options always take precedence over settings in the configuration file.
 
+#### Environment variable overrides
+
+Use `AGENT_CLI_CONFIG_HOME` to redirect the user-level config to a directory of your choice:
+
+```bash
+# use a project-scoped config
+AGENT_CLI_CONFIG_HOME=./.agent-cli agent-cli chat ...
+```
+
+Use `XDG_CONFIG_HOME` to follow XDG-style config placement when no `AGENT_CLI_CONFIG_HOME` is set:
+
+```bash
+# follow XDG (e.g. inside a sandbox or container)
+XDG_CONFIG_HOME=/workspace/.config agent-cli chat ...
+```
+
+Config paths are resolved when `agent-cli` starts, so set these variables before invoking the command.
+
 #### Managing Configuration
 
 Use the `config` command to manage your configuration files:
@@ -620,11 +642,20 @@ agent-cli config edit
 
  Config files are TOML format and searched in order:
 
-  1 ./agent-cli-config.toml (project-local)
-  2 ~/.config/agent-cli/config.toml (user default)
+  1 $AGENT_CLI_CONFIG_HOME/config.toml (if set)
+  2 ./agent-cli-config.toml (project-local)
+  3 $XDG_CONFIG_HOME/agent-cli/config.toml (if set)
+  4 ~/.config/agent-cli/config.toml (user default)
+
+ Settings in [defaults] apply globally.
+
+ Use [chat] or [transcribe] for command-specific overrides.
+
+ CLI arguments override config file settings.
+
+ Set env vars before startup.
 
- Settings in [defaults] apply to all commands. Override per-command with sections like
- [chat] or [transcribe]. CLI arguments override config file settings.
+ Use $AGENT_CLI_CONFIG_HOME or $XDG_CONFIG_HOME to change config path.
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │

{agent_cli-0.90.0 → agent_cli-0.91.0}/README.md

@@ -158,6 +158,7 @@ The setup scripts automatically install:
   - [Installation Commands](#installation-commands)
     - [Installing Optional Extras](#installing-optional-extras)
   - [Configuration](#configuration)
+    - [Environment variable overrides](#environment-variable-overrides)
     - [Managing Configuration](#managing-configuration)
     - [Provider Defaults](#provider-defaults)
   - [`autocorrect`](#autocorrect)
@@ -466,15 +467,36 @@ agent-cli install-extras rag memory vad
 
 ### Configuration
 
-All `agent-cli` commands can be configured using a TOML file. The configuration file is searched for in the following locations, in order:
+All `agent-cli` commands can be configured using a TOML file.
+The configuration file is searched for in the following locations, in order:
 
-1.  `./agent-cli-config.toml` (in the current directory)
-2.  `~/.config/agent-cli/config.toml`
+1.  CLI flag (`--config` on agent commands, `--path` on `agent-cli config ...`)
+2.  `$AGENT_CLI_CONFIG_HOME/config.toml` if set
+3.  `./agent-cli-config.toml` (in the current directory)
+4.  `$XDG_CONFIG_HOME/agent-cli/config.toml` if `XDG_CONFIG_HOME` is set and non-empty, otherwise `~/.config/agent-cli/config.toml`
 
 You can also specify a path to a configuration file using the `--config` option, e.g., `agent-cli transcribe --config /path/to/your/config.toml`.
 
 Command-line options always take precedence over settings in the configuration file.
 
+#### Environment variable overrides
+
+Use `AGENT_CLI_CONFIG_HOME` to redirect the user-level config to a directory of your choice:
+
+```bash
+# use a project-scoped config
+AGENT_CLI_CONFIG_HOME=./.agent-cli agent-cli chat ...
+```
+
+Use `XDG_CONFIG_HOME` to follow XDG-style config placement when no `AGENT_CLI_CONFIG_HOME` is set:
+
+```bash
+# follow XDG (e.g. inside a sandbox or container)
+XDG_CONFIG_HOME=/workspace/.config agent-cli chat ...
+```
+
+Config paths are resolved when `agent-cli` starts, so set these variables before invoking the command.
+
 #### Managing Configuration
 
 Use the `config` command to manage your configuration files:
@@ -515,11 +537,20 @@ agent-cli config edit
 
  Config files are TOML format and searched in order:
 
-  1 ./agent-cli-config.toml (project-local)
-  2 ~/.config/agent-cli/config.toml (user default)
+  1 $AGENT_CLI_CONFIG_HOME/config.toml (if set)
+  2 ./agent-cli-config.toml (project-local)
+  3 $XDG_CONFIG_HOME/agent-cli/config.toml (if set)
+  4 ~/.config/agent-cli/config.toml (user default)
+
+ Settings in [defaults] apply globally.
+
+ Use [chat] or [transcribe] for command-specific overrides.
+
+ CLI arguments override config file settings.
+
+ Set env vars before startup.
 
- Settings in [defaults] apply to all commands. Override per-command with sections like
- [chat] or [transcribe]. CLI arguments override config file settings.
+ Use $AGENT_CLI_CONFIG_HOME or $XDG_CONFIG_HOME to change config path.
 
 ╭─ Options ──────────────────────────────────────────────────────────────────────────────╮
 │ --help  -h        Show this message and exit.                                          │

{agent_cli-0.90.0 → agent_cli-0.91.0}/agent_cli/config.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import os
 import tomllib
 from pathlib import Path
 from typing import Any, Literal
@@ -10,12 +11,31 @@ from pydantic import BaseModel, field_validator
 
 from agent_cli.core.utils import console
 
-USER_CONFIG_PATH = Path.home() / ".config" / "agent-cli" / "config.toml"
+PROJECT_CONFIG_PATH = Path("agent-cli-config.toml")
 
-CONFIG_PATHS = [
-    Path("agent-cli-config.toml"),
-    USER_CONFIG_PATH,
-]
+
+def _user_config_path() -> Path:
+    """Resolve the user-level config path with env-var overrides.
+
+    Precedence: AGENT_CLI_CONFIG_HOME > XDG_CONFIG_HOME > ~/.config.
+    Resolved once at import; set env vars before importing agent_cli.config.
+    """
+    home = os.environ.get("AGENT_CLI_CONFIG_HOME")
+    if home:
+        return Path(home).expanduser() / "config.toml"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    if xdg:
+        return Path(xdg).expanduser() / "agent-cli" / "config.toml"
+    return Path.home() / ".config" / "agent-cli" / "config.toml"
+
+
+USER_CONFIG_PATH = _user_config_path()
+
+CONFIG_PATHS = (
+    [USER_CONFIG_PATH, PROJECT_CONFIG_PATH]
+    if os.environ.get("AGENT_CLI_CONFIG_HOME")
+    else [PROJECT_CONFIG_PATH, USER_CONFIG_PATH]
+)
 
 
 def _normalize_provider_value(field: str, value: str) -> str:

{agent_cli-0.90.0 → agent_cli-0.91.0}/agent_cli/config_cmd.py

@@ -24,12 +24,20 @@ config_app = typer.Typer(
 
 Config files are TOML format and searched in order:
 
-1. `./agent-cli-config.toml` (project-local)
-2. `~/.config/agent-cli/config.toml` (user default)
+1. `$AGENT_CLI_CONFIG_HOME/config.toml` (if set)
+2. `./agent-cli-config.toml` (project-local)
+3. `$XDG_CONFIG_HOME/agent-cli/config.toml` (if set)
+4. `~/.config/agent-cli/config.toml` (user default)
 
-Settings in `[defaults]` apply to all commands. Override per-command
-with sections like `[chat]` or `[transcribe]`. CLI arguments override
-config file settings.
+Settings in `[defaults]` apply globally.
+
+Use `[chat]` or `[transcribe]` for command-specific overrides.
+
+CLI arguments override config file settings.
+
+Set env vars before startup.
+
+Use `$AGENT_CLI_CONFIG_HOME` or `$XDG_CONFIG_HOME` to change config path.
 """,
     add_completion=True,
     rich_markup_mode="markdown",
@@ -56,7 +64,7 @@ CONFIG_PATH_INIT_OPTION: Path | None = typer.Option(
     None,
     "--path",
     "-p",
-    help="Where to create the config file (default: `~/.config/agent-cli/config.toml`).",
+    help="Where to create the config file (default: resolved user config path).",
 )
 FORCE_OPTION: bool = typer.Option(
     False,  # noqa: FBT003

{agent_cli-0.90.0 → agent_cli-0.91.0}/docs/architecture/index.md

@@ -105,7 +105,7 @@ Configuration is loaded from multiple sources with the following precedence:
 
 1. **Command-line arguments** (highest priority)
 2. **Environment variables** (`OPENAI_API_KEY`, etc.)
-3. **Config file** (`./agent-cli-config.toml` or `~/.config/agent-cli/config.toml`)
+3. **Config file** (`--config`/`--path`, `$AGENT_CLI_CONFIG_HOME/config.toml`, `./agent-cli-config.toml`, `$XDG_CONFIG_HOME/agent-cli/config.toml`, or `~/.config/agent-cli/config.toml`)
 4. **Default values** (lowest priority)
 
 ## Process Management

{agent_cli-0.90.0 → agent_cli-0.91.0}/docs/commands/config.md

@@ -15,6 +15,7 @@ agent-cli config [OPTIONS] COMMAND [ARGS]...
 ## Description
 
 The `config` command helps you create, edit, and inspect your configuration file.
+Set `AGENT_CLI_CONFIG_HOME` or `XDG_CONFIG_HOME` before startup to change the user-level config path.
 
 ## Commands
 
@@ -44,7 +45,7 @@ agent-cli config init [OPTIONS]
 
 | Option | Default | Description |
 |--------|---------|-------------|
-| `--path, -p` | - | Where to create the config file (default: `~/.config/agent-cli/config.toml`). |
+| `--path, -p` | - | Where to create the config file (default: resolved user config path). |
 | `--force, -f` | `false` | Overwrite existing config without prompting for confirmation. |
 
 

{agent_cli-0.90.0 → agent_cli-0.91.0}/docs/configuration.md

@@ -4,10 +4,13 @@ icon: lucide/settings
 
 # Configuration
 
-All `agent-cli` commands can be configured using a TOML file. The configuration file is searched for in the following locations, in order:
+All `agent-cli` commands can be configured using a TOML file.
+The configuration file is searched for in the following locations, in order:
 
-1. `./agent-cli-config.toml` (in the current directory)
-2. `~/.config/agent-cli/config.toml`
+1. CLI flag (`--config` on agent commands, `--path` on `agent-cli config ...`)
+2. `$AGENT_CLI_CONFIG_HOME/config.toml` if set
+3. `./agent-cli-config.toml` (in the current directory)
+4. `$XDG_CONFIG_HOME/agent-cli/config.toml` if `XDG_CONFIG_HOME` is set and non-empty, otherwise `~/.config/agent-cli/config.toml`
 
 You can also specify a path to a configuration file using the `--config` option:
 
@@ -17,8 +20,25 @@ agent-cli transcribe --config /path/to/your/config.toml
 
 Command-line options always take precedence over settings in the configuration file.
 
-Option keys can be written with dashes (matching CLI flags) or underscores; both
-are accepted.
+Option keys can be written with dashes (matching CLI flags) or underscores; both are accepted.
+
+## Environment variable overrides
+
+Use `AGENT_CLI_CONFIG_HOME` to redirect the user-level config to a directory of your choice:
+
+```bash
+# use a project-scoped config
+AGENT_CLI_CONFIG_HOME=./.agent-cli agent-cli chat ...
+```
+
+Use `XDG_CONFIG_HOME` to follow XDG-style config placement when no `AGENT_CLI_CONFIG_HOME` is set:
+
+```bash
+# follow XDG (e.g. inside a sandbox or container)
+XDG_CONFIG_HOME=/workspace/.config agent-cli chat ...
+```
+
+Config paths are resolved when `agent-cli` starts, so set these variables before invoking the command.
 
 ## Managing Configuration
 

{agent_cli-0.90.0 → agent_cli-0.91.0}/tests/test_config.py

@@ -2,8 +2,11 @@
 
 from __future__ import annotations
 
+import os
 import re
-from typing import TYPE_CHECKING
+import subprocess
+import sys
+from pathlib import Path
 from unittest.mock import MagicMock
 
 import pytest
@@ -11,6 +14,7 @@ from click import Command
 from typer import Context
 from typer.testing import CliRunner
 
+import agent_cli.config as config_module
 from agent_cli.cli import app, set_config_defaults
 from agent_cli.config import (
     GeminiASR,
@@ -21,9 +25,6 @@ from agent_cli.config import (
     normalize_provider_defaults,
 )
 
-if TYPE_CHECKING:
-    from pathlib import Path
-
 runner = CliRunner(env={"NO_COLOR": "1", "TERM": "dumb"})
 
 
@@ -212,6 +213,108 @@ ANTHROPIC_MODEL = "claude-opus-4-6"
     assert "dev.branch_name_mode" not in config
 
 
+def test_user_config_path_defaults_to_home_config(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """Unset env vars use ~/.config/agent-cli/config.toml."""
+    home = tmp_path / "home"
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
+    monkeypatch.delenv("AGENT_CLI_CONFIG_HOME", raising=False)
+    monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
+
+    assert config_module._user_config_path() == home / ".config" / "agent-cli" / "config.toml"
+
+
+def test_user_config_path_uses_xdg_config_home(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """XDG_CONFIG_HOME redirects the user config below agent-cli/."""
+    xdg_home = tmp_path / "xdg"
+    monkeypatch.delenv("AGENT_CLI_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg_home))
+
+    assert config_module._user_config_path() == xdg_home / "agent-cli" / "config.toml"
+
+
+def test_user_config_path_agent_cli_config_home_wins(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """AGENT_CLI_CONFIG_HOME takes precedence and is treated as a directory."""
+    agent_config_home = tmp_path / "agent-home"
+    monkeypatch.setenv("AGENT_CLI_CONFIG_HOME", str(agent_config_home))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+
+    assert config_module._user_config_path() == agent_config_home / "config.toml"
+
+
+def test_user_config_path_empty_xdg_falls_back_to_home(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """Empty XDG_CONFIG_HOME is treated the same as being unset."""
+    home = tmp_path / "home"
+    monkeypatch.setenv("HOME", str(home))
+    monkeypatch.setenv("USERPROFILE", str(home))
+    monkeypatch.delenv("AGENT_CLI_CONFIG_HOME", raising=False)
+    monkeypatch.setenv("XDG_CONFIG_HOME", "")
+
+    assert config_module._user_config_path() == home / ".config" / "agent-cli" / "config.toml"
+
+
+def test_explicit_config_path_wins_over_env_vars(
+    monkeypatch: pytest.MonkeyPatch,
+    tmp_path: Path,
+) -> None:
+    """An explicit CLI config path still wins over env-var config homes."""
+    explicit = tmp_path / "explicit.toml"
+    monkeypatch.setenv("AGENT_CLI_CONFIG_HOME", str(tmp_path / "agent-home"))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+
+    assert config_module._config_path(str(explicit)) == explicit.resolve()
+
+
+def test_config_init_writes_to_agent_cli_config_home(tmp_path: Path) -> None:
+    """Config init writes to USER_CONFIG_PATH resolved once at import time."""
+    repo_root = Path(__file__).resolve().parents[1]
+    config_home = tmp_path / "agent-home"
+    env = os.environ.copy()
+    env["AGENT_CLI_CONFIG_HOME"] = str(config_home)
+    env.pop("XDG_CONFIG_HOME", None)
+    env["PYTHONPATH"] = (
+        f"{repo_root}{os.pathsep}{env['PYTHONPATH']}" if env.get("PYTHONPATH") else str(repo_root)
+    )
+
+    script = """
+from typer.testing import CliRunner
+from agent_cli.cli import app
+
+runner = CliRunner(env={"NO_COLOR": "1", "TERM": "dumb"})
+result = runner.invoke(app, ["config", "init", "--force"])
+print(result.stdout, end="")
+if result.exception:
+    raise result.exception
+raise SystemExit(result.exit_code)
+"""
+    result = subprocess.run(
+        [sys.executable, "-c", script],
+        cwd=tmp_path,
+        env=env,
+        text=True,
+        capture_output=True,
+        timeout=10,
+        check=False,
+    )
+
+    assert result.returncode == 0, result.stdout + result.stderr
+    config_path = config_home / "config.toml"
+    assert config_path.exists()
+    assert "[defaults]" in config_path.read_text(encoding="utf-8")
+
+
 def test_provider_alias_normalization(config_file: Path) -> None:
     """Ensure deprecated provider names are normalized."""
     config = load_config(str(config_file))