pyplines-cli 2026.7.0a1__py3-none-any.whl

cli/__init__.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Annotated
+
+import typer
+
+from cli.apps.config import app as config_app
+from cli.apps.function import app as function_app
+from cli.config.loader import ConfigurationError, create_settings, get_config_path
+from cli.context import AppContext
+from cli.errors import exit_with_error
+from cli.output.mode import OutputMode, resolve_output_mode
+from cli.output.render import emit_data
+
+app = typer.Typer(
+    name="pyplines",
+    help="Build and operate Pyplines automation",
+    add_completion=False,
+    no_args_is_help=True,
+)
+app.add_typer(config_app, name="config")
+app.add_typer(function_app, name="function")
+
+
+@app.callback()
+def root_callback(
+    ctx: typer.Context,
+    output_json: Annotated[
+        bool,
+        typer.Option("--json", help="Emit machine-readable JSON output"),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option("--verbose", "-v", help="Show verbose diagnostics"),
+    ] = False,
+) -> None:
+    try:
+        config_path = get_config_path()
+        settings = create_settings(config_path)
+        output_mode = resolve_output_mode(
+            force_json=output_json,
+            configured_mode=str(settings.get("mode", "interactive")),
+        )
+        ctx.obj = AppContext(
+            settings=settings,
+            config_path=config_path,
+            output_mode=output_mode,
+            verbose=verbose,
+        )
+    except Exception as exc:
+        mode = OutputMode.JSON if output_json else OutputMode.TABLE
+        exit_with_error(exc, mode, kind="configuration")
+
+
+@app.command("version")
+def version_command(ctx: typer.Context) -> None:
+    context: AppContext = ctx.find_root().obj
+    try:
+        cli_version = version("pyplines-cli")
+    except PackageNotFoundError:
+        cli_version = "development"
+    emit_data({"pyplines-cli": cli_version}, context.output_mode)
+
+
+__all__ = ["app"]

cli/apps/__init__.py

@@ -0,0 +1 @@
+"""CLI command groups."""

cli/apps/config.py

@@ -0,0 +1,67 @@
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+import typer
+import yaml
+
+from cli.config.loader import effective_settings
+from cli.config.mutation import delete_dotted, set_dotted
+from cli.context import AppContext
+from cli.errors import exit_with_error
+from cli.output.render import emit_data
+
+app = typer.Typer(help="Manage Pyplines CLI configuration", no_args_is_help=True)
+
+
+def _context(ctx: typer.Context) -> AppContext:
+    return ctx.find_root().obj
+
+
+@app.command("path")
+def path_command(ctx: typer.Context) -> None:
+    context = _context(ctx)
+    emit_data({"path": str(context.config_path)}, context.output_mode)
+
+
+@app.command("show")
+def show_command(ctx: typer.Context) -> None:
+    context = _context(ctx)
+    emit_data(effective_settings(context.settings), context.output_mode)
+
+
+@app.command("get")
+def get_command(ctx: typer.Context, key: str) -> None:
+    context = _context(ctx)
+    sentinel = object()
+    value = context.settings.get(key, sentinel)
+    if value is sentinel:
+        exit_with_error(KeyError(f"setting does not exist: {key}"), context.output_mode)
+    emit_data({key: value}, context.output_mode)
+
+
+@app.command("set")
+def set_command(ctx: typer.Context, key: str, value: str) -> None:
+    context = _context(ctx)
+    try:
+        parsed: Any = yaml.safe_load(value)
+        set_dotted(context.config_path, key, parsed)
+        emit_data({key: parsed}, context.output_mode)
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="configuration")
+
+
+@app.command("rm")
+def remove_command(ctx: typer.Context, key: str) -> None:
+    context = _context(ctx)
+    try:
+        delete_dotted(context.config_path, key)
+        emit_data({"removed": key}, context.output_mode)
+    except KeyError:
+        exit_with_error(
+            ValueError(f"setting does not exist in config file: {key}"),
+            context.output_mode,
+            kind="configuration",
+        )
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="configuration")

cli/apps/function.py

@@ -0,0 +1,216 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated, Any
+
+import typer
+
+from cli.context import AppContext
+from cli.development.client import FunctionDevelopmentClient
+from cli.development.events import DevelopmentEvent
+from cli.errors import CliError, exit_with_error
+from cli.function.inputs import load_inputs
+from cli.function.scaffold import initialize_function
+from cli.output.mode import OutputMode
+from cli.output.render import emit_data, emit_json_event
+
+app = typer.Typer(help="Develop Pyplines Functions", no_args_is_help=True)
+
+
+class RemoteOperationFailed(Exception):
+    pass
+
+
+def _context(ctx: typer.Context) -> AppContext:
+    return ctx.find_root().obj
+
+
+def _client(context: AppContext) -> FunctionDevelopmentClient:
+    settings = context.settings
+    return FunctionDevelopmentClient(
+        base_url=str(settings.get("function_development.url")),
+        connect_timeout=float(settings.get("function_development.connect_timeout")),
+        operation_timeout=float(settings.get("function_development.operation_timeout")),
+    )
+
+
+@app.command("init")
+def init_command(
+    ctx: typer.Context,
+    name: str,
+    path: Annotated[
+        Path, typer.Option(help="Parent directory for the Function")
+    ] = Path("."),
+    template: Annotated[
+        str | None, typer.Option(help="Git repository containing the Function template")
+    ] = None,
+    template_ref: Annotated[
+        str | None, typer.Option(help="Template Git tag, branch, or commit")
+    ] = None,
+) -> None:
+    context = _context(ctx)
+    repository = template or str(context.settings.get("function.template.repository"))
+    ref = template_ref or str(context.settings.get("function.template.ref"))
+    try:
+        destination = initialize_function(
+            slug=name,
+            parent=path,
+            repository=repository,
+            ref=ref,
+        )
+        emit_data(
+            {
+                "function": name,
+                "path": str(destination),
+                "template": repository,
+                "template_ref": ref,
+            },
+            context.output_mode,
+        )
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="function-init")
+
+
+@app.command("status")
+def status_command(ctx: typer.Context) -> None:
+    context = _context(ctx)
+    try:
+        with _client(context) as client:
+            emit_data(client.status(), context.output_mode)
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="function-development")
+
+
+@app.command("check")
+def check_command(
+    ctx: typer.Context,
+    path: Annotated[Path, typer.Argument(help="Mounted Function project path")] = Path(
+        "."
+    ),
+) -> None:
+    context = _context(ctx)
+    try:
+        _require_project(path)
+        with _client(context) as client:
+            _render_stream(client.check(), context.output_mode)
+    except RemoteOperationFailed:
+        raise typer.Exit(code=1)
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="function-check")
+
+
+@app.command("invoke")
+def invoke_command(
+    ctx: typer.Context,
+    path: Annotated[Path, typer.Argument(help="Mounted Function project path")] = Path(
+        "."
+    ),
+    inputs: Annotated[
+        list[str] | None,
+        typer.Option("--input", help="Function input in key=value form"),
+    ] = None,
+    input_file: Annotated[
+        Path | None,
+        typer.Option(help="JSON or YAML input file"),
+    ] = None,
+    sensitive_paths: Annotated[
+        list[str] | None,
+        typer.Option("--sensitive-path", help="Sensitive input JSON pointer"),
+    ] = None,
+) -> None:
+    context = _context(ctx)
+    try:
+        _require_project(path)
+        payload = load_inputs(
+            assignments=inputs or [],
+            input_file=input_file,
+        )
+        with _client(context) as client:
+            _render_stream(
+                client.invoke(payload, sensitive_paths or []),
+                context.output_mode,
+            )
+    except RemoteOperationFailed:
+        raise typer.Exit(code=1)
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="function-invoke")
+
+
+@app.command("package")
+def package_command(
+    ctx: typer.Context,
+    path: Annotated[Path, typer.Argument(help="Mounted Function project path")] = Path(
+        "."
+    ),
+) -> None:
+    context = _context(ctx)
+    try:
+        project = _require_project(path)
+        with _client(context) as client:
+            result = _render_stream(client.package(), context.output_mode)
+        if isinstance(result, dict) and isinstance(result.get("path"), str):
+            local_archive = project / "dist" / Path(result["path"]).name
+            if not local_archive.is_file():
+                raise CliError(
+                    f"Function Package was not created locally: {local_archive}"
+                )
+    except RemoteOperationFailed:
+        raise typer.Exit(code=1)
+    except Exception as exc:
+        exit_with_error(exc, context.output_mode, kind="function-package")
+
+
+def _render_stream(events: Any, mode: OutputMode) -> Any:
+    terminal_result: Any = None
+    failed = False
+    for event in events:
+        if mode is OutputMode.JSON:
+            emit_json_event(event.raw)
+        else:
+            _render_table_event(event)
+        if event.type == "result":
+            terminal_result = event.payload
+        elif event.type == "error":
+            failed = True
+    if failed:
+        raise RemoteOperationFailed()
+    if terminal_result is None:
+        raise CliError("development operation ended without a result")
+    return terminal_result
+
+
+def _render_table_event(event: DevelopmentEvent) -> None:
+    payload = event.payload
+    if event.type == "progress":
+        stage = (
+            payload.get("stage", "progress") if isinstance(payload, dict) else payload
+        )
+        typer.echo(f"[{stage}]")
+    elif event.type == "log":
+        if isinstance(payload, dict):
+            level = payload.get("level", "info")
+            message = payload.get("message", "")
+            fields = payload.get("fields") or {}
+            suffix = " ".join(f"{key}={value}" for key, value in fields.items())
+            typer.echo(f"[{level}] {message}" + (f" {suffix}" if suffix else ""))
+        else:
+            typer.echo(str(payload))
+    elif event.type == "diagnostic":
+        message = (
+            payload.get("message", payload) if isinstance(payload, dict) else payload
+        )
+        typer.echo(str(message), err=True)
+    elif event.type == "error":
+        message = (
+            payload.get("message", payload) if isinstance(payload, dict) else payload
+        )
+        typer.echo(f"Error: {message}", err=True)
+    elif event.type == "result":
+        emit_data(payload, OutputMode.TABLE)
+
+
+def _require_project(path: Path) -> Path:
+    project = path.expanduser().resolve()
+    if not (project / "pyproject.toml").is_file():
+        raise CliError(f"Function project does not contain pyproject.toml: {project}")
+    return project

cli/config/__init__.py

@@ -0,0 +1,3 @@
+from cli.config.loader import create_settings, get_config_path
+
+__all__ = ["create_settings", "get_config_path"]

cli/config/loader.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+from urllib.parse import urlparse
+
+from dynaconf import Dynaconf
+from platformdirs import user_config_dir
+
+DEFAULTS: dict[str, Any] = {
+    "mode": "interactive",
+    "function_development": {
+        "url": "http://127.0.0.1:7331",
+        "connect_timeout": 5,
+        "operation_timeout": 1800,
+    },
+    "function": {
+        "template": {
+            "repository": "https://github.com/pyplines/function-template.git",
+            "ref": "v1",
+        }
+    },
+}
+
+
+class ConfigurationError(ValueError):
+    pass
+
+
+def get_config_path() -> Path:
+    override = os.getenv("PYPLINES_CONFIG_FILE")
+    if override:
+        return Path(override).expanduser().resolve()
+    return Path(user_config_dir("pyplines")) / "config.yaml"
+
+
+def create_settings(path: Path | None = None, *, load_env: bool = True) -> Dynaconf:
+    config_path = (path or get_config_path()).expanduser().resolve()
+    settings = Dynaconf(
+        envvar_prefix="PYPLINES" if load_env else False,
+        settings_files=[str(config_path)],
+        environments=False,
+        load_dotenv=False,
+        core_loaders=["YAML"],
+        merge_enabled=True,
+    )
+    _apply_defaults(settings, DEFAULTS)
+    validate_settings(settings)
+    return settings
+
+
+def validate_settings(settings: Dynaconf) -> None:
+    mode = str(settings.get("mode", "interactive")).lower()
+    if mode not in {"interactive", "automation"}:
+        raise ConfigurationError("mode must be interactive or automation")
+
+    url = str(settings.get("function_development.url", ""))
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc:
+        raise ConfigurationError(
+            "function_development.url must be an HTTP or HTTPS URL"
+        )
+
+    for key in (
+        "function_development.connect_timeout",
+        "function_development.operation_timeout",
+    ):
+        value = settings.get(key)
+        if isinstance(value, bool) or not isinstance(value, (int, float)) or value <= 0:
+            raise ConfigurationError(f"{key} must be a positive number")
+
+    repository = str(settings.get("function.template.repository", "")).strip()
+    if not repository:
+        raise ConfigurationError("function.template.repository must not be empty")
+    template_ref = str(settings.get("function.template.ref", "")).strip()
+    if not template_ref:
+        raise ConfigurationError("function.template.ref must not be empty")
+
+
+def effective_settings(settings: Dynaconf) -> dict[str, Any]:
+    ignored = {"LOAD_DOTENV", "CONFIG_FILE"}
+    return {
+        str(key).lower(): _normalize_effective(value)
+        for key, value in settings.as_dict().items()
+        if key not in ignored
+    }
+
+
+def _apply_defaults(
+    settings: Dynaconf, values: dict[str, Any], prefix: str = ""
+) -> None:
+    missing = object()
+    for key, value in values.items():
+        dotted = f"{prefix}.{key}" if prefix else key
+        if isinstance(value, dict):
+            _apply_defaults(settings, value, dotted)
+        elif settings.get(dotted, missing) is missing:
+            settings.set(dotted, value)
+
+
+def _normalize_effective(value: Any) -> Any:
+    if isinstance(value, dict):
+        normalized = {}
+        for key, item in value.items():
+            name = str(key).lower()
+            if any(marker in name for marker in ("token", "password", "secret")):
+                normalized[name] = "[REDACTED]"
+            else:
+                normalized[name] = _normalize_effective(item)
+        return normalized
+    if isinstance(value, list):
+        return [_normalize_effective(item) for item in value]
+    return value

cli/config/mutation.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from cli.config.loader import create_settings
+
+
+def read_source(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    try:
+        value = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ValueError(f"configuration is not valid YAML: {exc}") from exc
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ValueError("configuration root must be an object")
+    return value
+
+
+def get_dotted(value: dict[str, Any], key: str) -> Any:
+    current: Any = value
+    for segment in _segments(key):
+        if not isinstance(current, dict) or segment not in current:
+            raise KeyError(key)
+        current = current[segment]
+    return current
+
+
+def set_dotted(path: Path, key: str, value: Any) -> None:
+    source = read_source(path)
+    current = source
+    segments = _segments(key)
+    for segment in segments[:-1]:
+        child = current.setdefault(segment, {})
+        if not isinstance(child, dict):
+            raise ValueError(f"cannot set nested key below scalar: {segment}")
+        current = child
+    current[segments[-1]] = value
+    write_source(path, source)
+
+
+def delete_dotted(path: Path, key: str) -> None:
+    source = read_source(path)
+    current = source
+    segments = _segments(key)
+    parents: list[tuple[dict[str, Any], str]] = []
+    for segment in segments[:-1]:
+        child = current.get(segment)
+        if not isinstance(child, dict):
+            raise KeyError(key)
+        parents.append((current, segment))
+        current = child
+    if segments[-1] not in current:
+        raise KeyError(key)
+    del current[segments[-1]]
+    for parent, segment in reversed(parents):
+        if parent[segment] == {}:
+            del parent[segment]
+    write_source(path, source)
+
+
+def write_source(path: Path, source: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    encoded = yaml.safe_dump(source, sort_keys=False, default_flow_style=False)
+    descriptor, temporary = tempfile.mkstemp(
+        prefix=f".{path.name}.", suffix=".yaml", dir=path.parent
+    )
+    temporary_path = Path(temporary)
+    try:
+        with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
+            handle.write(encoded)
+        os.chmod(temporary_path, 0o600)
+        create_settings(temporary_path, load_env=False)
+        os.replace(temporary_path, path)
+    except Exception:
+        temporary_path.unlink(missing_ok=True)
+        raise
+
+
+def _segments(key: str) -> list[str]:
+    segments = [segment.strip().lower() for segment in key.split(".")]
+    if not segments or any(not segment for segment in segments):
+        raise ValueError("configuration key must use nonempty dotted segments")
+    return segments

cli/context.py

@@ -0,0 +1,14 @@
+from dataclasses import dataclass
+from pathlib import Path
+
+from dynaconf import Dynaconf
+
+from cli.output.mode import OutputMode
+
+
+@dataclass(frozen=True)
+class AppContext:
+    settings: Dynaconf
+    config_path: Path
+    output_mode: OutputMode
+    verbose: bool = False

cli/development/__init__.py

@@ -0,0 +1,3 @@
+from cli.development.client import FunctionDevelopmentClient
+
+__all__ = ["FunctionDevelopmentClient"]

cli/development/client.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from cli.development.events import DevelopmentEvent
+from cli.errors import CliError
+
+TOKEN_ENV = "PYPLINES_FUNCTION_DEVELOPMENT_TOKEN"
+
+
+class FunctionDevelopmentClient:
+    def __init__(
+        self,
+        *,
+        base_url: str,
+        connect_timeout: float,
+        operation_timeout: float,
+        token: str | None = None,
+        transport: httpx.BaseTransport | None = None,
+    ):
+        resolved_token = token or os.getenv(TOKEN_ENV)
+        if not resolved_token:
+            raise CliError(f"development token is required in {TOKEN_ENV}")
+        self._token = resolved_token
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers={"Authorization": f"Bearer {resolved_token}"},
+            timeout=httpx.Timeout(operation_timeout, connect=connect_timeout),
+            transport=transport,
+        )
+
+    def __enter__(self) -> "FunctionDevelopmentClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._client.close()
+
+    def status(self) -> dict[str, Any]:
+        try:
+            response = self._client.get("/v1/status")
+            response.raise_for_status()
+            value = response.json()
+        except (httpx.HTTPError, ValueError) as exc:
+            raise CliError(self._safe_error(exc)) from exc
+        if not isinstance(value, dict):
+            raise CliError("development status response must be an object")
+        return value
+
+    def check(self) -> Iterator[DevelopmentEvent]:
+        return self._stream("/v1/functions/check")
+
+    def invoke(
+        self, inputs: dict[str, Any], sensitive_paths: list[str]
+    ) -> Iterator[DevelopmentEvent]:
+        return self._stream(
+            "/v1/functions/invoke",
+            payload={
+                "input": inputs,
+                "sensitive_input_paths": sensitive_paths,
+            },
+        )
+
+    def package(self) -> Iterator[DevelopmentEvent]:
+        return self._stream("/v1/functions/package")
+
+    def _stream(
+        self, path: str, payload: dict[str, Any] | None = None
+    ) -> Iterator[DevelopmentEvent]:
+        try:
+            with self._client.stream("POST", path, json=payload) as response:
+                response.raise_for_status()
+                for line in response.iter_lines():
+                    if not line:
+                        continue
+                    try:
+                        value = json.loads(line)
+                        yield DevelopmentEvent.parse(value)
+                    except (json.JSONDecodeError, ValueError) as exc:
+                        raise CliError(f"invalid development event: {exc}") from exc
+        except httpx.HTTPError as exc:
+            raise CliError(self._safe_error(exc)) from exc
+
+    def _safe_error(self, error: Exception) -> str:
+        return str(error).replace(self._token, "[REDACTED]")

cli/development/events.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+EVENT_TYPES = {"progress", "log", "diagnostic", "result", "error"}
+
+
+@dataclass(frozen=True)
+class DevelopmentEvent:
+    type: str
+    payload: Any
+    raw: dict[str, Any]
+
+    @classmethod
+    def parse(cls, value: Any) -> "DevelopmentEvent":
+        if not isinstance(value, dict):
+            raise ValueError("development event must be an object")
+        event_type = value.get("type")
+        if event_type not in EVENT_TYPES:
+            raise ValueError(f"unknown development event type: {event_type}")
+        if event_type not in value:
+            raise ValueError(f"development event is missing {event_type} payload")
+        return cls(type=event_type, payload=value[event_type], raw=value)

cli/errors.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import json
+
+import typer
+
+from cli.output.mode import OutputMode
+
+
+class CliError(Exception):
+    pass
+
+
+def exit_with_error(error: Exception, mode: OutputMode, *, kind: str = "cli") -> None:
+    message = str(error)
+    if mode is OutputMode.JSON:
+        typer.echo(
+            json.dumps(
+                {"error": {"kind": kind, "message": message}},
+                separators=(",", ":"),
+            ),
+            err=True,
+        )
+    else:
+        typer.echo(f"Error: {message}", err=True)
+    raise typer.Exit(code=1)

cli/function/__init__.py

@@ -0,0 +1 @@
+"""Function development helpers."""

cli/function/inputs.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Any, TextIO
+
+import yaml
+
+
+def load_inputs(
+    *,
+    assignments: list[str],
+    input_file: Path | None,
+    stream: TextIO | None = None,
+) -> dict[str, Any]:
+    source = stream or sys.stdin
+    stdin_value = None
+    if not source.isatty():
+        content = source.read()
+        if content.strip():
+            stdin_value = _decode(content, "stdin")
+    if input_file is not None and stdin_value is not None:
+        raise ValueError("stdin and --input-file cannot both provide input")
+    if input_file is not None:
+        if not input_file.is_file():
+            raise ValueError(f"input file does not exist: {input_file}")
+        base = _decode(input_file.read_text(encoding="utf-8"), str(input_file))
+    else:
+        base = stdin_value or {}
+    if not isinstance(base, dict):
+        raise ValueError("Function input must be an object")
+    result = dict(base)
+    for assignment in assignments:
+        key, separator, raw = assignment.partition("=")
+        key = key.strip()
+        if not separator or not key:
+            raise ValueError("--input must use key=value syntax")
+        result[key] = yaml.safe_load(raw)
+    return result
+
+
+def _decode(content: str, source: str) -> Any:
+    try:
+        return yaml.safe_load(content)
+    except yaml.YAMLError as exc:
+        raise ValueError(f"invalid JSON or YAML from {source}: {exc}") from exc

cli/function/scaffold.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import re
+import shutil
+import subprocess
+import tempfile
+import tomllib
+from pathlib import Path
+
+from cli.errors import CliError
+
+SLUG = re.compile(r"^[a-z0-9]+(?:-[a-z0-9]+)*$")
+
+
+def initialize_function(
+    *,
+    slug: str,
+    parent: Path,
+    repository: str,
+    ref: str,
+) -> Path:
+    if not SLUG.fullmatch(slug):
+        raise CliError("Function name must use lowercase letters, numbers, and hyphens")
+    parent = parent.expanduser().resolve()
+    destination = parent / slug
+    if destination.exists() and any(destination.iterdir()):
+        raise CliError(f"destination is not empty: {destination}")
+    parent.mkdir(parents=True, exist_ok=True)
+    temporary = Path(tempfile.mkdtemp(prefix=f".{slug}.", dir=parent))
+    try:
+        _clone(repository, ref, temporary)
+        shutil.rmtree(temporary / ".git", ignore_errors=True)
+        _customize(temporary, slug)
+        _validate(temporary, slug)
+        if destination.exists():
+            destination.rmdir()
+        temporary.rename(destination)
+        return destination
+    except Exception:
+        shutil.rmtree(temporary, ignore_errors=True)
+        raise
+
+
+def _clone(repository: str, ref: str, destination: Path) -> None:
+    commands = [
+        [
+            "git",
+            "clone",
+            "--depth",
+            "1",
+            "--no-checkout",
+            repository,
+            str(destination),
+        ],
+        [
+            "git",
+            "-C",
+            str(destination),
+            "fetch",
+            "--depth",
+            "1",
+            "origin",
+            ref,
+        ],
+        ["git", "-C", str(destination), "checkout", "--detach", "FETCH_HEAD"],
+    ]
+    try:
+        for command in commands:
+            subprocess.run(command, capture_output=True, text=True, check=True)
+    except FileNotFoundError as exc:
+        raise CliError("Git is required to initialize a Function") from exc
+    except subprocess.CalledProcessError as exc:
+        message = exc.stderr.strip() or "Git clone failed"
+        raise CliError(message) from exc
+
+
+def _customize(root: Path, slug: str) -> None:
+    module = slug.replace("-", "_")
+    candidates = [root / "src" / "function_template", root / "function_template"]
+    for candidate in candidates:
+        if candidate.is_dir():
+            candidate.rename(candidate.with_name(module))
+    replacements = {
+        "function-template": slug,
+        "function_template": module,
+        "Function Template": _display_name(slug),
+    }
+    for path in root.rglob("*"):
+        if not path.is_file() or ".git" in path.parts:
+            continue
+        try:
+            content = path.read_text(encoding="utf-8")
+        except UnicodeDecodeError:
+            continue
+        for old, new in replacements.items():
+            content = content.replace(old, new)
+        path.write_text(content, encoding="utf-8")
+
+
+def _validate(root: Path, slug: str) -> None:
+    pyproject = root / "pyproject.toml"
+    if not pyproject.is_file():
+        raise CliError("Function template does not contain pyproject.toml")
+    data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+    if data.get("project", {}).get("name") != slug:
+        raise CliError("Function template did not produce the requested project name")
+    handler = (
+        data.get("tool", {}).get("pyplines", {}).get("function", {}).get("handler")
+    )
+    if not isinstance(handler, str) or ":" not in handler:
+        raise CliError("Function template does not declare a valid handler")
+
+
+def _display_name(slug: str) -> str:
+    return " ".join(part.capitalize() for part in slug.split("-"))

cli/output/__init__.py

@@ -0,0 +1,3 @@
+from cli.output.mode import OutputMode
+
+__all__ = ["OutputMode"]

cli/output/mode.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class OutputMode(str, Enum):
+    TABLE = "table"
+    JSON = "json"
+
+
+def resolve_output_mode(*, force_json: bool, configured_mode: str) -> OutputMode:
+    if force_json or configured_mode.lower() == "automation":
+        return OutputMode.JSON
+    return OutputMode.TABLE

cli/output/render.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from typing import Any
+
+import typer
+
+from cli.output.mode import OutputMode
+
+
+def emit_data(value: Any, mode: OutputMode) -> None:
+    if mode is OutputMode.JSON:
+        typer.echo(json.dumps(value, separators=(",", ":"), ensure_ascii=False))
+        return
+    if isinstance(value, Mapping):
+        width = max((len(str(key)) for key in value), default=0)
+        for key, item in value.items():
+            typer.echo(f"{str(key):<{width}}  {_display(item)}")
+        return
+    typer.echo(_display(value))
+
+
+def emit_json_event(event: dict[str, Any]) -> None:
+    typer.echo(json.dumps(event, separators=(",", ":"), ensure_ascii=False))
+
+
+def _display(value: Any) -> str:
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False)
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    return str(value)

pyplines_cli-2026.7.0a1.dist-info/METADATA

@@ -0,0 +1,93 @@
+Metadata-Version: 2.4
+Name: pyplines-cli
+Version: 2026.7.0a1
+Summary: The official command-line interface for Pyplines
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: dynaconf[yaml]<4,>=3.2.7
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: platformdirs<5,>=4
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: typer<1,>=0.24
+
+# pyplines-cli
+
+`pyplines-cli` is the command-line interface for Pyplines. The initial command
+surface supports local Function development through a running Pyplines Function
+development container. Server commands will use the same CLI in later releases.
+
+## Install
+
+```console
+pip install pyplines-cli
+```
+
+## Configuration
+
+Configuration is YAML stored in the platform-native user configuration directory.
+Find the exact path with:
+
+```console
+pyplines config path
+```
+
+Initial shape:
+
+```yaml
+mode: interactive
+
+function_development:
+  url: http://127.0.0.1:7331
+  connect_timeout: 5
+  operation_timeout: 1800
+
+function:
+  template:
+    repository: https://github.com/pyplines/function-template.git
+    ref: v1
+```
+
+Every setting can be overridden with a `PYPLINES_` environment variable. Use
+double underscores for nested keys:
+
+```console
+export PYPLINES_MODE=automation
+export PYPLINES_FUNCTION_DEVELOPMENT__URL=http://127.0.0.1:7331
+export PYPLINES_FUNCTION_DEVELOPMENT_TOKEN="<local-container-token>"
+```
+
+The token is environment-only and is not written to the configuration file.
+
+## Output
+
+Table output is the interactive default. JSON is selected by either:
+
+```console
+pyplines --json function status
+PYPLINES_MODE=automation pyplines function status
+```
+
+Streaming operations emit NDJSON in JSON mode.
+
+## Function Development
+
+Initialize from the configured, pinned Git template:
+
+```console
+pyplines function init hello-world
+```
+
+Check, invoke, and package the Function mounted into the development container:
+
+```console
+cd hello-world
+pyplines function status
+pyplines function check
+pyplines function invoke --input name=Ada
+pyplines function invoke --input-file inputs.yaml
+pyplines function package
+```
+
+`function init` uses the system Git client and honors existing credential helpers,
+SSH agents, proxies, and enterprise Git configuration. It does not execute template
+hooks or retain the template repository's `.git` directory.

pyplines_cli-2026.7.0a1.dist-info/RECORD

@@ -0,0 +1,23 @@
+cli/__init__.py,sha256=tNi1zWe9MGYmfKOyoKXus7u_57-N22GJawPtoys5fb0,1970
+cli/context.py,sha256=s_09baiQXrgdBjeSlLGt6LcjAjJaHSBD0Zbny5njKbg,273
+cli/errors.py,sha256=SgG3LTcxgFpWUDWUWJ7-z3FG0lfgRTkBC8-XaD7NWKI,568
+cli/apps/__init__.py,sha256=Rb-d2e6JpWZ5pPUP-TjKMWGtNCwpZCMYc0GulfEXbRs,26
+cli/apps/config.py,sha256=jQeLbaQD6gPZOmyHYqSfUfKvFwgM87P_yrPr71kOuGM,2057
+cli/apps/function.py,sha256=6TzlHcSQEXWh0kUAGbNOhJTcGmv4dfGIkYFaiXAyY-I,7091
+cli/config/__init__.py,sha256=2oV2Z2aVBxGredp49OGqJODBuVL9i2Gl2KchrNg_8xQ,113
+cli/config/loader.py,sha256=35rgbQtz_DqN23OZpYKddUB8SN81-rIG92q1fLATNYI,3692
+cli/config/mutation.py,sha256=fH2U18n6AMozBa9JUkmXWnwLuinCLDDvIDyiKowB4CY,2898
+cli/development/__init__.py,sha256=Lm_ilX4YH0wZ5WAN0Gculf0ekotTIKkvnLu-c6gHR7M,102
+cli/development/client.py,sha256=Dxyd9EvIV5A4YLaUtPHncDYMcbBIjh09cRzdonrhUos,3036
+cli/development/events.py,sha256=h-HHQERDMdH8Ao4bEf-A7vJnnfgvf5UeGsG62DJBIqs,798
+cli/function/__init__.py,sha256=_jagVutGo1iq10oUsVf_5s4Qhk5zAOSPahurWzM3v_o,36
+cli/function/inputs.py,sha256=ipCcjbom4HJe-YysIytPAXrS5AZKTUVd9oN8oXmb57w,1473
+cli/function/scaffold.py,sha256=oCJ3BpFzIZA41zUJd849nOsfayhYX3VeOMI_i7Zjwcs,3664
+cli/output/__init__.py,sha256=q4Dxyb4G7phdIls-ACZnswTliv_6JJ6hAEHOSxY8WI0,65
+cli/output/mode.py,sha256=SsQt0V0gS7bFK77zECsh53L21UELn8LdwjpvCCEb0nc,296
+cli/output/render.py,sha256=K40u8_Ac8hz572UI2CjsbMVpuxDB-V2-l-93wGG91kE,993
+pyplines_cli-2026.7.0a1.dist-info/METADATA,sha256=oCo68wQPDF-hTi0S7a4phLTzAHMBAlWoJRKrsEScqKs,2301
+pyplines_cli-2026.7.0a1.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+pyplines_cli-2026.7.0a1.dist-info/entry_points.txt,sha256=atYawf14g53pcY4Fk5t00DpqTSv0zpp3MNEmeJcs3Mo,37
+pyplines_cli-2026.7.0a1.dist-info/top_level.txt,sha256=2ImG917oaVHlm0nP9oJE-Qrgs-fq_fGWgba2H1f8fpE,4
+pyplines_cli-2026.7.0a1.dist-info/RECORD,,

pyplines_cli-2026.7.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyplines_cli-2026.7.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyplines = cli:app

pyplines_cli-2026.7.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+cli