kctl-payload 0.6.1__tar.gz

kctl_payload-0.6.1/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_payload-0.6.1/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-payload
+Version: 0.6.1
+Summary: Kodemeio Payload CMS CLI — manage Payload CMS via REST API
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: kctl-lib>=0.7.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_payload-0.6.1/README.md

@@ -0,0 +1,120 @@
+# kctl-payload
+
+Kodemeio Payload CMS CLI — manage content, media, and globals via REST API.
+
+## Installation
+
+```bash
+# From workspace (development)
+uv tool install --editable packages/kctl-payload
+
+# From PyPI
+uv tool install kctl-payload
+```
+
+## Quick Start
+
+```bash
+# Initialize configuration
+kctl-payload config init
+
+# Test API connectivity
+kctl-payload config test
+
+# List entries in a collection
+kctl-payload collections list blog-posts
+
+# Upload and list media
+kctl-payload media list
+
+# Show global settings
+kctl-payload globals show site-settings
+```
+
+## Command Groups
+
+| Group | Commands | Description |
+|-------|----------|-------------|
+| `config` | init, add, use, show, set, remove, profiles, current, test, migrate | Manage profiles and credentials |
+| `collections` | list, show, create, update, delete, query | CRUD operations on collection entries |
+| `media` | list, show, upload, delete | Media library management |
+| `globals` | list, show, update | Global document management |
+| `users` | list, show, create, update, delete | User account management |
+| `doctor` | check | Diagnostic checks (API connectivity, auth, config) |
+
+## Global Options
+
+All commands accept these options:
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--format` | `-f` | Output format: `pretty`, `json`, `csv`, `yaml` |
+| `--quiet` | `-q` | Suppress info messages |
+| `--no-header` | | Omit header row in table/CSV output |
+| `--profile` | `-p` | Config profile name |
+| `--version` | `-V` | Show version and exit |
+
+## Configuration
+
+Config is stored in `~/.config/kodemeio/config.yaml` under the `payload` key.
+
+```bash
+# Create a new profile
+kctl-payload config init
+
+# Add a named profile
+kctl-payload config add --profile prod
+
+# Switch active profile
+kctl-payload config use prod
+
+# Show current config (secrets masked)
+kctl-payload config show
+
+# Test connectivity
+kctl-payload config test
+```
+
+### Config Keys
+
+| Key | Description |
+|-----|-------------|
+| `url` | Payload CMS instance URL (e.g. `https://cms.example.com`) |
+| `api_key` | Payload API key for authentication |
+
+### Profile Example
+
+```yaml
+profiles:
+  kodemeio:
+    payload:
+      url: https://cms.kodeme.io
+      api_key: ${PAYLOAD_API_KEY}
+```
+
+## Common Workflows
+
+```bash
+# Query posts with filters
+kctl-payload collections query blog-posts --where '{"status": "published"}'
+
+# Upload a media file
+kctl-payload media upload ./banner.png --alt "Homepage banner"
+
+# Update a global document
+kctl-payload globals update site-settings --data '{"maintenance": false}'
+
+# List all users
+kctl-payload users list --format json
+```
+
+## Development
+
+```bash
+cd packages/kctl-payload
+uv sync --all-extras
+uv run pytest tests/ -v
+uv run mypy src/
+uv run ruff check src/
+```

kctl_payload-0.6.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-payload"
+version = "0.6.1"
+description = "Kodemeio Payload CMS CLI — manage Payload CMS via REST API"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.7.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-payload = "kctl_payload.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_payload"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_payload-0.6.1/skills/payload-admin/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: payload-admin
+description: >
+  Payload CMS management via kctl-payload CLI.
+  MUST use for ANY kctl-payload operation.
+  Triggers on: "payload, cms, content, blog, testimonials, faqs, media, collections".
+---
+
+# kctl-payload
+
+Kodemeio Payload CMS CLI - manage your Payload CMS instance (collections, media, globals, users).
+
+## Installation
+
+```bash
+uv tool install kctl-payload
+```
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | JSON output (shortcut for --format json) |
+| `--quiet` | `-q` | Suppress info messages |
+| `--format` | `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | | Omit headers in CSV output |
+| `--debug` | | Enable debug logging |
+| `--profile` | `-p` | Config profile name |
+| `--url` | | API URL override |
+| `--api-key` | | API key override |
+| `--version` | `-V` | Show version |
+
+## Commands
+
+### config
+- `kctl-payload config init` — Initialize CLI configuration
+- `kctl-payload config show` — Show configuration (keys masked)
+- `kctl-payload config test` — Test API connection
+
+### collections
+- `kctl-payload collections list` — List documents in a collection
+- `kctl-payload collections get` — Get a single document by ID
+- `kctl-payload collections create` — Create a new document in a collection
+- `kctl-payload collections update` — Update an existing document
+- `kctl-payload collections delete` — Delete a document from a collection
+- `kctl-payload collections query` — Query a collection with advanced filters
+
+### media
+- `kctl-payload media list` — List media files
+- `kctl-payload media upload` — Upload a media file (multipart form)
+- `kctl-payload media delete` — Delete a media file
+
+### globals
+- `kctl-payload globals get` — Get a global document
+- `kctl-payload globals update` — Update a global document
+
+### users
+- `kctl-payload users list` — List users
+- `kctl-payload users create` — Create a new user
+
+### doctor
+- `kctl-payload doctor` — Run diagnostic checks
+
+## Configuration
+
+Service key: `payload` in `~/.config/kodemeio/config.yaml`
+
+```yaml
+profiles:
+  terakidz:
+    payload:
+      url: https://cms.terakidz.com
+      api_key: <key>
+```

kctl_payload-0.6.1/src/kctl_payload/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-payload: Kodemeio Payload CMS CLI."""
+
+__version__ = "0.6.1"

kctl_payload-0.6.1/src/kctl_payload/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as: python -m kctl_payload."""
+
+from kctl_payload.cli import _run
+
+_run()

kctl_payload-0.6.1/src/kctl_payload/cli.py

@@ -0,0 +1,97 @@
+"""Main CLI entry point for kctl-payload."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+from kctl_lib import KctlError, handle_cli_error
+
+from kctl_payload import __version__
+from kctl_payload.commands.collections import app as collections_app
+from kctl_payload.commands.config_cmd import app as config_app
+from kctl_payload.commands.doctor import app as doctor_app
+from kctl_payload.commands.globals_cmd import app as globals_app
+from kctl_payload.commands.media import app as media_app
+from kctl_payload.commands.users import app as users_app
+from kctl_payload.core.callbacks import AppContext
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-payload {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-payload",
+    help="Kodemeio Payload CMS CLI - manage your Payload CMS instance.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output as JSON (shortcut for --format json)")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress info messages")] = False,
+    output_format: Annotated[
+        str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml")
+    ] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit headers in CSV output")] = False,
+    debug: Annotated[bool, typer.Option("--debug", help="Enable debug logging")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile name")] = None,
+    url: Annotated[str | None, typer.Option("--url", help="API URL override")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key", help="API key override")] = None,
+    version: Annotated[
+        bool, typer.Option("--version", "-V", callback=version_callback, is_eager=True, help="Show version")
+    ] = False,
+) -> None:
+    """Kodemeio Payload CMS CLI."""
+    import os
+
+    if debug:
+        os.environ["KCTL_DEBUG"] = "1"
+
+    effective_format = "json" if json_output else output_format
+
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output or effective_format == "json",
+        quiet=quiet,
+        format=effective_format,
+        no_header=no_header,
+        debug=debug,
+        profile=profile,
+        url_override=url,
+        api_key_override=api_key,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-payload", __version__)
+
+
+# ---------------------------------------------------------------------------
+# Command groups
+# ---------------------------------------------------------------------------
+app.add_typer(config_app, name="config")
+app.add_typer(collections_app, name="collections")
+app.add_typer(media_app, name="media")
+app.add_typer(globals_app, name="globals")
+app.add_typer(users_app, name="users")
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="payload", version=__version__)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+
+
+if __name__ == "__main__":
+    _run()

kctl_payload-0.6.1/src/kctl_payload/commands/collections.py

@@ -0,0 +1,155 @@
+"""Collection management commands for Payload CMS.
+
+Supports CRUD operations on any Payload collection via REST API.
+Known collections: blog-posts, testimonials, faqs, pages, campaigns, media
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from kctl_payload.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Payload CMS collections.")
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    collection: Annotated[str, typer.Argument(help="Collection slug (e.g. blog-posts, pages)")],
+    status: Annotated[str | None, typer.Option("--status", "-s", help="Filter by _status field")] = None,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Number of items to return")] = 10,
+    page: Annotated[int, typer.Option("--page", help="Page number")] = 1,
+) -> None:
+    """List documents in a collection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str | int] = {"limit": limit, "page": page}
+    if status:
+        params["where[_status][equals]"] = status
+
+    result = c.client.get(f"/{collection}", params=params)
+    docs = result.get("docs", []) if isinstance(result, dict) else result
+    out.table(
+        docs,
+        columns=["id", "title", "slug", "_status", "createdAt", "updatedAt"],
+        title=f"{collection} (page {page})",
+    )
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    collection: Annotated[str, typer.Argument(help="Collection slug")],
+    doc_id: Annotated[str, typer.Argument(help="Document ID")],
+) -> None:
+    """Get a single document by ID."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get(f"/{collection}/{doc_id}")
+    out.raw_json(result)
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    collection: Annotated[str, typer.Argument(help="Collection slug")],
+    data: Annotated[str, typer.Option("--data", "-d", help="JSON string of document data")],
+) -> None:
+    """Create a new document in a collection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as e:
+        out.error(f"Invalid JSON: {e}")
+        raise typer.Exit(1) from e
+
+    result = c.client.post(f"/{collection}", json=payload)
+    doc = result.get("doc", result) if isinstance(result, dict) else result
+    out.success(f"Created document in {collection}")
+    out.raw_json(doc)
+
+
+@app.command()
+def update(
+    ctx: typer.Context,
+    collection: Annotated[str, typer.Argument(help="Collection slug")],
+    doc_id: Annotated[str, typer.Argument(help="Document ID")],
+    data: Annotated[str, typer.Option("--data", "-d", help="JSON string of fields to update")],
+) -> None:
+    """Update an existing document."""
+    c: AppContext = ctx.obj
+    out = c.output
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as e:
+        out.error(f"Invalid JSON: {e}")
+        raise typer.Exit(1) from e
+
+    result = c.client.patch(f"/{collection}/{doc_id}", json=payload)
+    doc = result.get("doc", result) if isinstance(result, dict) else result
+    out.success(f"Updated document {doc_id} in {collection}")
+    out.raw_json(doc)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    collection: Annotated[str, typer.Argument(help="Collection slug")],
+    doc_id: Annotated[str, typer.Argument(help="Document ID")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation")] = False,
+) -> None:
+    """Delete a document from a collection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    if not force:
+        typer.confirm(f"Delete document {doc_id} from {collection}?", abort=True)
+
+    c.client.delete(f"/{collection}/{doc_id}")
+    out.success(f"Deleted document {doc_id} from {collection}")
+
+
+@app.command()
+def query(
+    ctx: typer.Context,
+    collection: Annotated[str, typer.Argument(help="Collection slug")],
+    where: Annotated[str | None, typer.Option("--where", "-w", help="Payload where query as JSON")] = None,
+    sort: Annotated[str | None, typer.Option("--sort", help="Sort field (prefix with - for desc)")] = None,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Number of items to return")] = 10,
+    page: Annotated[int, typer.Option("--page", help="Page number")] = 1,
+) -> None:
+    """Query a collection with advanced filters."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str | int] = {"limit": limit, "page": page}
+    if sort:
+        params["sort"] = sort
+
+    # Parse where clause from JSON into Payload query params
+    if where:
+        try:
+            where_obj = json.loads(where)
+            # Flatten where object into query params
+            for field_name, conditions in where_obj.items():
+                if isinstance(conditions, dict):
+                    for op, val in conditions.items():
+                        params[f"where[{field_name}][{op}]"] = val
+                else:
+                    params[f"where[{field_name}][equals]"] = conditions
+        except json.JSONDecodeError as e:
+            out.error(f"Invalid JSON in --where: {e}")
+            raise typer.Exit(1) from e
+
+    result = c.client.get(f"/{collection}", params=params)
+    docs = result.get("docs", []) if isinstance(result, dict) else result
+    total = result.get("totalDocs", "?") if isinstance(result, dict) else "?"
+    out.info(f"Found {total} documents (showing page {page})")
+    out.table(
+        docs,
+        columns=["id", "title", "slug", "_status", "createdAt"],
+        title=f"{collection} query results",
+    )

kctl_payload-0.6.1/src/kctl_payload/commands/config_cmd.py

@@ -0,0 +1,105 @@
+"""Configuration management commands."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from kctl_payload.core.callbacks import AppContext
+from kctl_payload.core.config import (
+    CONFIG_FILE,
+    SERVICE_KEY,
+    ServiceConfig,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    resolve_active_profile_name,
+    set_default_profile,
+    set_service_config,
+)
+
+app = typer.Typer(help="Manage CLI configuration and profiles.")
+
+
+def _mask(val: str) -> str:
+    if not val:
+        return "[dim]not set[/dim]"
+    return f"{val[:4]}{'*' * max(0, len(val) - 8)}{val[-4:]}" if len(val) > 10 else "****"
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    url: Annotated[str | None, typer.Option("--url")] = None,
+    api_key: Annotated[str | None, typer.Option("--api-key")] = None,
+    name: Annotated[str | None, typer.Option("--name", "-n")] = None,
+) -> None:
+    """Initialize CLI configuration."""
+    c: AppContext = ctx.obj
+    out = c.output
+    profile_name = name or typer.prompt("Profile name", default="kodemeio")
+    api_url = url or typer.prompt("Payload CMS URL (e.g. https://cms.example.com)")
+    key = api_key or typer.prompt("API key", hide_input=True)
+
+    svc = ServiceConfig(url=api_url, api_key=key)
+    set_service_config(profile_name, svc)
+    if len(get_profile_names()) <= 1:
+        set_default_profile(profile_name)
+    out.success(f"Configuration saved to {CONFIG_FILE}")
+    out.kv("Profile", profile_name)
+    out.kv("URL", api_url)
+    out.kv("API Key", _mask(key))
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show configuration (keys masked)."""
+    c: AppContext = ctx.obj
+    out = c.output
+    default = get_default_profile()
+    sections = [
+        (
+            "General",
+            [
+                ("Config file", str(CONFIG_FILE)),
+                ("Default profile", default),
+                ("Service key", SERVICE_KEY),
+            ],
+        )
+    ]
+    for pname in get_profile_names():
+        marker = " [green](default)[/green]" if pname == default else ""
+        services = get_all_services_in_profile(pname)
+        kvs = []
+        for svc_name, svc_data in services.items():
+            if not isinstance(svc_data, dict):
+                continue
+            indicator = "[green]●[/green]" if svc_name == SERVICE_KEY else "[dim]○[/dim]"
+            kvs.append(
+                (
+                    f"{indicator} {svc_name}",
+                    f"{svc_data.get('url', '')}  key: {_mask(svc_data.get('api_key', ''))}",
+                )
+            )
+        sections.append((f"Profile: {pname}{marker}", kvs or [("(empty)", "")]))
+    out.detail("Configuration", sections)
+
+
+@app.command()
+def test(ctx: typer.Context) -> None:
+    """Test API connection."""
+    c: AppContext = ctx.obj
+    out = c.output
+    active = resolve_active_profile_name(c.profile)
+    out.info(f"Testing profile '{active}' → {SERVICE_KEY}")
+    try:
+        status = c.client.check_health()
+        if status == 200:
+            out.success("Connected to Payload CMS API")
+        else:
+            out.error(f"Connection failed: HTTP {status}")
+            raise typer.Exit(1)
+    except Exception as e:
+        out.error(f"Connection failed: {e}")
+        raise typer.Exit(1) from e

kctl_payload-0.6.1/src/kctl_payload/commands/doctor.py

@@ -0,0 +1,82 @@
+"""Doctor diagnostic checks for kctl-payload."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import typer
+
+from kctl_payload.core.callbacks import AppContext
+from kctl_lib.doctor_base import CheckResult, DoctorCheck, run_doctor
+
+
+@dataclass
+class APIConnectivityCheck:
+    """Check that the configured API endpoint is reachable."""
+
+    name: str = "API Connectivity"
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_payload.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name()
+            cfg = get_service_config(profile)
+            url = cfg.url or ""
+            if not url:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No URL configured",
+                    fix_command="kctl-payload config init",
+                )
+            return CheckResult(name=self.name, status="ok", message=f"URL: {url}")
+        except Exception as e:
+            return CheckResult(name=self.name, status="warn", message=str(e))
+
+
+@dataclass
+class AuthCheck:
+    """Check that authentication credentials are configured."""
+
+    name: str = "Authentication"
+
+    def run(self) -> CheckResult:
+        try:
+            from kctl_payload.core.config import get_service_config, resolve_active_profile_name
+
+            profile = resolve_active_profile_name()
+            cfg = get_service_config(profile)
+            token = cfg.api_key or ""
+            if not token:
+                return CheckResult(
+                    name=self.name,
+                    status="fail",
+                    message="No API key configured",
+                    fix_command="kctl-payload config init",
+                )
+            masked = token[:4] + "****" + token[-4:] if len(token) > 8 else "****"
+            return CheckResult(name=self.name, status="ok", message=f"API key configured ({masked})")
+        except Exception as e:
+            return CheckResult(name=self.name, status="warn", message=str(e))
+
+
+app = typer.Typer(help="Run diagnostic checks.", no_args_is_help=False, invoke_without_command=True)
+
+
+@app.callback(invoke_without_command=True)
+def doctor(ctx: typer.Context) -> None:
+    """Run all diagnostic checks."""
+    if ctx.invoked_subcommand is not None:
+        return
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    checks: list[DoctorCheck] = [
+        APIConnectivityCheck(),
+        AuthCheck(),
+    ]
+
+    all_passed = run_doctor(checks, out)  # type: ignore[arg-type]
+    if not all_passed:
+        raise typer.Exit(code=1)

kctl_payload-0.6.1/src/kctl_payload/commands/globals_cmd.py

@@ -0,0 +1,48 @@
+"""Globals management commands for Payload CMS.
+
+Supports get and update operations on global documents.
+Known globals: site-settings, navigation
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from kctl_payload.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Payload CMS globals.")
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    slug: Annotated[str, typer.Argument(help="Global slug (e.g. site-settings, navigation)")],
+) -> None:
+    """Get a global document."""
+    c: AppContext = ctx.obj
+    out = c.output
+    result = c.client.get(f"/globals/{slug}")
+    out.raw_json(result)
+
+
+@app.command()
+def update(
+    ctx: typer.Context,
+    slug: Annotated[str, typer.Argument(help="Global slug (e.g. site-settings, navigation)")],
+    data: Annotated[str, typer.Option("--data", "-d", help="JSON string of fields to update")],
+) -> None:
+    """Update a global document."""
+    c: AppContext = ctx.obj
+    out = c.output
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as e:
+        out.error(f"Invalid JSON: {e}")
+        raise typer.Exit(1) from e
+
+    result = c.client.patch(f"/globals/{slug}", json=payload)
+    out.success(f"Updated global '{slug}'")
+    out.raw_json(result)

kctl_payload-0.6.1/src/kctl_payload/commands/media.py

@@ -0,0 +1,85 @@
+"""Media management commands for Payload CMS.
+
+Supports listing, uploading, and deleting media files.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from kctl_payload.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Payload CMS media files.")
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Number of items to return")] = 10,
+    page: Annotated[int, typer.Option("--page", help="Page number")] = 1,
+) -> None:
+    """List media files."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str | int] = {"limit": limit, "page": page}
+
+    result = c.client.get("/media", params=params)
+    docs = result.get("docs", []) if isinstance(result, dict) else result
+    out.table(
+        docs,
+        columns=["id", "filename", "mimeType", "filesize", "createdAt"],
+        title=f"Media (page {page})",
+    )
+
+
+@app.command()
+def upload(
+    ctx: typer.Context,
+    file_path: Annotated[Path, typer.Argument(help="Path to file to upload")],
+    alt: Annotated[str | None, typer.Option("--alt", help="Alt text for the media")] = None,
+) -> None:
+    """Upload a media file (multipart form)."""
+    c: AppContext = ctx.obj
+    out = c.output
+
+    if not file_path.exists():
+        out.error(f"File not found: {file_path}")
+        raise typer.Exit(1)
+
+    import httpx
+
+    # Build multipart upload using raw httpx since APIClient.post is JSON-oriented
+    files = {"file": (file_path.name, file_path.open("rb"))}
+    data: dict[str, str] = {}
+    if alt:
+        data["alt"] = alt
+
+    url = f"{c.client._base_url}/media"
+    headers = {c.client.AUTH_HEADER: f"{c.client.AUTH_PREFIX}{c.client._credential}"}
+
+    response = httpx.post(url, files=files, data=data, headers=headers, timeout=60)
+    response.raise_for_status()
+    result = response.json()
+
+    doc = result.get("doc", result) if isinstance(result, dict) else result
+    out.success(f"Uploaded {file_path.name}")
+    out.raw_json(doc)
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    media_id: Annotated[str, typer.Argument(help="Media document ID")],
+    force: Annotated[bool, typer.Option("--force", "-f", help="Skip confirmation")] = False,
+) -> None:
+    """Delete a media file."""
+    c: AppContext = ctx.obj
+    out = c.output
+    if not force:
+        typer.confirm(f"Delete media {media_id}?", abort=True)
+
+    c.client.delete(f"/media/{media_id}")
+    out.success(f"Deleted media {media_id}")

kctl_payload-0.6.1/src/kctl_payload/commands/users.py

@@ -0,0 +1,58 @@
+"""User management commands for Payload CMS."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from kctl_payload.core.callbacks import AppContext
+
+app = typer.Typer(help="Manage Payload CMS users.")
+
+
+@app.command("list")
+def list_cmd(
+    ctx: typer.Context,
+    limit: Annotated[int, typer.Option("--limit", "-l", help="Number of items to return")] = 10,
+    page: Annotated[int, typer.Option("--page", help="Page number")] = 1,
+) -> None:
+    """List users."""
+    c: AppContext = ctx.obj
+    out = c.output
+    params: dict[str, str | int] = {"limit": limit, "page": page}
+
+    result = c.client.get("/users", params=params)
+    docs = result.get("docs", []) if isinstance(result, dict) else result
+    out.table(
+        docs,
+        columns=["id", "email", "name", "role", "createdAt"],
+        title=f"Users (page {page})",
+    )
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    email: Annotated[str, typer.Option("--email", "-e", help="User email")],
+    password: Annotated[str, typer.Option("--password", "-p", help="User password", hide_input=True)],
+    data: Annotated[str | None, typer.Option("--data", "-d", help="Additional user data as JSON")] = None,
+) -> None:
+    """Create a new user."""
+    c: AppContext = ctx.obj
+    out = c.output
+    payload: dict = {"email": email, "password": password}
+
+    if data:
+        try:
+            extra = json.loads(data)
+            payload.update(extra)
+        except json.JSONDecodeError as e:
+            out.error(f"Invalid JSON in --data: {e}")
+            raise typer.Exit(1) from e
+
+    result = c.client.post("/users", json=payload)
+    doc = result.get("doc", result) if isinstance(result, dict) else result
+    out.success(f"Created user {email}")
+    out.raw_json(doc)

kctl_payload-0.6.1/src/kctl_payload/core/callbacks.py

@@ -0,0 +1,39 @@
+"""Typer global callback and shared context for kctl-payload.
+
+Subclasses AppContextBase from kctl-lib with Payload CMS-specific fields.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from kctl_lib.callbacks import AppContextBase
+
+from kctl_payload.core.client import PayloadClient
+from kctl_payload.core.config import resolve_connection
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Payload CMS-specific application context."""
+
+    debug: bool = False
+    url_override: str | None = None
+    api_key_override: str | None = None
+    _client: PayloadClient | None = field(default=None, repr=False, init=False)
+
+    @property
+    def client(self) -> PayloadClient:
+        if self._client is None:
+            url, api_key = resolve_connection(
+                profile_name=self.profile,
+                url_override=self.url_override,
+                api_key_override=self.api_key_override,
+            )
+            self._client = PayloadClient(base_url=url, api_key=api_key)
+        return self._client
+
+    def close(self) -> None:
+        """Close underlying HTTP client."""
+        if self._client is not None:
+            self._client.close()

kctl_payload-0.6.1/src/kctl_payload/core/client.py

@@ -0,0 +1,62 @@
+"""Payload CMS API client, subclassing kctl-lib's APIClient.
+
+Provides Payload-specific auth (Authorization: users API-Key <key>),
+retry support, and health check functionality.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from kctl_lib.api_client import APIClient
+from kctl_lib.exceptions import ConfigError
+
+
+class PayloadClient(APIClient):
+    """Synchronous httpx client for Payload CMS API with retry support."""
+
+    AUTH_HEADER = "Authorization"
+    AUTH_PREFIX = "users API-Key "
+    API_PREFIX = "/api"
+
+    def __init__(
+        self,
+        base_url: str = "",
+        api_key: str = "",
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        retry_base_delay: float = 2.0,
+        retry_max_delay: float = 60.0,
+        **kwargs: Any,
+    ):
+        if not base_url:
+            raise ConfigError("No URL configured. Run: kctl-payload config init")
+
+        super().__init__(
+            base_url=base_url,
+            credential=api_key or "unset",
+            timeout=timeout,
+            retry_enabled=True,
+            max_retries=max_retries,
+            retry_base_delay=retry_base_delay,
+            retry_max_delay=retry_max_delay,
+            **kwargs,
+        )
+
+    @property
+    def root_url(self) -> str:
+        """Public accessor for the root URL (without /api)."""
+        return self._base_url.rsplit("/api", 1)[0]
+
+    def check_health(self) -> int:
+        """Check health by hitting /api/globals/site-settings, returns HTTP status code."""
+        try:
+            r = httpx.get(
+                f"{self._base_url}/globals/site-settings",
+                headers={self.AUTH_HEADER: f"{self.AUTH_PREFIX}{self._credential}"},
+                timeout=5,
+            )
+            return r.status_code
+        except httpx.HTTPError:
+            return 0

kctl_payload-0.6.1/src/kctl_payload/core/config.py

@@ -0,0 +1,134 @@
+"""Profile management and configuration resolution for kctl-payload.
+
+Delegates to kctl-lib's config framework with Payload CMS-specific settings.
+"""
+
+from __future__ import annotations
+
+import os
+
+from kctl_lib.config import (
+    CONFIG_DIR,
+    CONFIG_FILE,
+    ConfigFile,
+    expand_env,
+    get_all_services_in_profile,
+    get_default_profile,
+    get_profile_names,
+    is_service_scoped,
+    load_config,
+    load_raw_config,
+    remove_profile,
+    save_raw_config,
+    set_default_profile,
+)
+from kctl_lib.config import get_service_config as _get_service_config
+from kctl_lib.config import (
+    resolve_active_profile_name as _resolve_active_profile_name,
+)
+from kctl_lib.config import set_service_config as _set_service_config
+from pydantic import BaseModel
+
+# This CLI's service key within a profile
+SERVICE_KEY = "payload"
+
+# Environment variable prefix for this CLI
+ENV_PREFIX = "KCTL_PAYLOAD"
+
+__all__ = [
+    "CONFIG_DIR",
+    "CONFIG_FILE",
+    "ConfigFile",
+    "SERVICE_KEY",
+    "ServiceConfig",
+    "get_all_services_in_profile",
+    "get_default_profile",
+    "get_profile_names",
+    "get_service_config",
+    "is_service_scoped",
+    "load_config",
+    "load_raw_config",
+    "remove_profile",
+    "resolve_active_profile_name",
+    "resolve_connection",
+    "save_raw_config",
+    "set_default_profile",
+    "set_service_config",
+]
+
+
+class ServiceConfig(BaseModel):
+    """Payload CMS service-specific config within a profile."""
+
+    url: str = ""
+    api_key: str = ""
+
+
+def get_service_config(profile_name: str) -> ServiceConfig:
+    """Get Payload service config from a profile."""
+    raw = _get_service_config(
+        profile_name,
+        SERVICE_KEY,
+        valid_fields=list(ServiceConfig.model_fields.keys()),
+    )
+    if not raw:
+        return ServiceConfig()
+    return ServiceConfig(**raw)
+
+
+def set_service_config(profile_name: str, svc_config: ServiceConfig) -> None:
+    """Write Payload service config into a profile."""
+    svc_data = svc_config.model_dump(exclude_defaults=False)
+    # Remove empty values
+    cleaned = {k: v for k, v in svc_data.items() if v}
+    _set_service_config(profile_name, SERVICE_KEY, cleaned)
+
+
+def _expand_key(api_key: str) -> str:
+    """Expand ${ENV_VAR} references in API key values."""
+    return expand_env(api_key)
+
+
+def resolve_active_profile_name(
+    profile_name: str | None = None,
+) -> str:
+    """Resolve the active profile name from all sources."""
+    return _resolve_active_profile_name(profile_name, ENV_PREFIX)
+
+
+def resolve_connection(
+    profile_name: str | None = None,
+    url_override: str | None = None,
+    api_key_override: str | None = None,
+) -> tuple[str, str]:
+    """Resolve API URL and API key from all sources.
+
+    Priority:
+    1. CLI flags (url_override, api_key_override)
+    2. KCTL_PAYLOAD_URL / KCTL_PAYLOAD_API_KEY env vars
+    3. Profile's payload service config
+    """
+    url = ""
+    api_key = ""
+
+    # 3. Config file profile (service-scoped)
+    pname = resolve_active_profile_name(profile_name)
+    svc = get_service_config(pname)
+    if svc.url:
+        url = svc.url
+    if svc.api_key:
+        api_key = svc.api_key
+
+    # 2. KCTL env vars
+    if env_url := os.environ.get("KCTL_PAYLOAD_URL"):
+        url = env_url
+    if env_key := os.environ.get("KCTL_PAYLOAD_API_KEY"):
+        api_key = env_key
+
+    # 1. CLI flags
+    if url_override:
+        url = url_override
+    if api_key_override:
+        api_key = api_key_override
+
+    return url, api_key

kctl_payload-0.6.1/tests/conftest.py

@@ -0,0 +1,106 @@
+"""Shared test fixtures for kctl-payload tests."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import MagicMock, patch
+
+import pytest
+from typer.testing import CliRunner
+
+from kctl_lib.output import Output
+
+from kctl_payload.core.callbacks import AppContext
+from kctl_payload.core.client import PayloadClient
+
+
+@pytest.fixture
+def runner() -> CliRunner:
+    """Typer CLI test runner."""
+    return CliRunner()
+
+
+@pytest.fixture
+def mock_client() -> MagicMock:
+    """Mocked PayloadClient with predictable responses."""
+    client = MagicMock(spec=PayloadClient)
+    client._root_url = "https://cms.test.io"
+    client._base_url = "https://cms.test.io/api"
+    client._credential = "test-api-key-12345"
+    client.AUTH_HEADER = "Authorization"
+    client.AUTH_PREFIX = "users API-Key "
+    client.check_health.return_value = 200
+    client.get.return_value = {"docs": [], "totalDocs": 0}
+    client.post.return_value = {"doc": {}}
+    client.put.return_value = {"doc": {}}
+    client.patch.return_value = {"doc": {}}
+    client.delete.return_value = {}
+    return client
+
+
+@pytest.fixture
+def app_context(mock_client: MagicMock) -> AppContext:
+    """AppContext with mock client injected."""
+    ctx = AppContext(json_mode=True)
+    ctx._client = mock_client
+    return ctx
+
+
+@pytest.fixture
+def mock_config(tmp_path: Path):
+    """Redirect kctl-lib config to a temp directory."""
+    config_dir = tmp_path / "kodemeio"
+    config_dir.mkdir(parents=True)
+    config_file = config_dir / "config.yaml"
+    config_file.write_text("default_profile: default\nprofiles: {}\n")
+    with patch("kctl_lib.config.CONFIG_FILE", config_file):
+        yield config_file
+
+
+@pytest.fixture
+def mock_output() -> Output:
+    """Output instance for testing."""
+    return Output(json_mode=False, quiet=True, format="pretty")
+
+
+@pytest.fixture
+def mock_context(mock_client: MagicMock, mock_output: Output) -> AppContext:
+    """AppContext with mocked client."""
+    ctx = AppContext(quiet=True)
+    ctx._client = mock_client
+    ctx._output = mock_output
+    return ctx
+
+
+@pytest.fixture
+def sample_blog_posts() -> dict:
+    """Sample Payload CMS blog posts response."""
+    return {
+        "docs": [
+            {
+                "id": "6612a1b2c3d4e5f6a7b8c9d0",
+                "title": "Getting Started with Payload CMS",
+                "slug": "getting-started",
+                "_status": "published",
+                "createdAt": "2026-01-15T10:00:00.000Z",
+                "updatedAt": "2026-01-20T14:30:00.000Z",
+            },
+            {
+                "id": "6612a1b2c3d4e5f6a7b8c9d1",
+                "title": "Advanced Content Modeling",
+                "slug": "advanced-content-modeling",
+                "_status": "draft",
+                "createdAt": "2026-02-01T08:00:00.000Z",
+                "updatedAt": "2026-02-05T11:15:00.000Z",
+            },
+        ],
+        "totalDocs": 2,
+        "limit": 10,
+        "totalPages": 1,
+        "page": 1,
+        "pagingCounter": 1,
+        "hasPrevPage": False,
+        "hasNextPage": False,
+        "prevPage": None,
+        "nextPage": None,
+    }

kctl_payload-0.6.1/tests/test_cli.py

@@ -0,0 +1,30 @@
+"""Basic CLI tests for kctl-payload."""
+
+from __future__ import annotations
+
+from typer.testing import CliRunner
+
+from kctl_payload.cli import app
+
+runner = CliRunner()
+
+
+def test_app_exists():
+    assert app is not None
+
+
+def test_help():
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "Usage" in result.output
+
+
+def test_version():
+    result = runner.invoke(app, ["--version"])
+    assert result.exit_code == 0
+
+
+def test_config_help():
+    result = runner.invoke(app, ["config", "--help"])
+    assert result.exit_code == 0
+    assert "Usage" in result.output