plugsync-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{plugsync_cli-0.3.0 → plugsync_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugsync-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Command-line client for plugsync HubSpot connectors -- manage connectors and plugins like code, no repo checkout required
 Author-email: Exelab <hello@plugsync.com>
 License: Proprietary

{plugsync_cli-0.3.0 → plugsync_cli-0.4.0}/plugsync_cli/__init__.py

@@ -1,2 +1,2 @@
 """PluSync CLI — git-like connector management."""
-__version__ = "0.1.0"
+__version__ = "0.4.0"

{plugsync_cli-0.3.0 → plugsync_cli-0.4.0}/plugsync_cli/client.py

@@ -154,6 +154,19 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
+    def config_surface(self) -> dict:
+        """The config catalogue: actions, transforms, when, sources, json_schema.
+
+        `json_schema` is `ConnectorConfigV3.model_json_schema()`, defaults
+        included: it is how `plugsync diff` knows which values the server wrote
+        from a schema default rather than the operator (#1259). Org-scoped
+        auth only -- the catalogue itself is the same for every org.
+        """
+        with self._client() as c:
+            r = c.get(self._url("/config-surface"))
+            r.raise_for_status()
+            return r.json()
+
     def get_version(self, connector_id: str, version: int) -> dict:
         """One published config version, config included (backend VersionResponse)."""
         with self._client() as c:
@@ -175,11 +188,19 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
-    def publish(self, connector_id: str, change_summary: str | None = None) -> dict:
+    def publish(
+        self, connector_id: str, change_summary: str | None = None, force: bool = False,
+    ) -> dict:
+        """`force` (#1367, DX-61): publish a new version even when the draft
+        is identical to the active one - the values a publish resolves (plugin
+        ARN/version, HubSpot schema) can drift without any draft edit. Unrelated
+        to `plugsync push --force`, which discards a concurrent DRAFT edit."""
         with self._client() as c:
             body = {}
             if change_summary:
                 body["change_summary"] = change_summary
+            if force:
+                body["force"] = True
             r = c.post(self._url(f"/connectors/{connector_id}/publish"), json=body)
             r.raise_for_status()
             return r.json()
@@ -255,12 +276,38 @@ class PlugSyncClient:
             r.raise_for_status()
             return r.json()
 
-    def plugin_invoke(self, plugin_id: str, payload: dict) -> dict:
-        """Proxy an invocation to the plugin's Lambda function."""
+    def plugin_invoke(
+        self,
+        plugin_id: str,
+        payload: dict,
+        config: dict | None = None,
+        auth_credential: str | None = None,
+        auth_key: str | None = None,
+    ) -> dict:
+        """Proxy an invocation to the plugin's Lambda function.
+
+        `payload` is the event BODY only -- it lands at `event.payload` on
+        the Lambda side, not the whole PluginPayload envelope (issue #1365).
+        `config` mirrors `event.config`.
+
+        `auth_credential` is a name, never a secret in the clear: the server
+        reads it as an event source name and resolves that source's outbound
+        auth exactly as a real flow does (its credential, auth_type and
+        auth_header), falling back to a stored credential name when the org
+        has no source called that. The event.auth KEY those headers land
+        under is `auth_key` when given, else `auth_credential` itself; that
+        key is also the `auth` capability grant the server requires on the
+        plugin, mirroring what the runtime hands a plugin.
+        """
         with self._client() as c:
             r = c.post(
                 self._url(f"/plugins/{plugin_id}/invoke"),
-                json={"payload": payload},
+                json={
+                    "payload": payload,
+                    "config": config or {},
+                    "auth_credential": auth_credential,
+                    "auth_key": auth_key,
+                },
             )
             r.raise_for_status()
             return r.json()

plugsync_cli-0.4.0/plugsync_cli/commands/diff.py

@@ -0,0 +1,439 @@
+"""plugsync diff -- compare local files against a published version (read-only).
+
+Two bugs made this command report "no changes" no matter what (#1241). It read
+the published side through `export_revision`, an endpoint Plan 6a deleted, and
+it read the local side by packing the directory into a zip whose entries are
+prefixed with the connector name while matching them at the root of the
+archive -- so the local state was always empty, and an empty local state
+diffs clean against anything. Both sides now compare config blobs directly:
+the local directory as `serializer.read_config_directory` returns it, the
+published one as `GET /versions/{v}` returns it. No zip in between.
+
+Then the opposite failure (#1259): the comparison was `json.dumps(sort_keys=
+True)` per item and the answer was the literal string "differs", so a config
+whose only divergence was `on_target_deleted: "skip"` -- a schema default the
+server materializes on every draft write -- read as "six entities modified" to
+an operator deciding whether to publish. A false six is worse than silence.
+
+So the diff is now field-level: it names the keys that differ, with the nested
+path for the ones inside `schemas`/`steps`, and it separates the fields that
+exist only on the server AND hold that field's schema default. Those are the
+server's doing, not the operator's, so they are reported apart and left out of
+the change count. The defaults come from the schema itself (see
+`plugsync_cli.schema_defaults`), never from a list maintained here.
+
+A third bug of the same shape (#1366): a flow with a `plugin` step publishes
+with `function_arn`/`version`/`capabilities` resolved and embedded into
+`step["plugin"]` (`app/services/plugin_resolver.py`), fields the authored
+local form never has. Compared raw, that flow reads as permanently modified,
+forever, even with zero edits. So the published side's plugin steps are
+normalized against the matching local step (by step id) before the field-level
+diff runs, stripping exactly those fields when the local step does not
+declare them -- the same normalization `publish_service.compute_diff` already
+does for the dashboard's draft/version diff (#690), on the same field list,
+read from the same `GET /api/config-surface` (`plugin_embedded_fields`, see
+`plugsync_cli.schema_defaults.plugin_embedded_fields`). A genuine drift (both
+sides declaring the field with different values, e.g. `pull --revision`'d
+files diffed after a plugin re-promotion) is untouched by this and still
+surfaces as a normal change.
+
+Read-only throughout, and no diff result is a failure: whatever this command
+finds -- changes, materialized defaults, nothing at all -- it exits 0, because
+it describes and never gates. `plugsync validate` is the one that fails a
+pipeline. A non-zero exit still comes from not being able to run at all (no
+`.plugsync.yaml`, an unreadable version, an API error), exactly as before #1259:
+nothing here changes which situations exit non-zero.
+"""
+import copy
+import json
+from dataclasses import dataclass
+from typing import Any
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from plugsync_cli.context import build_client, fail, load_context
+from plugsync_cli.schema_defaults import SchemaNode, plugin_embedded_fields, schema_root
+
+console = Console()
+
+# Top-level config keys compared item-by-item (keyed by name) rather than whole.
+COLLECTIONS = {"entities": "entity", "flows": "flow"}
+
+# Keys listed in one Detail cell before the rest is summarized. A row exists to
+# tell an operator where to look, and forty paths in a table cell do not.
+MAX_LISTED_KEYS = 8
+
+
+def _by_name(items) -> dict[str, dict]:
+    return {item["name"]: item for item in items or []}
+
+
+def _differs(left, right) -> bool:
+    return json.dumps(left, sort_keys=True) != json.dumps(right, sort_keys=True)
+
+
+@dataclass(frozen=True)
+class FieldChange:
+    """One key whose value is not the same on both sides.
+
+    `path` is written the way the config reads it -- `schemas.hubspot.
+    on_target_deleted`, `steps[2].action` -- so it can be followed straight
+    into the YAML file the row names.
+    """
+
+    path: str
+    # The published value, carried only for a server default: the row prints it
+    # so the operator can see it is the default and not something surprising.
+    value: Any
+    # Absent from the local files, present in the published config. A superset
+    # of `server_default`: a key can be missing locally for other reasons.
+    only_on_server: bool
+    server_default: bool
+
+
+def _field_changes(
+    local: Any, remote: Any, node: SchemaNode, path: str = ""
+) -> list[FieldChange]:
+    """Every leaf that differs between two config fragments, named by path.
+
+    Lists are walked by index only when both sides are the same length: with a
+    different length there is no honest pairing (an inserted step would report
+    every later one as modified), so the list is reported as one change.
+    """
+    if isinstance(local, dict) and isinstance(remote, dict):
+        changes: list[FieldChange] = []
+        for key in sorted(set(local) | set(remote)):
+            here = f"{path}.{key}" if path else key
+            if key not in local:
+                changes.append(_absent_locally(key, remote[key], node, here))
+            elif key not in remote:
+                changes.append(_changed(here))
+            else:
+                changes.extend(
+                    _field_changes(local[key], remote[key], node.child(key), here)
+                )
+        return changes
+
+    if isinstance(local, list) and isinstance(remote, list) and len(local) == len(remote):
+        member = node.item()
+        changes = []
+        for index, (mine, theirs) in enumerate(zip(local, remote)):
+            changes.extend(_field_changes(mine, theirs, member, f"{path}[{index}]"))
+        return changes
+
+    if _differs(local, remote):
+        return [_changed(path)]
+    return []
+
+
+def _absent_locally(key: str, value: Any, node: SchemaNode, path: str) -> FieldChange:
+    """A key the published config has and the local files do not."""
+    return FieldChange(path, value, True, node.is_default(key, value))
+
+
+def _changed(path: str) -> FieldChange:
+    """A difference that is the operator's own: an edited or dropped value."""
+    return FieldChange(path, None, False, False)
+
+
+def _compact(value: Any) -> str:
+    try:
+        return json.dumps(value, sort_keys=True)
+    except (TypeError, ValueError):
+        return repr(value)
+
+
+def _join(parts: list[str]) -> str:
+    if len(parts) <= MAX_LISTED_KEYS:
+        return ", ".join(parts)
+    listed = ", ".join(parts[:MAX_LISTED_KEYS])
+    return f"{listed}, and {len(parts) - MAX_LISTED_KEYS} more"
+
+
+def _rows(prefix: str, scope: str, fields: list[FieldChange]) -> list[dict]:
+    """Up to two rows for one item: the operator's changes, and the server's.
+
+    Split rather than merged so an item that has both -- a real edit plus a
+    materialized default -- shows the edit on its own line and in the count,
+    with the default visible but not inflating it.
+    """
+    mine = [field for field in fields if not field.server_default]
+    theirs = [field for field in fields if field.server_default]
+    rows = []
+    if mine:
+        rows.append(
+            {
+                "type": f"{prefix}_modified",
+                "scope": scope,
+                "detail": _join([field.path for field in mine]),
+                "fields": len(mine),
+                "server_default": False,
+                # Whether naming this row correctly depended on knowing the
+                # schema: with the schema unavailable, some of these keys may
+                # be server defaults reported as the operator's changes.
+                "needs_schema": any(field.only_on_server for field in mine),
+            }
+        )
+    if theirs:
+        rows.append(
+            {
+                "type": f"{prefix}_server_default",
+                "scope": scope,
+                "detail": _join(
+                    [f"{field.path} = {_compact(field.value)}" for field in theirs]
+                ),
+                "fields": len(theirs),
+                "server_default": True,
+                "needs_schema": False,
+            }
+        )
+    return rows
+
+
+def _diff_configs(local: dict, remote: dict, root: SchemaNode) -> list[dict]:
+    """Changes that turn `remote` into `local`, one row per named item or key."""
+    changes: list[dict] = []
+
+    for key, label in COLLECTIONS.items():
+        member = root.child(key).item()
+        local_items, remote_items = _by_name(local.get(key)), _by_name(remote.get(key))
+        for name in sorted(set(local_items) | set(remote_items)):
+            if name not in remote_items:
+                changes.append(_simple(f"{label}_added", name, "only in local files"))
+            elif name not in local_items:
+                changes.append(
+                    _simple(f"{label}_removed", name, "only in the published version")
+                )
+            else:
+                changes.extend(
+                    _rows(
+                        label,
+                        name,
+                        _field_changes(local_items[name], remote_items[name], member),
+                    )
+                )
+
+    scalar_keys = (set(local) | set(remote)) - set(COLLECTIONS)
+    for key in sorted(scalar_keys):
+        if key not in local:
+            fields = [_absent_locally(key, remote[key], root, key)]
+        elif key not in remote:
+            fields = [_changed(key)]
+        else:
+            fields = _field_changes(local[key], remote[key], root.child(key), key)
+        changes.extend(_rows(key, key, fields))
+
+    return changes
+
+
+def _simple(change_type: str, scope: str, detail: str) -> dict:
+    return {
+        "type": change_type,
+        "scope": scope,
+        "detail": detail,
+        "fields": 1,
+        "server_default": False,
+        "needs_schema": False,
+    }
+
+
+def _local_item_count(config: dict) -> int:
+    collections = sum(len(config.get(key) or []) for key in COLLECTIONS)
+    scalars = sum(1 for key, value in config.items() if key not in COLLECTIONS and value)
+    return collections + scalars
+
+
+def _mark(change_type: str) -> str:
+    if change_type.endswith("_added"):
+        return f"[green]+ {change_type}[/green]"
+    if change_type.endswith("_removed"):
+        return f"[red]- {change_type}[/red]"
+    if change_type.endswith("_server_default"):
+        return f"[cyan]= {change_type}[/cyan]"
+    return f"[yellow]~ {change_type}[/yellow]"
+
+
+def _table(changes: list[dict]) -> Table:
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Change", width=26)
+    table.add_column("Item")
+    # fold: a Detail cell now carries dotted key paths, and a path is one word
+    # to a word-wrapper. Ellipsizing it would drop the very end -- the key
+    # name -- which is the part this column exists to show.
+    table.add_column("Detail", overflow="fold")
+    for change in changes:
+        table.add_row(_mark(change["type"]), change["scope"], change["detail"])
+    return table
+
+
+def _render(changes: list[dict], revision: int) -> None:
+    mine = [change for change in changes if not change["server_default"]]
+    defaults = [change for change in changes if change["server_default"]]
+
+    if mine:
+        console.print(
+            f"\n[bold]{len(mine)} change{'' if len(mine) == 1 else 's'} detected[/bold]\n"
+        )
+        console.print(_table(mine))
+    else:
+        console.print(
+            f"[green]No changes of yours. Local files match published "
+            f"v{revision}.[/green]"
+        )
+
+    if defaults:
+        total = sum(change["fields"] for change in defaults)
+        console.print(
+            f"\n[bold]{total} field{'' if total == 1 else 's'} the server filled "
+            "in from a schema default[/bold], absent from your files: written on "
+            "every draft save, not changes you made\n"
+        )
+        console.print(_table(defaults))
+
+
+def _config_surface(client) -> dict:
+    """The `/api/config-surface` catalog, or `{}` if it cannot be had.
+
+    Deliberately swallows everything: this command must keep working against a
+    backend with no `/api/config-surface`, one that answers it with something
+    unexpected, or none at all. Fetched exactly once per run and shared by both
+    consumers that need it -- the JSON Schema (`schema_root`) and the plugin
+    embedded-field list (`plugin_embedded_fields`) -- so a diff against an
+    unreachable API still costs one GET, not two.
+    """
+    try:
+        surface = client.config_surface()
+        return surface if isinstance(surface, dict) else {}
+    except Exception:
+        return {}
+
+
+def _strip_plugin_embedded_fields(
+    remote_flow: dict, local_flow: dict | None, fields: frozenset[str]
+) -> dict:
+    """A deep copy of `remote_flow` with publish-materialized plugin
+    coordinates dropped from any `action == "plugin"` step whose `local_flow`
+    counterpart (matched by step id) does not declare them (#1366).
+
+    Mirrors `publish_service._normalize_plugin_step_fields` (#690), the
+    backend's own fix for the same bug shape one level up (draft vs active
+    version instead of local files vs published version). Scoped strictly to
+    `step["plugin"]` on `action == "plugin"` steps and matched by step id, so a
+    real drift -- both sides declaring the field, with different values --
+    still surfaces as a normal change.
+    """
+    if not fields:
+        return remote_flow
+    local_steps_by_id = {
+        s["id"]: s
+        for s in (local_flow or {}).get("steps", []) or []
+        if isinstance(s, dict) and s.get("id")
+    }
+    normalized = copy.deepcopy(remote_flow)
+    for step in normalized.get("steps", []) or []:
+        if step.get("action") != "plugin" or not step.get("id"):
+            continue
+        plugin_block = step.get("plugin")
+        if not isinstance(plugin_block, dict):
+            continue
+        local_step = local_steps_by_id.get(step["id"]) or {}
+        local_plugin_block = local_step.get("plugin")
+        if not isinstance(local_plugin_block, dict):
+            local_plugin_block = {}
+        for field_name in fields:
+            if field_name in plugin_block and field_name not in local_plugin_block:
+                del plugin_block[field_name]
+    return normalized
+
+
+def _normalize_remote_flows(
+    remote_flows: list, local_flows: list, fields: frozenset[str]
+) -> list:
+    local_by_name = {f["name"]: f for f in local_flows or [] if isinstance(f, dict)}
+    return [
+        _strip_plugin_embedded_fields(f, local_by_name.get(f.get("name")), fields)
+        for f in remote_flows or []
+        if isinstance(f, dict)
+    ]
+
+
+def _warn_defaults_unknown(changes: list[dict]) -> None:
+    """Say why a change may not be one, but only when the doubt is real.
+
+    Fires only if the schema was unavailable AND something differs solely by
+    being absent locally: that is the shape a materialized default has. Any
+    other diff is unaffected by the missing schema and must not drag a warning
+    an operator would learn to skip.
+    """
+    if not any(change["needs_schema"] for change in changes):
+        return
+    console.print(
+        "\n[yellow]Some keys below exist only in the published version. This "
+        "API does not serve the config schema (GET /api/config-surface), so "
+        "the ones the server materialized from a schema default cannot be told "
+        "apart from your own edits. Upgrade the API to see them separated."
+        "[/yellow]"
+    )
+
+
+@click.command()
+@click.argument("path", required=False, default=None)
+@click.option(
+    "--revision",
+    "-r",
+    type=int,
+    default=None,
+    help="Compare against a specific published version (default: the newest)",
+)
+def diff(path: str | None, revision: int | None):
+    """Show what differs between local files and a published version.
+
+    Read-only: nothing is uploaded. To see what a publish would change instead,
+    use `plugsync preview`, which diffs the DRAFT against the active version.
+
+    Each modified item names the keys that differ. Keys the server wrote from a
+    schema default (`on_target_deleted`, `pipelines`, ...) are listed
+    separately and excluded from the change count: they are not your edits.
+
+    Examples:
+        plugsync diff
+        plugsync diff ./hubspot-juve
+        plugsync diff --revision 3
+    """
+    client = build_client()
+    context = load_context(path)
+    local_config = context.config()
+
+    if revision is None:
+        versions = client.list_revisions(context.connector_id)
+        if not versions:
+            console.print("[yellow]No published versions yet. Everything is new.[/yellow]")
+            count = _local_item_count(local_config)
+            console.print(f"[bold]{count} local item(s) would be published.[/bold]")
+            return
+        revision = versions[0]["version"]
+
+    remote_config = client.get_version(context.connector_id, revision)["config"]
+    if not isinstance(remote_config, dict):
+        fail(f"Version {revision} carries no readable config.")
+
+    console.print(f"Comparing local files against published v{revision}...")
+    surface = _config_surface(client)
+    root = schema_root(surface.get("json_schema"))
+    fields = plugin_embedded_fields(surface)
+    if isinstance(remote_config.get("flows"), list):
+        remote_config = {
+            **remote_config,
+            "flows": _normalize_remote_flows(
+                remote_config["flows"], local_config.get("flows"), fields
+            ),
+        }
+    changes = _diff_configs(local_config, remote_config, root)
+    if not changes:
+        console.print(f"[green]No changes. Local files match published v{revision}.[/green]")
+        return
+    _render(changes, revision)
+    if not root.known:
+        _warn_defaults_unknown(changes)

{plugsync_cli-0.3.0 → plugsync_cli-0.4.0}/plugsync_cli/commands/plugin.py

@@ -232,7 +232,29 @@ def plugin_push(path: str | None):
         result = client.plugin_push(plugin_id, bundle_bytes, source_code)
     except httpx.HTTPStatusError as exc:
         _handle_plugin_api_error(exc)
-    console.print(f"[green]Pushed - status: {result.get('status', '?')}[/green]")
+
+    # `result["status"]` is the plugin's PROMOTION status (draft/dev/staging/live/...),
+    # not the outcome of this push -- push never writes Plugin.status itself
+    # (backend/app/api/plugins.py's push_plugin only stores the bundle and enqueues a
+    # deploy_plugin_dev outbox row). Reporting it bare as "Pushed - status: live" reads
+    # as "this push went live", which is false whenever the plugin was already promoted
+    # before this push (issue #1364/DX-58). Spell out what actually happened instead.
+    live_str = result.get("live_version") or "none"
+    staging_str = result.get("staging_version") or "none"
+
+    # Kept as short, separate print() calls on purpose: Rich wraps a single long
+    # logical line at the terminal width (80 cols when not a tty), which would
+    # otherwise fold a real plugin_id (a 36-char UUID) mid-command and make the
+    # printed `plugsync plugin status <id>` hint uncopy-pasteable.
+    console.print("[green]Bundle uploaded, dev deploy enqueued.[/green]")
+    console.print(
+        f"Promotion status: {result.get('status', '?')} "
+        f"(live_version {live_str}, staging_version {staging_str})."
+    )
+    console.print("Run `plugsync plugin promote` to ship it.")
+    console.print("Dev deploy runs asynchronously; it may take a few seconds.")
+    console.print(f"Check outcome: `plugsync plugin status {plugin_id}`")
+    console.print(f"or `plugsync plugin logs {plugin_id}`.")
 
 
 # ---------------------------------------------------------------------------
@@ -331,10 +353,15 @@ def plugin_status_cmd(plugin_id: str):
 
     info = client.plugin_status(plugin_id)
     console.print(f"[bold]{info.get('name', plugin_id)}[/bold]")
-    console.print(f"  id:     {info.get('id', plugin_id)}")
-    console.print(f"  status: {info.get('status', '?')}")
+    console.print(f"  id:              {info.get('id', plugin_id)}")
+    console.print(f"  status:          {info.get('status', '?')}")
+    console.print(f"  staging_version: {info.get('staging_version') or 'none'}")
+    console.print(f"  live_version:    {info.get('live_version') or 'none'}")
+    console.print(f"  function_arn:    {info.get('function_arn') or 'none'}")
+    if info.get("error_message"):
+        console.print(f"  error_message:   {info['error_message']}")
     if info.get("bundle_hash"):
-        console.print(f"  hash:   {info['bundle_hash'][:12]}...")
+        console.print(f"  hash:            {info['bundle_hash'][:12]}...")
 
 
 # ---------------------------------------------------------------------------
@@ -422,13 +449,49 @@ def plugin_metrics_cmd(plugin_id: str, window: str):
     "--payload",
     "-p",
     default="{}",
-    help='JSON payload to send (default: "{}").',
+    help=(
+        'JSON event BODY to send (default: "{}"). This is only the '
+        "`payload` key of the PluginPayload your handler receives -- it "
+        "lands at event.payload, NOT the whole envelope. Use --config and "
+        "--auth for the other keys a plugin can read."
+    ),
 )
-def plugin_invoke_cmd(plugin_id: str, payload: str):
+@click.option(
+    "--config",
+    "-c",
+    default=None,
+    help=(
+        "JSON object to send as event.config, mirroring a step's authored "
+        "`plugin.config` (default: {})."
+    ),
+)
+@click.option(
+    "--auth",
+    "-a",
+    "auth",
+    default=None,
+    help=(
+        "Name of an event source (NOT a secret) whose outbound auth the "
+        "server resolves into headers, exactly as a real flow resolves it: "
+        "the source's own credential, auth_type and auth_header. The "
+        "headers land at event.auth[<source-name>], the key a real `auth` "
+        "capability grant uses, and the plugin must declare that grant "
+        "(`auth:<source-name>`) or the invoke is refused. Two more forms: "
+        "`<credential-name>`, used when no source of your org carries that "
+        "name, resolves a stored credential with the default header for "
+        "its type; `<source-name>=<credential-name>` pins that credential "
+        "onto the named source's header shape."
+    ),
+)
+def plugin_invoke_cmd(plugin_id: str, payload: str, config: str | None, auth: str | None):
     """Invoke a plugin with a test payload.
 
     Example:
         plugsync plugin invoke <id> --payload '{"key": "value"}'
+        plugsync plugin invoke <id> --payload '{"key": "value"}' \\
+            --config '{"doc_type": "invoice"}' --auth kvk
+        plugsync plugin invoke <id> --payload '{"key": "value"}' \\
+            --auth kvk=erp_api_key
     """
     try:
         payload_dict = json.loads(payload)
@@ -436,13 +499,37 @@ def plugin_invoke_cmd(plugin_id: str, payload: str):
         console.print(f"[red]Invalid JSON payload: {e}[/red]")
         raise SystemExit(1)
 
+    config_dict: dict = {}
+    if config is not None:
+        try:
+            config_dict = json.loads(config)
+        except json.JSONDecodeError as e:
+            console.print(f"[red]Invalid JSON config: {e}[/red]")
+            raise SystemExit(1)
+
+    # `--auth <name>` (a source name, falling back server-side to a credential
+    # name when the org has no source called that) or `--auth <source>=<cred>`
+    # (an explicit credential pinned onto that source's header shape). Either
+    # way the part before the "=" -- or the whole value -- is the event.auth
+    # key AND the `auth` capability grant the server requires.
+    auth_credential = auth
+    auth_key: str | None = None
+    if auth is not None and "=" in auth:
+        auth_key, auth_credential = auth.split("=", 1)
+        if not auth_key or not auth_credential:
+            console.print(
+                "[red]Invalid --auth: expected <source-name>=<credential-name>, "
+                f"got {auth!r}[/red]"
+            )
+            raise SystemExit(1)
+
     try:
         client = PlugSyncClient()
     except RuntimeError as e:
         console.print(f"[red]{e}[/red]")
         raise SystemExit(1)
 
-    result = client.plugin_invoke(plugin_id, payload_dict)
+    result = client.plugin_invoke(plugin_id, payload_dict, config_dict, auth_credential, auth_key)
     console.print(json.dumps(result, indent=2))