pyclaudecli 0.1.0__py3-none-any.whl

pyclaudecli/__init__.py

@@ -0,0 +1,14 @@
+"""pyclaudecli: a Python library that wraps the `claude` CLI (Claude Code)."""
+
+from .client import ClaudeCLI, build_flags
+from .exceptions import ClaudeCLIError, ClaudeNotFoundError, ClaudeTimeoutError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ClaudeCLI",
+    "build_flags",
+    "ClaudeCLIError",
+    "ClaudeNotFoundError",
+    "ClaudeTimeoutError",
+]

pyclaudecli/__main__.py

@@ -0,0 +1,61 @@
+"""`python -m pyclaudecli` — a minimal CLI wrapper for quick scripting.
+
+For anything beyond a one-off prompt, use `pyclaudecli.ClaudeCLI` directly.
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import List, Optional, Tuple
+
+from .client import ClaudeCLI
+
+
+def parse_args(argv: List[str]) -> Tuple[str, str]:
+    model = "haiku"
+    prompt_parts = []
+    index = 0
+
+    while index < len(argv):
+        arg = argv[index]
+
+        if arg in {"--model", "-m"}:
+            if index + 1 >= len(argv):
+                raise SystemExit("Missing value for --model.")
+            model = argv[index + 1]
+            index += 2
+            continue
+
+        if arg.startswith("--model="):
+            model = arg.split("=", 1)[1]
+            index += 1
+            continue
+
+        prompt_parts.append(arg)
+        index += 1
+
+    prompt = " ".join(prompt_parts).strip() if prompt_parts else "Hello, Claude!"
+    return model, prompt
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+
+    model, prompt = parse_args(argv)
+    client = ClaudeCLI()
+    try:
+        result = client.run(["--print", "--model", model, prompt], check=False)
+    except Exception as exc:  # ClaudeNotFoundError, etc.
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    if result.stdout:
+        print(result.stdout, end="")
+    if result.stderr:
+        print(result.stderr, file=sys.stderr, end="")
+    return result.returncode
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

pyclaudecli/_process.py

@@ -0,0 +1,241 @@
+"""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/client.py

@@ -0,0 +1,581 @@
+"""ClaudeCLI: a Python wrapper around every `claude` CLI command."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any, Callable, Dict, Iterator, List, Optional, Sequence, Union
+
+from . import _process
+from .exceptions import ClaudeCLIError
+
+_ANSI_PATTERN = re.compile(r"\x1b\[[0-9;]*[a-zA-Z]|\x1b\][^\x07]*\x07")
+
+
+def _kebab(name: str) -> str:
+    return "--" + name.replace("_", "-")
+
+
+def build_flags(options: Dict[str, Any]) -> List[str]:
+    """Converts a {python_name: value} dict into CLI flags.
+
+    None/False -> omitted. True -> bare flag. list/tuple -> the flag once,
+    followed by each value (matches commander.js variadic `<x...>` options).
+    Anything else -> the flag followed by str(value).
+    """
+    flags: List[str] = []
+    for key, value in options.items():
+        if value is None or value is False:
+            continue
+        flag = _kebab(key)
+        if value is True:
+            flags.append(flag)
+        elif isinstance(value, (list, tuple)):
+            if not value:
+                continue
+            flags.append(flag)
+            flags.extend(str(v) for v in value)
+        else:
+            flags.append(flag)
+            flags.append(str(value))
+    return flags
+
+
+class ClaudeCLI:
+    """Wraps the `claude` CLI (Claude Code) for programmatic use.
+
+    Every method shells out to the real `claude` binary, so whatever is
+    installed and authenticated on this machine is what runs. Methods that
+    capture output raise `ClaudeCLIError` (or a subclass) on a non-zero exit;
+    pass `check=False` to a raw call via `.run()` if you'd rather inspect the
+    result yourself.
+    """
+
+    def __init__(
+        self,
+        binary: str = "claude",
+        *,
+        cwd: Optional[str] = None,
+        env: Optional[dict] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        self.binary = binary
+        self.cwd = cwd
+        self.env = env
+        self.timeout = timeout
+
+    # -- internals -----------------------------------------------------
+
+    def run(
+        self,
+        args: Sequence[str],
+        *,
+        input_text: Optional[str] = None,
+        timeout: Optional[float] = None,
+        check: bool = True,
+    ) -> _process.CommandResult:
+        """Runs `claude <args>` and returns the captured result."""
+        return _process.run(
+            self.binary,
+            args,
+            cwd=self.cwd,
+            env=self.env,
+            input_text=input_text,
+            timeout=timeout if timeout is not None else self.timeout,
+            check=check,
+        )
+
+    def _text(self, args: Sequence[str], **kwargs: Any) -> str:
+        return self.run(args, **kwargs).stdout
+
+    def _json(self, args: Sequence[str], **kwargs: Any) -> Any:
+        result = self.run(args, **kwargs)
+        try:
+            return json.loads(result.stdout)
+        except json.JSONDecodeError as exc:
+            raise ClaudeCLIError(
+                f"Expected JSON from `{self.binary} {' '.join(args)}`, "
+                f"got: {result.stdout[:200]!r}",
+                returncode=result.returncode,
+                stdout=result.stdout,
+                stderr=result.stderr,
+                cmd=[self.binary, *args],
+            ) from exc
+
+    def _interactive(self, args: Sequence[str]) -> int:
+        return _process.run_interactive(self.binary, args, cwd=self.cwd, env=self.env)
+
+    # -- version / health ------------------------------------------------
+
+    def version(self) -> str:
+        """`claude --version`"""
+        return self._text(["--version"]).strip()
+
+    def doctor(self) -> str:
+        """`claude doctor` — health-checks the local installation."""
+        return self._text(["doctor"])
+
+    def update(self) -> str:
+        """`claude update` — checks for and installs updates."""
+        return self._text(["update"])
+
+    def install(self, target: Optional[str] = None, *, force: bool = False) -> str:
+        """`claude install [target]` (target: stable, latest, or a version)."""
+        args = ["install"] + ([target] if target else []) + build_flags({"force": force})
+        return self._text(args)
+
+    # -- prompting (non-interactive / --print) ----------------------------
+
+    def prompt(
+        self,
+        text: str,
+        *,
+        model: Optional[str] = None,
+        output_format: Optional[str] = None,
+        system_prompt: Optional[str] = None,
+        append_system_prompt: Optional[str] = None,
+        allowed_tools: Optional[Sequence[str]] = None,
+        disallowed_tools: Optional[Sequence[str]] = None,
+        tools: Optional[Sequence[str]] = None,
+        add_dir: Optional[Sequence[str]] = None,
+        permission_mode: Optional[str] = None,
+        permission_prompts: Optional[str] = None,
+        mcp_config: Optional[Sequence[str]] = None,
+        settings: Optional[str] = None,
+        session_id: Optional[str] = None,
+        resume: Optional[str] = None,
+        continue_session: bool = False,
+        fork_session: bool = False,
+        effort: Optional[str] = None,
+        fallback_model: Optional[str] = None,
+        max_budget_usd: Optional[float] = None,
+        json_schema: Optional[str] = None,
+        betas: Optional[Sequence[str]] = None,
+        no_session_persistence: bool = False,
+        dangerously_skip_permissions: bool = False,
+        restricted: bool = False,
+        input_text: Optional[str] = None,
+        timeout: Optional[float] = None,
+        extra_flags: Optional[Dict[str, Any]] = None,
+    ) -> Union[str, dict]:
+        """Runs a single non-interactive prompt (`claude --print ...`).
+
+        Returns the response text, or the parsed JSON result object when
+        `output_format="json"`. Anything not exposed as a named parameter
+        (e.g. `--cloud`, `--worktree`, `--file`) can be passed via
+        `extra_flags={"worktree": True}`.
+        """
+        options = dict(
+            model=model,
+            output_format=output_format,
+            system_prompt=system_prompt,
+            append_system_prompt=append_system_prompt,
+            allowed_tools=allowed_tools,
+            disallowed_tools=disallowed_tools,
+            tools=tools,
+            add_dir=add_dir,
+            permission_mode=permission_mode,
+            permission_prompts=permission_prompts,
+            mcp_config=mcp_config,
+            settings=settings,
+            session_id=session_id,
+            resume=resume,
+            fork_session=fork_session,
+            effort=effort,
+            fallback_model=fallback_model,
+            max_budget_usd=max_budget_usd,
+            json_schema=json_schema,
+            betas=betas,
+            no_session_persistence=no_session_persistence,
+            dangerously_skip_permissions=dangerously_skip_permissions,
+            restricted=restricted,
+        )
+        options.update(extra_flags or {})
+        if options.get("output_format") == "stream-json":
+            options["verbose"] = True  # required by the CLI for --print + stream-json
+
+        args = ["--print"] + build_flags(options)
+        if continue_session:
+            args.append("--continue")
+        args.append(text)
+
+        result = self.run(args, input_text=input_text, timeout=timeout)
+        if output_format == "json":
+            return json.loads(result.stdout)
+        return result.stdout
+
+    def prompt_json(self, text: str, **kwargs: Any) -> dict:
+        """`prompt()` forced to `--output-format json`; returns the parsed dict."""
+        kwargs["output_format"] = "json"
+        return self.prompt(text, **kwargs)  # type: ignore[return-value]
+
+    def prompt_stream(self, text: str, **kwargs: Any) -> Iterator[dict]:
+        """`prompt()` with `--output-format stream-json`; yields each event dict."""
+        extra_flags = dict(kwargs.pop("extra_flags", None) or {})
+        extra_flags.update(kwargs)
+        extra_flags["output_format"] = "stream-json"
+        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):
+            line = line.strip()
+            if line:
+                yield json.loads(line)
+
+    # -- background sessions ("agents") -----------------------------------
+
+    def start_background(
+        self,
+        task: str,
+        *,
+        model: Optional[str] = None,
+        name: Optional[str] = None,
+        resume: Optional[str] = None,
+        extra_flags: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """`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]
+        output = self._text(args)
+        match = re.search(r"backgrounded\W*([0-9a-fA-F]+)", output)
+        if not match:
+            raise ClaudeCLIError(
+                f"Could not find a session id in `claude --bg` output: {output!r}",
+                stdout=output,
+                cmd=[self.binary, *args],
+            )
+        return match.group(1)
+
+    def list_agents(self, *, all: bool = False, cwd: Optional[str] = None) -> List[dict]:
+        """`claude agents --json`; lists interactive and background sessions."""
+        args = ["agents", "--json"] + build_flags({"all": all, "cwd": cwd})
+        return self._json(args)
+
+    def attach(self, session_id: str) -> int:
+        """`claude attach <id>` — opens a background session in this terminal.
+
+        Requires a real TTY (stdio is inherited, not captured).
+        """
+        return self._interactive(["attach", session_id])
+
+    def logs(self, session_id: str, *, strip_ansi: bool = False) -> str:
+        """`claude logs <id>` — a raw terminal snapshot of recent output.
+
+        Pass `strip_ansi=True` for a best-effort plain-text version.
+        """
+        text = self._text(["logs", session_id])
+        return _ANSI_PATTERN.sub("", text) if strip_ansi else text
+
+    def stop(self, session_id: str) -> str:
+        """`claude stop <id>` — stops a background session (keeps its state)."""
+        return self._text(["stop", session_id])
+
+    def rm(self, session_id: str) -> str:
+        """`claude rm <id>` — deletes a (stopped) background session."""
+        return self._text(["rm", session_id])
+
+    def respawn(self, session_id: Optional[str] = None, *, all: bool = False) -> str:
+        """`claude respawn [id]` / `claude respawn --all`."""
+        args = ["respawn"] + ([session_id] if session_id else []) + build_flags({"all": all})
+        return self._text(args)
+
+    # -- auth --------------------------------------------------------------
+
+    def auth_status(self, *, as_json: bool = True) -> Union[dict, str]:
+        """`claude auth status`."""
+        if as_json:
+            return self._json(["auth", "status", "--json"])
+        return self._text(["auth", "status", "--text"])
+
+    def auth_login(
+        self,
+        *,
+        email: Optional[str] = None,
+        console: bool = False,
+        sso: bool = False,
+        code: Optional[str] = None,
+        code_provider: Optional[Callable[[str], str]] = None,
+        on_output: Optional[Callable[[str], None]] = None,
+        timeout: float = 180,
+    ) -> int:
+        """Drives `claude auth login` end to end.
+
+        Prints (via `on_output`, or stdout if not given) the sign-in URL for
+        you to open and complete in a browser, then forwards the resulting
+        code back to the CLI. Pass `code` to supply it non-interactively, or
+        `code_provider(url)` to fetch it programmatically (e.g. from your own
+        browser-automation step); otherwise it's read from stdin.
+        """
+        args = ["auth", "login"]
+        args += build_flags({"console": console, "sso": sso, "email": email})
+        return _process.oauth_login(
+            self.binary,
+            args,
+            cwd=self.cwd,
+            env=self.env,
+            code=code,
+            code_provider=code_provider,
+            on_output=on_output or (lambda chunk: print(chunk, end="", flush=True)),
+            timeout=timeout,
+        )
+
+    def auth_logout(self) -> str:
+        """`claude auth logout`."""
+        return self._text(["auth", "logout"])
+
+    def setup_token(self) -> int:
+        """`claude setup-token` — sets up a long-lived auth token.
+
+        Interactive (may involve a browser step); stdio is inherited.
+        """
+        return self._interactive(["setup-token"])
+
+    # -- MCP servers ---------------------------------------------------------
+
+    def mcp_list(self) -> str:
+        """`claude mcp list`."""
+        return self._text(["mcp", "list"])
+
+    def mcp_get(self, name: str) -> str:
+        """`claude mcp get <name>`."""
+        return self._text(["mcp", "get", name])
+
+    def mcp_add(
+        self,
+        name: str,
+        command_or_url: str,
+        *args: str,
+        transport: Optional[str] = None,
+        header: Optional[Sequence[str]] = None,
+        env: Optional[Sequence[str]] = None,
+        scope: Optional[str] = None,
+        client_id: Optional[str] = None,
+        client_secret: bool = False,
+        callback_port: Optional[int] = None,
+    ) -> str:
+        """`claude mcp add <name> <commandOrUrl> [args...]`."""
+        options = build_flags(
+            dict(
+                transport=transport,
+                header=header,
+                env=env,
+                scope=scope,
+                client_id=client_id,
+                client_secret=client_secret,
+                callback_port=callback_port,
+            )
+        )
+        return self._text(["mcp", "add", *options, name, command_or_url, *args])
+
+    def mcp_add_json(
+        self,
+        name: str,
+        config: Union[str, dict],
+        *,
+        scope: Optional[str] = None,
+        client_secret: bool = False,
+    ) -> str:
+        """`claude mcp add-json <name> <json>`. `config` may be a dict or JSON string."""
+        payload = json.dumps(config) if isinstance(config, dict) else config
+        options = build_flags({"scope": scope, "client_secret": client_secret})
+        return self._text(["mcp", "add-json", *options, name, payload])
+
+    def mcp_add_from_claude_desktop(self, *, scope: Optional[str] = None) -> str:
+        """`claude mcp add-from-claude-desktop` (Mac and WSL only)."""
+        return self._text(["mcp", "add-from-claude-desktop", *build_flags({"scope": scope})])
+
+    def mcp_remove(self, name: str, *, scope: Optional[str] = None) -> str:
+        """`claude mcp remove <name>`."""
+        return self._text(["mcp", "remove", *build_flags({"scope": scope}), name])
+
+    def mcp_login(self, name: str, *, no_browser: bool = False) -> int:
+        """`claude mcp login <name>` — interactive OAuth for an MCP server."""
+        return self._interactive(["mcp", "login", *build_flags({"no_browser": no_browser}), name])
+
+    def mcp_logout(self, name: str) -> str:
+        """`claude mcp logout <name>`."""
+        return self._text(["mcp", "logout", name])
+
+    def mcp_reset_project_choices(self) -> str:
+        """`claude mcp reset-project-choices`."""
+        return self._text(["mcp", "reset-project-choices"])
+
+    # -- plugins ---------------------------------------------------------------
+
+    def plugin_list(self, *, as_json: bool = False) -> Union[str, list]:
+        """`claude plugin list`."""
+        args = ["plugin", "list"] + build_flags({"json": as_json})
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_install(
+        self,
+        plugin: str,
+        *,
+        scope: Optional[str] = None,
+        yes: bool = False,
+        config: Optional[Sequence[str]] = None,
+        accept_command: Optional[str] = None,
+        as_json: bool = False,
+    ) -> Union[str, dict]:
+        """`claude plugin install <plugin>` (use `plugin@marketplace` to pin one)."""
+        options = build_flags(
+            dict(scope=scope, yes=yes, config=config, accept_command=accept_command, json=as_json)
+        )
+        args = ["plugin", "install", *options, plugin]
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_uninstall(
+        self,
+        plugin: str,
+        *,
+        scope: Optional[str] = None,
+        keep_data: bool = False,
+        prune: bool = False,
+        yes: bool = False,
+        as_json: bool = False,
+    ) -> Union[str, dict]:
+        """`claude plugin uninstall <plugin>`."""
+        options = build_flags(
+            dict(scope=scope, keep_data=keep_data, prune=prune, yes=yes, json=as_json)
+        )
+        args = ["plugin", "uninstall", *options, plugin]
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_enable(self, plugin: str, *, scope: Optional[str] = None, as_json: bool = False) -> Union[str, dict]:
+        """`claude plugin enable <plugin>`."""
+        args = ["plugin", "enable", *build_flags({"scope": scope, "json": as_json}), plugin]
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_disable(
+        self,
+        plugin: Optional[str] = None,
+        *,
+        all: bool = False,
+        scope: Optional[str] = None,
+        as_json: bool = False,
+    ) -> Union[str, dict]:
+        """`claude plugin disable [plugin]` (or `all=True` for every plugin)."""
+        options = build_flags({"all": all, "scope": scope, "json": as_json})
+        args = ["plugin", "disable", *options] + ([plugin] if plugin else [])
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_update(
+        self,
+        plugin: str,
+        *,
+        scope: Optional[str] = None,
+        yes: bool = False,
+        accept_command: Optional[str] = None,
+        as_json: bool = False,
+    ) -> Union[str, dict]:
+        """`claude plugin update <plugin>`."""
+        options = build_flags(dict(scope=scope, yes=yes, accept_command=accept_command, json=as_json))
+        args = ["plugin", "update", *options, plugin]
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_details(self, name: str) -> str:
+        """`claude plugin details <name>`."""
+        return self._text(["plugin", "details", name])
+
+    def plugin_validate(self, path: str, *, strict: bool = False, as_json: bool = False) -> Union[str, dict]:
+        """`claude plugin validate <path>`."""
+        args = ["plugin", "validate", *build_flags({"strict": strict, "json": as_json}), path]
+        return self._json(args) if as_json else self._text(args)
+
+    def plugin_prune(self, *, scope: Optional[str] = None, yes: bool = False, dry_run: bool = False) -> str:
+        """`claude plugin prune` — removes orphaned auto-installed dependencies."""
+        args = ["plugin", "prune", *build_flags({"scope": scope, "yes": yes, "dry_run": dry_run})]
+        return self._text(args)
+
+    def plugin_marketplace_list(self) -> str:
+        """`claude plugin marketplace list`."""
+        return self._text(["plugin", "marketplace", "list"])
+
+    def plugin_marketplace_add(self, source: str) -> str:
+        """`claude plugin marketplace add <source>` (URL, path, or GitHub repo)."""
+        return self._text(["plugin", "marketplace", "add", source])
+
+    def plugin_marketplace_remove(self, name: str) -> str:
+        """`claude plugin marketplace remove <name>`."""
+        return self._text(["plugin", "marketplace", "remove", name])
+
+    def plugin_marketplace_update(self, name: Optional[str] = None) -> str:
+        """`claude plugin marketplace update [name]` (updates all if omitted)."""
+        return self._text(["plugin", "marketplace", "update"] + ([name] if name else []))
+
+    # -- project state -----------------------------------------------------
+
+    def project_purge(self, path: Optional[str] = None) -> str:
+        """`claude project purge [path]` — deletes all local state for a project."""
+        return self._text(["project", "purge"] + ([path] if path else []))
+
+    # -- auto mode -----------------------------------------------------------
+
+    def auto_mode_config(self) -> dict:
+        """`claude auto-mode config` — the effective classifier config as JSON."""
+        return self._json(["auto-mode", "config"])
+
+    def auto_mode_defaults(self) -> dict:
+        """`claude auto-mode defaults` — the shipped default rules as JSON."""
+        return self._json(["auto-mode", "defaults"])
+
+    def auto_mode_reset(self) -> str:
+        """`claude auto-mode reset` — removes custom rules from user settings."""
+        return self._text(["auto-mode", "reset"])
+
+    def auto_mode_critique(self) -> str:
+        """`claude auto-mode critique` — AI feedback on your custom rules."""
+        return self._text(["auto-mode", "critique"])
+
+    # -- misc ---------------------------------------------------------------
+
+    def import_config(
+        self,
+        source: str,
+        *,
+        dry_run: bool = False,
+        yes: Union[bool, str, None] = None,
+    ) -> str:
+        """`claude import <source>` (source: codex, gemini, or cursor).
+
+        Pass `dry_run=True` and/or `yes=True` (or a digest string) for
+        non-interactive use; otherwise the CLI may prompt interactively.
+        """
+        args = ["import", source] + build_flags({"dry_run": dry_run, "yes": yes})
+        return self._text(args)
+
+    def ultrareview(
+        self,
+        target: Optional[str] = None,
+        *,
+        as_json: bool = False,
+        post: bool = False,
+        timeout_minutes: Optional[int] = None,
+        timeout: Optional[float] = None,
+    ) -> Union[str, dict]:
+        """`claude ultrareview [target]` — cloud multi-agent code review.
+
+        `target` is a PR number or base branch; omit it to review the current
+        branch. `timeout` (seconds) bounds this call locally; `timeout_minutes`
+        is the CLI's own remote-review budget (default 45).
+        """
+        options = build_flags({"json": as_json, "post": post, "timeout": timeout_minutes})
+        args = ["ultrareview", *options] + ([target] if target else [])
+        result = self.run(args, timeout=timeout)
+        if as_json:
+            return json.loads(result.stdout)
+        return result.stdout
+
+    def start_gateway(self, *, config: Optional[str] = None):
+        """`claude gateway` — starts the enterprise auth/telemetry gateway.
+
+        This is a long-running server, so it's started with `Popen` (not
+        waited on) and the process handle is returned; call `.terminate()`
+        on it when you're done.
+        """
+        import subprocess
+
+        args = [self.binary, "gateway", *build_flags({"config": config})]
+        return subprocess.Popen(args, cwd=self.cwd, env=self.env)

pyclaudecli/exceptions.py

@@ -0,0 +1,32 @@
+"""Exceptions raised by pyclaudecli."""
+
+from __future__ import annotations
+
+from typing import Optional, Sequence
+
+
+class ClaudeCLIError(Exception):
+    """Raised when the `claude` CLI exits with a non-zero status."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        returncode: Optional[int] = None,
+        stdout: Optional[str] = None,
+        stderr: Optional[str] = None,
+        cmd: Optional[Sequence[str]] = None,
+    ) -> None:
+        super().__init__(message)
+        self.returncode = returncode
+        self.stdout = stdout
+        self.stderr = stderr
+        self.cmd = list(cmd) if cmd is not None else None
+
+
+class ClaudeNotFoundError(ClaudeCLIError):
+    """Raised when the `claude` binary can't be found on PATH."""
+
+
+class ClaudeTimeoutError(ClaudeCLIError):
+    """Raised when a `claude` invocation exceeds its timeout."""

pyclaudecli-0.1.0.dist-info/METADATA

@@ -0,0 +1,94 @@
+Metadata-Version: 2.5
+Name: pyclaudecli
+Version: 0.1.0
+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
+License-File: LICENSE
+Keywords: anthropic,automation,claude,claude-code,cli,sdk,wrapper
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# pyclaudecli
+
+A Python library that wraps the [Claude Code](https://claude.com/claude-code) CLI (`claude`) so you can drive it from Python instead of shelling out by hand: one-shot prompts, JSON/streaming output, background agents, authentication, MCP servers, plugins, and the rest of the CLI's surface.
+
+It's a thin wrapper, not a reimplementation — every call runs the real `claude` binary, so it always reflects whatever version, auth, and config you have installed locally.
+
+## Install
+
+```bash
+pip install pyclaudecli
+```
+
+Requires the `claude` CLI itself to be installed and on `PATH` (see the [Claude Code docs](https://claude.com/claude-code)).
+
+## Quickstart
+
+```python
+from pyclaudecli import ClaudeCLI
+
+claude = ClaudeCLI()
+
+# One-shot prompt
+print(claude.prompt("Summarize this repo's README.", model="haiku"))
+
+# Structured result (cost, session id, etc.)
+result = claude.prompt_json("What's 2+2?", model="haiku")
+print(result["result"], result["total_cost_usd"])
+
+# Live streaming events
+for event in claude.prompt_stream("Write a haiku about tests.", model="haiku"):
+    print(event["type"])
+```
+
+## Background agents
+
+```python
+session_id = claude.start_background("Refactor the auth module", model="sonnet")
+claude.list_agents()
+claude.logs(session_id, strip_ansi=True)
+claude.stop(session_id)
+claude.rm(session_id)
+```
+
+## Auth
+
+```python
+claude.auth_status()  # {"loggedIn": True, "email": "...", ...}
+
+# Prints the sign-in URL, then forwards the pasted code to finish login
+claude.auth_login()
+```
+
+## MCP servers and plugins
+
+```python
+claude.mcp_add("sentry", "https://mcp.sentry.dev/mcp", transport="http")
+claude.mcp_list()
+
+claude.plugin_install("some-plugin", yes=True)
+claude.plugin_list(as_json=True)
+```
+
+See `ClaudeCLI`'s docstrings for the full method list — 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.
+
+## Errors
+
+All CLI failures raise `ClaudeCLIError` (or `ClaudeNotFoundError` / `ClaudeTimeoutError`), carrying `returncode`, `stdout`, and `stderr`.
+
+## License
+
+MIT

pyclaudecli-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pyclaudecli/__init__.py,sha256=mhEn48gp_bZiMgBmYu3QFNShOp8vbeFojYm5WJqeKbY,352
+pyclaudecli/__main__.py,sha256=kof4pG7QHlkQr1w7xYqH8EwPAnNqj8PFjjCFX-RKy5E,1540
+pyclaudecli/_process.py,sha256=jp7rvHqBY7XLE0CSrE9cI2mmEa61qlLBFW19EQDezv8,7076
+pyclaudecli/client.py,sha256=ZBIzKc68Lmd6fYx8CzZCF9m7TvyzWPZ9iWDVLkLVivg,22830
+pyclaudecli/exceptions.py,sha256=G2-5Vp2hBK-Q7jck-ybq2G6NRi5hHpxty9d7fLArUuA,870
+pyclaudecli-0.1.0.dist-info/METADATA,sha256=3HW7O-83nukvLd1GwFKPVIY21dH_C8IJ-kE2XxKWWdw,3310
+pyclaudecli-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pyclaudecli-0.1.0.dist-info/entry_points.txt,sha256=RzYhNNBMvPbe6g3zH4OwC1NLmz38mYEePKDtryrR5c4,58
+pyclaudecli-0.1.0.dist-info/licenses/LICENSE,sha256=--FgFwZp9RlY-pXA4xV-pw-3oeGsyNk2vjIr3bQRnBY,1076
+pyclaudecli-0.1.0.dist-info/RECORD,,

pyclaudecli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pyclaudecli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyclaudecli = pyclaudecli.__main__:main

pyclaudecli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suriya Ravichandran
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.