pyclaudecli 1.0.2__tar.gz → 1.0.3__tar.gz

{pyclaudecli-1.0.2 → pyclaudecli-1.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyclaudecli
-Version: 1.0.2
+Version: 1.0.3
 Summary: Python library wrapping the Claude Code CLI: prompts, background agents, auth, MCP, plugins, and more
 Author-email: Suriya Ravichandran <suriyaravichandran@itrendsolution.com>
 License: MIT
@@ -41,6 +41,7 @@ It's a thin wrapper, not a reimplementation — every call runs the real `claude
 - [Command-line usage](#command-line-usage)
 - [Errors](#errors)
 - [`build_flags`](#build_flags)
+- [Security notes](#security-notes)
 - [Every method, with an example](#every-method-with-an-example)
 - [Development](#development)
 - [License](#license)
@@ -81,6 +82,15 @@ claude = ClaudeCLI(
 )
 ```
 
+`env` is merged **over** the current environment, so `PATH`, `HOME` and the rest still
+reach the CLI — passing one API key doesn't cost you the ability to find the binary or
+its credentials. Pass `replace_env=True` if you really want the child to start from a
+clean slate:
+
+```python
+claude = ClaudeCLI(env={"PATH": "/usr/bin", "HOME": "/tmp/sandbox"}, replace_env=True)
+```
+
 ## Authentication
 
 `claude` handles auth itself, so `pyclaudecli` just drives it. You have two options.
@@ -410,13 +420,49 @@ gateway.terminate()
 
 See `ClaudeCLI`'s docstrings for the exact CLI flags behind each method — it covers every top-level `claude` command (`auth`, `mcp`, `plugin`, `project`, `agents`/background sessions, `auto-mode`, `doctor`, `update`, `install`, `import`, `ultrareview`, `gateway`) plus the main prompt flags. Anything not exposed as a named parameter can still be passed through via each method's `extra_flags` dict.
 
+## Security notes
+
+A few things the wrapper does on your behalf, worth knowing if you're feeding it input
+from anywhere but your own code:
+
+**Prompts can't smuggle in CLI flags.** `prompt()`, `prompt_stream()`, `start_background()`
+and the `pyclaudecli` command put `--` between the options and your text, so a prompt that
+starts with a dash is text, not a flag. Without it, user-supplied input like
+`--dangerously-skip-permissions` or `--settings /tmp/evil.json` would be parsed by the CLI:
+
+```python
+claude.prompt("--version")   # asks Claude about "--version"; does not run the flag
+```
+
+Flags you actually want still go through named parameters or `extra_flags`. Note this
+protection covers the prompt text — if you interpolate untrusted input into a *flag value*
+(`model=`, `settings=`, `add_dir=`), validate it yourself.
+
+**Errors don't spill credentials.** `ClaudeCLIError.args`/`.cmd` and the exception message
+are redacted before they're raised, so MCP auth headers, injected `--env` values, tokens
+inside an `mcp add-json` payload and anything shaped like `sk-ant-…`, `Bearer …` or
+`password=…` come back as `<redacted>`. Flag names survive so the command is still
+recognisable, and long values are truncated. Tracebacks and log aggregators get the
+redacted form; `exc.stdout`/`exc.stderr` still hold the raw output for local debugging.
+
+**Login codes are handled as single-use secrets.** `auth_login()` writes exactly one line
+to the CLI's stdin — a code containing a newline can't inject extra input — and drops the
+code and the captured output from memory once it's submitted. The child process and its
+pipes are always cleaned up, including when your `code_provider` raises.
+
+Two things it deliberately does *not* do: it never runs a shell (every call is an argv
+list, so there's no shell-injection surface), and it doesn't manage credentials itself —
+auth lives with the `claude` CLI and your environment. Remember the argv of a running
+process is visible to other users on the same machine via `ps`, so prefer env vars over
+flags for anything sensitive.
+
 ## Development
 
 ```bash
 git clone https://github.com/Suriya-Ravichandran/pyclaudecli.git
 cd pyclaudecli
 pip install -e .
-pytest
+pytest          # offline; does not invoke the claude binary
 ```
 
 ## License

{pyclaudecli-1.0.2 → pyclaudecli-1.0.3}/README.md

@@ -18,6 +18,7 @@ It's a thin wrapper, not a reimplementation — every call runs the real `claude
 - [Command-line usage](#command-line-usage)
 - [Errors](#errors)
 - [`build_flags`](#build_flags)
+- [Security notes](#security-notes)
 - [Every method, with an example](#every-method-with-an-example)
 - [Development](#development)
 - [License](#license)
@@ -58,6 +59,15 @@ claude = ClaudeCLI(
 )
 ```
 
+`env` is merged **over** the current environment, so `PATH`, `HOME` and the rest still
+reach the CLI — passing one API key doesn't cost you the ability to find the binary or
+its credentials. Pass `replace_env=True` if you really want the child to start from a
+clean slate:
+
+```python
+claude = ClaudeCLI(env={"PATH": "/usr/bin", "HOME": "/tmp/sandbox"}, replace_env=True)
+```
+
 ## Authentication
 
 `claude` handles auth itself, so `pyclaudecli` just drives it. You have two options.
@@ -387,13 +397,49 @@ gateway.terminate()
 
 See `ClaudeCLI`'s docstrings for the exact CLI flags behind each method — it covers every top-level `claude` command (`auth`, `mcp`, `plugin`, `project`, `agents`/background sessions, `auto-mode`, `doctor`, `update`, `install`, `import`, `ultrareview`, `gateway`) plus the main prompt flags. Anything not exposed as a named parameter can still be passed through via each method's `extra_flags` dict.
 
+## Security notes
+
+A few things the wrapper does on your behalf, worth knowing if you're feeding it input
+from anywhere but your own code:
+
+**Prompts can't smuggle in CLI flags.** `prompt()`, `prompt_stream()`, `start_background()`
+and the `pyclaudecli` command put `--` between the options and your text, so a prompt that
+starts with a dash is text, not a flag. Without it, user-supplied input like
+`--dangerously-skip-permissions` or `--settings /tmp/evil.json` would be parsed by the CLI:
+
+```python
+claude.prompt("--version")   # asks Claude about "--version"; does not run the flag
+```
+
+Flags you actually want still go through named parameters or `extra_flags`. Note this
+protection covers the prompt text — if you interpolate untrusted input into a *flag value*
+(`model=`, `settings=`, `add_dir=`), validate it yourself.
+
+**Errors don't spill credentials.** `ClaudeCLIError.args`/`.cmd` and the exception message
+are redacted before they're raised, so MCP auth headers, injected `--env` values, tokens
+inside an `mcp add-json` payload and anything shaped like `sk-ant-…`, `Bearer …` or
+`password=…` come back as `<redacted>`. Flag names survive so the command is still
+recognisable, and long values are truncated. Tracebacks and log aggregators get the
+redacted form; `exc.stdout`/`exc.stderr` still hold the raw output for local debugging.
+
+**Login codes are handled as single-use secrets.** `auth_login()` writes exactly one line
+to the CLI's stdin — a code containing a newline can't inject extra input — and drops the
+code and the captured output from memory once it's submitted. The child process and its
+pipes are always cleaned up, including when your `code_provider` raises.
+
+Two things it deliberately does *not* do: it never runs a shell (every call is an argv
+list, so there's no shell-injection surface), and it doesn't manage credentials itself —
+auth lives with the `claude` CLI and your environment. Remember the argv of a running
+process is visible to other users on the same machine via `ps`, so prefer env vars over
+flags for anything sensitive.
+
 ## Development
 
 ```bash
 git clone https://github.com/Suriya-Ravichandran/pyclaudecli.git
 cd pyclaudecli
 pip install -e .
-pytest
+pytest          # offline; does not invoke the claude binary
 ```
 
 ## License

{pyclaudecli-1.0.2 → pyclaudecli-1.0.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyclaudecli"
-version = "1.0.2"
+version = "1.0.3"
 description = "Python library wrapping the Claude Code CLI: prompts, background agents, auth, MCP, plugins, and more"
 readme = "README.md"
 requires-python = ">=3.8"

{pyclaudecli-1.0.2 → pyclaudecli-1.0.3}/src/pyclaudecli/__init__.py

@@ -3,7 +3,7 @@
 from .client import ClaudeCLI, build_flags
 from .exceptions import ClaudeCLIError, ClaudeNotFoundError, ClaudeTimeoutError
 
-__version__ = "1.0.2"
+__version__ = "1.0.3"
 
 __all__ = [
     "ClaudeCLI",

{pyclaudecli-1.0.2 → pyclaudecli-1.0.3}/src/pyclaudecli/__main__.py

@@ -45,7 +45,9 @@ def main(argv: Optional[List[str]] = None) -> int:
     model, prompt = parse_args(argv)
     client = ClaudeCLI()
     try:
-        result = client.run(["--print", "--model", model, prompt], check=False)
+        # `--` keeps a prompt that starts with a dash from being parsed as
+        # flags by the CLI (this parser passes unknown args through as text).
+        result = client.run(["--print", "--model", model, "--", prompt], check=False)
     except Exception as exc:  # ClaudeNotFoundError, etc.
         print(str(exc), file=sys.stderr)
         return 1

pyclaudecli-1.0.3/src/pyclaudecli/_process.py

@@ -0,0 +1,318 @@
+"""Low-level process plumbing shared by ClaudeCLI's methods."""
+
+from __future__ import annotations
+
+import os
+import re
+import select
+import subprocess
+import time
+from dataclasses import dataclass
+from typing import Callable, Iterator, Optional, Sequence
+
+from .exceptions import ClaudeCLIError, ClaudeNotFoundError, ClaudeTimeoutError
+
+_URL_PATTERN = re.compile(r"https://\S+")
+
+# Flags whose values are credentials (MCP auth headers, injected env vars).
+_SECRET_FLAGS = frozenset({"--header", "--env", "--client-id", "--client-secret"})
+
+# Credential shapes that can turn up anywhere in an argv, including inside the
+# JSON blob passed to `mcp add-json`.
+_SECRET_VALUE_PATTERN = re.compile(
+    r"""(
+        sk-ant-[\w-]+                      # Anthropic API keys
+      | pypi-[\w-]+                        # PyPI tokens
+      | gh[pousr]_[A-Za-z0-9]+             # GitHub tokens
+      | [Bb]earer\s+\S+                    # bearer tokens
+      | (?i:[\w.-]*(?:token|secret|key|password|passwd|auth)[\w.-]*)
+        \s*["\s]*[=:]\s*"?[^\s"',}]+       # anything token/secret/key-ish = value
+    )""",
+    re.VERBOSE,
+)
+
+_REDACTED = "<redacted>"
+_MAX_ARG_LEN = 120
+_MAX_DETAIL_LEN = 2000
+_MAX_LOGIN_BUFFER = 64 * 1024
+
+
+def redact_arg(value: str, limit: Optional[int] = _MAX_ARG_LEN) -> str:
+    """Masks credential-looking substrings, and truncates very long values."""
+    cleaned = _SECRET_VALUE_PATTERN.sub(_REDACTED, str(value))
+    if limit is not None and len(cleaned) > limit:
+        cleaned = cleaned[:limit] + "…"
+    return cleaned
+
+
+def redact_command(command: Sequence[str]) -> list:
+    """Returns a copy of an argv safe to put in an error message or a log.
+
+    Values of credential-bearing flags are replaced wholesale; everything else
+    is scanned for embedded secrets and truncated. Flag *names* survive, so the
+    command stays recognisable when debugging.
+    """
+    safe = []
+    masking = False
+    for token in command:
+        token = str(token)
+        if token.startswith("-"):
+            masking = token in _SECRET_FLAGS
+            safe.append(token)
+            continue
+        safe.append(_REDACTED if masking else redact_arg(token))
+    return safe
+
+
+def format_command(command: Sequence[str]) -> str:
+    """A redacted, shell-ish rendering of an argv for error messages."""
+    return " ".join(redact_command(command))
+
+
+@dataclass
+class CommandResult:
+    args: list
+    returncode: int
+    stdout: str
+    stderr: str
+
+    @property
+    def ok(self) -> bool:
+        return self.returncode == 0
+
+
+def run(
+    binary: str,
+    args: Sequence[str],
+    *,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+    input_text: Optional[str] = None,
+    timeout: Optional[float] = None,
+    check: bool = True,
+) -> CommandResult:
+    command = [binary, *args]
+    try:
+        completed = subprocess.run(
+            command,
+            cwd=cwd,
+            env=env,
+            input=input_text,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+        )
+    except FileNotFoundError as exc:
+        raise ClaudeNotFoundError(
+            f"'{binary}' was not found on PATH. Is Claude Code installed?",
+            cmd=redact_command(command),
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        stdout = exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or "")
+        stderr = exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or "")
+        raise ClaudeTimeoutError(
+            f"'{format_command(command)}' did not finish within {timeout}s",
+            cmd=redact_command(command),
+            stdout=stdout,
+            stderr=stderr,
+        ) from exc
+
+    result = CommandResult(command, completed.returncode, completed.stdout, completed.stderr)
+    if check and not result.ok:
+        detail = redact_arg((result.stderr or result.stdout or "").strip(), limit=_MAX_DETAIL_LEN)
+        raise ClaudeCLIError(
+            f"'{format_command(command)}' exited with {result.returncode}: {detail}",
+            returncode=result.returncode,
+            stdout=result.stdout,
+            stderr=result.stderr,
+            cmd=redact_command(command),
+        )
+    return result
+
+
+def stream_lines(
+    binary: str,
+    args: Sequence[str],
+    *,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+) -> Iterator[str]:
+    """Runs a command and yields decoded stdout lines as they arrive."""
+    command = [binary, *args]
+    try:
+        proc = subprocess.Popen(
+            command,
+            cwd=cwd,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+    except FileNotFoundError as exc:
+        raise ClaudeNotFoundError(
+            f"'{binary}' was not found on PATH. Is Claude Code installed?",
+            cmd=redact_command(command),
+        ) from exc
+
+    assert proc.stdout is not None
+    try:
+        for line in proc.stdout:
+            yield line.rstrip("\n")
+    finally:
+        proc.stdout.close()
+        returncode = proc.wait()
+        if returncode != 0:
+            raise ClaudeCLIError(
+                f"'{format_command(command)}' exited with {returncode}",
+                returncode=returncode,
+                cmd=redact_command(command),
+            )
+
+
+def run_interactive(
+    binary: str,
+    args: Sequence[str],
+    *,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+) -> int:
+    """Runs a command with stdio inherited from the current process.
+
+    For subcommands that need a real terminal (attach, setup-token, an
+    interactive mcp/import picker) rather than captured output.
+    """
+    command = [binary, *args]
+    try:
+        return subprocess.call(command, cwd=cwd, env=env)
+    except FileNotFoundError as exc:
+        raise ClaudeNotFoundError(
+            f"'{binary}' was not found on PATH. Is Claude Code installed?",
+            cmd=redact_command(command),
+        ) from exc
+
+
+def oauth_login(
+    binary: str,
+    args: Sequence[str],
+    *,
+    cwd: Optional[str] = None,
+    env: Optional[dict] = None,
+    code: Optional[str] = None,
+    code_provider: Optional[Callable[[str], str]] = None,
+    on_output: Optional[Callable[[str], None]] = None,
+    prompt_marker: str = "Paste code here",
+    timeout: float = 180,
+) -> int:
+    """Drives an interactive OAuth login (`claude auth login` / `mcp login`).
+
+    Streams the child's output (forwarding it to `on_output`, if given) until
+    it prints its "paste the code" prompt, then writes back `code` — or
+    whatever `code_provider(url)` returns, where `url` is the login URL
+    found in the output so far. Falls back to `input()` if neither is given.
+    Returns the child's exit code.
+    """
+    command = [binary, *args]
+    try:
+        proc = subprocess.Popen(
+            command,
+            cwd=cwd,
+            env=env,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
+    except FileNotFoundError as exc:
+        raise ClaudeNotFoundError(
+            f"'{binary}' was not found on PATH. Is Claude Code installed?",
+            cmd=redact_command(command),
+        ) from exc
+
+    assert proc.stdout is not None and proc.stdin is not None
+    fd = proc.stdout.fileno()
+    buffer = ""
+    url: Optional[str] = None
+    deadline = time.time() + timeout
+
+    try:
+        while time.time() < deadline and proc.poll() is None:
+            ready, _, _ = select.select([fd], [], [], 0.5)
+            if not ready:
+                continue
+
+            chunk = os.read(fd, 4096).decode(errors="replace")
+            if not chunk:
+                break
+
+            buffer += chunk
+            # A login that never reaches its prompt must not grow the buffer
+            # without bound; the marker and URL both live near the tail.
+            if len(buffer) > _MAX_LOGIN_BUFFER:
+                buffer = buffer[-_MAX_LOGIN_BUFFER:]
+            if on_output:
+                on_output(chunk)
+
+            if url is None:
+                match = _URL_PATTERN.search(buffer)
+                if match:
+                    url = match.group(0)
+
+            if prompt_marker in buffer:
+                if code is not None:
+                    entered_code = code
+                elif code_provider is not None:
+                    entered_code = code_provider(url or "")
+                else:
+                    entered_code = input("\nPaste the code from the browser here: ")
+
+                # Only ever hand the child a single line: a code carrying a
+                # newline would otherwise write extra lines into its stdin.
+                entered_code = str(entered_code or "").splitlines()
+                entered_code = entered_code[0].strip() if entered_code else ""
+
+                proc.stdin.write(entered_code + "\n")
+                proc.stdin.flush()
+                proc.stdin.close()
+                # Drop the code and the captured output rather than holding
+                # them in memory for the rest of the call.
+                entered_code = ""
+                buffer = ""
+                break
+        else:
+            if proc.poll() is None:
+                raise ClaudeTimeoutError(
+                    f"'{format_command(command)}' did not produce a login prompt within {timeout}s",
+                    cmd=redact_command(command),
+                )
+
+        drain_deadline = time.time() + 30
+        while proc.poll() is None and time.time() < drain_deadline:
+            ready, _, _ = select.select([fd], [], [], 0.5)
+            if ready:
+                chunk = os.read(fd, 4096).decode(errors="replace")
+                if not chunk:
+                    break
+                if on_output:
+                    on_output(chunk)
+
+        if proc.poll() is None:
+            raise ClaudeTimeoutError(
+                f"'{format_command(command)}' did not finish after the code was submitted",
+                cmd=redact_command(command),
+            )
+
+        return proc.returncode
+    finally:
+        # Never leave a half-driven login (or its pipes) behind, whatever
+        # went wrong — including an exception raised by `code_provider`.
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait()
+        for stream in (proc.stdin, proc.stdout):
+            try:
+                if stream is not None and not stream.closed:
+                    stream.close()
+            except (OSError, ValueError):
+                pass

{pyclaudecli-1.0.2 → pyclaudecli-1.0.3}/src/pyclaudecli/client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import os
 import re
 from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence, Union
 
@@ -58,14 +59,33 @@ class ClaudeCLI:
         cwd: Optional[str] = None,
         env: Optional[dict] = None,
         timeout: Optional[float] = None,
+        replace_env: bool = False,
     ) -> None:
         self.binary = binary
         self.cwd = cwd
         self.env = env
         self.timeout = timeout
+        self.replace_env = replace_env
 
     # -- internals -----------------------------------------------------
 
+    def _env(self) -> Optional[dict]:
+        """The environment to hand the child process.
+
+        `env` is merged *over* the current environment by default. Replacing it
+        outright would drop PATH (so the binary may not resolve, or a different
+        one could), HOME and XDG_* (so `claude` would look for its credentials
+        and settings somewhere else), which is rarely what a caller passing a
+        single API key intends. Pass `replace_env=True` for a clean slate.
+        """
+        if self.env is None:
+            return None
+        if self.replace_env:
+            return {str(k): str(v) for k, v in self.env.items()}
+        merged = os.environ.copy()
+        merged.update({str(k): str(v) for k, v in self.env.items()})
+        return merged
+
     def run(
         self,
         args: Sequence[str],
@@ -79,7 +99,7 @@ class ClaudeCLI:
             self.binary,
             args,
             cwd=self.cwd,
-            env=self.env,
+            env=self._env(),
             input_text=input_text,
             timeout=timeout if timeout is not None else self.timeout,
             check=check,
@@ -93,17 +113,18 @@ class ClaudeCLI:
         try:
             return json.loads(result.stdout)
         except json.JSONDecodeError as exc:
+            command = [self.binary, *args]
             raise ClaudeCLIError(
-                f"Expected JSON from `{self.binary} {' '.join(args)}`, "
-                f"got: {result.stdout[:200]!r}",
+                f"Expected JSON from `{_process.format_command(command)}`, "
+                f"got: {_process.redact_arg(result.stdout[:200])!r}",
                 returncode=result.returncode,
                 stdout=result.stdout,
                 stderr=result.stderr,
-                cmd=[self.binary, *args],
+                cmd=_process.redact_command(command),
             ) from exc
 
     def _interactive(self, args: Sequence[str]) -> int:
-        return _process.run_interactive(self.binary, args, cwd=self.cwd, env=self.env)
+        return _process.run_interactive(self.binary, args, cwd=self.cwd, env=self._env())
 
     # -- version / health ------------------------------------------------
 
@@ -197,7 +218,10 @@ class ClaudeCLI:
         args = ["--print"] + build_flags(options)
         if continue_session:
             args.append("--continue")
-        args.append(text)
+        # `--` ends option parsing: without it a prompt that happens to start
+        # with a dash is read as CLI flags, so untrusted text could turn on
+        # things like --dangerously-skip-permissions.
+        args += ["--", text]
 
         result = self.run(args, input_text=input_text, timeout=timeout)
         if output_format == "json":
@@ -217,8 +241,8 @@ class ClaudeCLI:
         extra_flags["verbose"] = True  # required by the CLI for --print + stream-json
 
         options = {k: v for k, v in extra_flags.items() if v is not None and v is not False}
-        args = ["--print"] + build_flags(options) + [text]
-        for line in _process.stream_lines(self.binary, args, cwd=self.cwd, env=self.env):
+        args = ["--print"] + build_flags(options) + ["--", text]
+        for line in _process.stream_lines(self.binary, args, cwd=self.cwd, env=self._env()):
             line = line.strip()
             if line:
                 yield json.loads(line)
@@ -237,7 +261,7 @@ class ClaudeCLI:
         """`claude --bg <task>`; returns the short session id it prints."""
         options = dict(model=model, name=name, resume=resume)
         options.update(extra_flags or {})
-        args = ["--bg"] + build_flags(options) + [task]
+        args = ["--bg"] + build_flags(options) + ["--", task]
         output = self._text(args)
         match = re.search(r"backgrounded\W*([0-9a-fA-F]+)", output)
         if not match:
@@ -314,7 +338,7 @@ class ClaudeCLI:
             self.binary,
             args,
             cwd=self.cwd,
-            env=self.env,
+            env=self._env(),
             code=code,
             code_provider=code_provider,
             on_output=on_output or (lambda chunk: print(chunk, end="", flush=True)),
@@ -578,4 +602,4 @@ class ClaudeCLI:
         import subprocess
 
         args = [self.binary, "gateway", *build_flags({"config": config})]
-        return subprocess.Popen(args, cwd=self.cwd, env=self.env)
+        return subprocess.Popen(args, cwd=self.cwd, env=self._env())

pyclaudecli-1.0.3/tests/test_security.py

@@ -0,0 +1,159 @@
+"""Regression tests for the hardening in 1.0.3 — all offline, no `claude` needed."""
+
+import os
+
+import pytest
+
+from pyclaudecli import ClaudeCLI, build_flags
+from pyclaudecli._process import format_command, redact_arg, redact_command
+
+
+class RecordingCLI(ClaudeCLI):
+    """Captures the argv a method would run instead of executing it."""
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        self.calls = []
+
+    def run(self, args, **kwargs):
+        self.calls.append(list(args))
+        raise AssertionError("not executed")
+
+
+def argv_for(method, *args, **kwargs):
+    client = RecordingCLI()
+    with pytest.raises(AssertionError):
+        getattr(client, method)(*args, **kwargs)
+    return client.calls[-1]
+
+
+# -- argument injection ---------------------------------------------------
+
+def test_prompt_separates_options_from_text():
+    argv = argv_for("prompt", "--version")
+    assert argv[-2:] == ["--", "--version"]
+
+
+def test_prompt_separator_comes_after_continue():
+    argv = argv_for("prompt", "-h", continue_session=True)
+    assert argv.index("--continue") < argv.index("--")
+
+
+@pytest.mark.parametrize(
+    "hostile",
+    ["--version", "--dangerously-skip-permissions", "-p", "--settings=/tmp/evil.json"],
+)
+def test_hostile_prompts_stay_positional(hostile):
+    argv = argv_for("prompt", hostile)
+    assert argv[-1] == hostile
+    assert argv[argv.index("--") + 1] == hostile
+
+
+def test_start_background_separates_task():
+    argv = argv_for("start_background", "--version")
+    assert argv[-2:] == ["--", "--version"]
+
+
+def test_module_entrypoint_separates_prompt():
+    from pyclaudecli.__main__ import main
+
+    captured = {}
+
+    class Fake(ClaudeCLI):
+        def run(self, args, **kwargs):
+            captured["argv"] = list(args)
+            raise SystemExit(0)
+
+    import pyclaudecli.__main__ as entry
+
+    original = entry.ClaudeCLI
+    entry.ClaudeCLI = Fake
+    try:
+        with pytest.raises(SystemExit):
+            main(["--version"])
+    finally:
+        entry.ClaudeCLI = original
+
+    assert captured["argv"][-2:] == ["--", "--version"]
+
+
+# -- secret redaction -----------------------------------------------------
+
+def test_redacts_values_of_credential_flags():
+    argv = ["claude", "mcp", "add", "--header", "Authorization: Bearer tok123", "s", "https://x"]
+    safe = redact_command(argv)
+    assert "tok123" not in " ".join(safe)
+    assert "--header" in safe  # flag names stay, for debuggability
+
+
+def test_redacts_env_flag_values():
+    safe = format_command(["claude", "mcp", "add", "--env", "API_KEY=supersecret", "s", "cmd"])
+    assert "supersecret" not in safe
+
+
+@pytest.mark.parametrize(
+    "secret",
+    [
+        "sk-ant-api03-abcdef123456",
+        "pypi-AgEIcHlwaS5vcmcXYZ",
+        "ghp_abcdefghijklmnop",
+        '{"token": "abcdef123456"}',
+        "password=hunter2",
+    ],
+)
+def test_redacts_credential_shapes_anywhere(secret):
+    assert secret not in redact_arg(secret)
+    assert "<redacted>" in redact_arg(secret)
+
+
+def test_add_json_payload_is_redacted():
+    payload = '{"type":"http","url":"https://x","headers":{"Authorization":"Bearer sk-ant-abc123"}}'
+    assert "sk-ant-abc123" not in format_command(["claude", "mcp", "add-json", "s", payload])
+
+
+def test_long_arguments_are_truncated():
+    assert len(redact_arg("a" * 5000)) < 200
+
+
+def test_ordinary_arguments_survive():
+    argv = ["claude", "--print", "--model", "haiku", "--", "Summarize this repo"]
+    assert redact_command(argv) == argv
+
+
+# -- environment handling -------------------------------------------------
+
+def test_env_is_merged_over_os_environ_by_default():
+    env = ClaudeCLI(env={"ANTHROPIC_API_KEY": "sk-ant-x"})._env()
+    assert env["ANTHROPIC_API_KEY"] == "sk-ant-x"
+    assert env.get("PATH") == os.environ.get("PATH")
+
+
+def test_replace_env_gives_a_clean_slate():
+    env = ClaudeCLI(env={"ANTHROPIC_API_KEY": "sk-ant-x"}, replace_env=True)._env()
+    assert env == {"ANTHROPIC_API_KEY": "sk-ant-x"}
+
+
+def test_no_env_means_inherit():
+    assert ClaudeCLI()._env() is None
+
+
+# -- unchanged behaviour --------------------------------------------------
+
+def test_build_flags_still_builds_flags():
+    assert build_flags({"model": "haiku", "verbose": True, "quiet": False, "add_dir": ["a", "b"]}) == [
+        "--model", "haiku", "--verbose", "--add-dir", "a", "b",
+    ]
+
+
+def test_cli_stderr_is_redacted_in_error_messages():
+    from pyclaudecli._process import redact_arg
+
+    stderr = 'invalid header "Authorization: Bearer sk-ant-leak123"'
+    assert "sk-ant-leak123" not in redact_arg(stderr, limit=2000)
+
+
+def test_detail_redaction_keeps_long_errors_readable():
+    from pyclaudecli._process import redact_arg
+
+    long_error = "error: " + ("context " * 100)
+    assert len(redact_arg(long_error, limit=2000)) > 500

pyclaudecli-1.0.3/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.8"
+
+[[package]]
+name = "pyclaudecli"
+version = "1.0.3"
+source = { editable = "." }

pyclaudecli-1.0.2/src/pyclaudecli/_process.py

@@ -1,241 +0,0 @@
-"""Low-level process plumbing shared by ClaudeCLI's methods."""
-
-from __future__ import annotations
-
-import os
-import re
-import select
-import subprocess
-import time
-from dataclasses import dataclass
-from typing import Callable, Iterator, Optional, Sequence
-
-from .exceptions import ClaudeCLIError, ClaudeNotFoundError, ClaudeTimeoutError
-
-_URL_PATTERN = re.compile(r"https://\S+")
-
-
-@dataclass
-class CommandResult:
-    args: list
-    returncode: int
-    stdout: str
-    stderr: str
-
-    @property
-    def ok(self) -> bool:
-        return self.returncode == 0
-
-
-def run(
-    binary: str,
-    args: Sequence[str],
-    *,
-    cwd: Optional[str] = None,
-    env: Optional[dict] = None,
-    input_text: Optional[str] = None,
-    timeout: Optional[float] = None,
-    check: bool = True,
-) -> CommandResult:
-    command = [binary, *args]
-    try:
-        completed = subprocess.run(
-            command,
-            cwd=cwd,
-            env=env,
-            input=input_text,
-            capture_output=True,
-            text=True,
-            timeout=timeout,
-        )
-    except FileNotFoundError as exc:
-        raise ClaudeNotFoundError(
-            f"'{binary}' was not found on PATH. Is Claude Code installed?",
-            cmd=command,
-        ) from exc
-    except subprocess.TimeoutExpired as exc:
-        stdout = exc.stdout.decode() if isinstance(exc.stdout, bytes) else (exc.stdout or "")
-        stderr = exc.stderr.decode() if isinstance(exc.stderr, bytes) else (exc.stderr or "")
-        raise ClaudeTimeoutError(
-            f"'{' '.join(command)}' did not finish within {timeout}s",
-            cmd=command,
-            stdout=stdout,
-            stderr=stderr,
-        ) from exc
-
-    result = CommandResult(command, completed.returncode, completed.stdout, completed.stderr)
-    if check and not result.ok:
-        detail = (result.stderr or result.stdout or "").strip()
-        raise ClaudeCLIError(
-            f"'{' '.join(command)}' exited with {result.returncode}: {detail}",
-            returncode=result.returncode,
-            stdout=result.stdout,
-            stderr=result.stderr,
-            cmd=command,
-        )
-    return result
-
-
-def stream_lines(
-    binary: str,
-    args: Sequence[str],
-    *,
-    cwd: Optional[str] = None,
-    env: Optional[dict] = None,
-) -> Iterator[str]:
-    """Runs a command and yields decoded stdout lines as they arrive."""
-    command = [binary, *args]
-    try:
-        proc = subprocess.Popen(
-            command,
-            cwd=cwd,
-            env=env,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            text=True,
-            bufsize=1,
-        )
-    except FileNotFoundError as exc:
-        raise ClaudeNotFoundError(
-            f"'{binary}' was not found on PATH. Is Claude Code installed?",
-            cmd=command,
-        ) from exc
-
-    assert proc.stdout is not None
-    try:
-        for line in proc.stdout:
-            yield line.rstrip("\n")
-    finally:
-        proc.stdout.close()
-        returncode = proc.wait()
-        if returncode != 0:
-            raise ClaudeCLIError(
-                f"'{' '.join(command)}' exited with {returncode}",
-                returncode=returncode,
-                cmd=command,
-            )
-
-
-def run_interactive(
-    binary: str,
-    args: Sequence[str],
-    *,
-    cwd: Optional[str] = None,
-    env: Optional[dict] = None,
-) -> int:
-    """Runs a command with stdio inherited from the current process.
-
-    For subcommands that need a real terminal (attach, setup-token, an
-    interactive mcp/import picker) rather than captured output.
-    """
-    command = [binary, *args]
-    try:
-        return subprocess.call(command, cwd=cwd, env=env)
-    except FileNotFoundError as exc:
-        raise ClaudeNotFoundError(
-            f"'{binary}' was not found on PATH. Is Claude Code installed?",
-            cmd=command,
-        ) from exc
-
-
-def oauth_login(
-    binary: str,
-    args: Sequence[str],
-    *,
-    cwd: Optional[str] = None,
-    env: Optional[dict] = None,
-    code: Optional[str] = None,
-    code_provider: Optional[Callable[[str], str]] = None,
-    on_output: Optional[Callable[[str], None]] = None,
-    prompt_marker: str = "Paste code here",
-    timeout: float = 180,
-) -> int:
-    """Drives an interactive OAuth login (`claude auth login` / `mcp login`).
-
-    Streams the child's output (forwarding it to `on_output`, if given) until
-    it prints its "paste the code" prompt, then writes back `code` — or
-    whatever `code_provider(url)` returns, where `url` is the login URL
-    found in the output so far. Falls back to `input()` if neither is given.
-    Returns the child's exit code.
-    """
-    command = [binary, *args]
-    try:
-        proc = subprocess.Popen(
-            command,
-            cwd=cwd,
-            env=env,
-            stdin=subprocess.PIPE,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.STDOUT,
-            text=True,
-            bufsize=1,
-        )
-    except FileNotFoundError as exc:
-        raise ClaudeNotFoundError(
-            f"'{binary}' was not found on PATH. Is Claude Code installed?",
-            cmd=command,
-        ) from exc
-
-    assert proc.stdout is not None and proc.stdin is not None
-    fd = proc.stdout.fileno()
-    buffer = ""
-    url: Optional[str] = None
-    deadline = time.time() + timeout
-
-    while time.time() < deadline and proc.poll() is None:
-        ready, _, _ = select.select([fd], [], [], 0.5)
-        if not ready:
-            continue
-
-        chunk = os.read(fd, 4096).decode(errors="replace")
-        if not chunk:
-            break
-
-        buffer += chunk
-        if on_output:
-            on_output(chunk)
-
-        if url is None:
-            match = _URL_PATTERN.search(buffer)
-            if match:
-                url = match.group(0)
-
-        if prompt_marker in buffer:
-            if code is not None:
-                entered_code = code
-            elif code_provider is not None:
-                entered_code = code_provider(url or "")
-            else:
-                entered_code = input("\nPaste the code from the browser here: ").strip()
-
-            proc.stdin.write(entered_code + "\n")
-            proc.stdin.flush()
-            proc.stdin.close()
-            buffer = ""
-            break
-    else:
-        if proc.poll() is None:
-            proc.kill()
-            raise ClaudeTimeoutError(
-                f"'{' '.join(command)}' did not produce a login prompt within {timeout}s",
-                cmd=command,
-            )
-
-    drain_deadline = time.time() + 30
-    while proc.poll() is None and time.time() < drain_deadline:
-        ready, _, _ = select.select([fd], [], [], 0.5)
-        if ready:
-            chunk = os.read(fd, 4096).decode(errors="replace")
-            if not chunk:
-                break
-            if on_output:
-                on_output(chunk)
-
-    if proc.poll() is None:
-        proc.kill()
-        raise ClaudeTimeoutError(
-            f"'{' '.join(command)}' did not finish after the code was submitted",
-            cmd=command,
-        )
-
-    return proc.returncode

pyclaudecli-1.0.2/tests/test_usage.py

@@ -1,28 +0,0 @@
-from pyclaudecli import ClaudeCLI, ClaudeCLIError
-
-claude = ClaudeCLI()  # add cwd=..., env=... if needed
-
-# Plain text answer
-claude.prompt("Explain this function", model="haiku")
-
-# Structured result: cost, session_id, etc.
-result = claude.prompt_json("2+2?", model="haiku")
-result["result"], result["total_cost_usd"]
-
-# Live token/event stream
-for event in claude.prompt_stream("Write a haiku"):
-    print(event["type"])
-
-# Background agent (long-running task)
-sid = claude.start_background("Refactor auth module", model="sonnet")
-claude.list_agents()
-claude.logs(sid, strip_ansi=True)
-claude.stop(sid); claude.rm(sid)
-
-# Auth
-claude.auth_status()
-claude.auth_login()   # prints URL, prompts you for the pasted code
-
-# MCP / plugins
-claude.mcp_add("sentry", "https://mcp.sentry.dev/mcp", transport="http")
-claude.plugin_install("some-plugin", yes=True)