dailybot-cli 3.0.2__tar.gz → 3.1.0__tar.gz

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dailybot-cli
-Version: 3.0.2
+Version: 3.1.0
 Summary: Dailybot CLI - The command-line bridge between humans and agents. Progress reports, observability, and workflow automation for modern teams across Slack, Google Chat, Discord, MS Teams, and more.
 Author-email: Dailybot <support@dailybot.com>
 License: MIT
@@ -489,8 +489,8 @@ dailybot kudos list --filter KUDOS_RECEIVED
 dailybot kudos list --filter KUDOS_GIVEN --since 2026-01-01 --until 2026-06-30
 dailybot kudos list --search "release" --all --json
 
-# Org-wide kudos stats
-dailybot kudos org --json
+# Every kudos in the organization (admin-only)
+dailybot kudos org --page-size 20 --since 2026-07-01
 
 # Leaderboard of top kudos recipients
 dailybot kudos wall-of-fame --limit 10
@@ -499,9 +499,9 @@ dailybot kudos wall-of-fame --limit 10
 `dailybot kudos list` accepts the shared list flags (pagination, `--search`, and
 date filters) — see [Listing, search, and pagination](#listing-search-and-pagination).
 
-> `dailybot kudos org` is **API-key-only**: the org-stats endpoint rejects a CLI
-> login (Bearer) session with `403`. Set `DAILYBOT_API_KEY` (or
-> `dailybot config key=...`) before running it.
+> `dailybot kudos org` is **admin-only** and shows the whole organization's kudos
+> feed, where `dailybot kudos list` shows only the ones you gave or received. It
+> accepts the same list flags.
 
 ---
 
@@ -564,7 +564,7 @@ envelope, and list output prints a `Showing X of N` count footer.
 | Flag | Description |
 |------|-------------|
 | `--page N` | Fetch a specific 1-based page. |
-| `--page-size N` | Results per page (max 200). |
+| `--page-size N` | Results per page (max 100). |
 | `--all` | Fetch every page and merge the results. |
 | `--limit N` | Stop after N results. |
 | `--search TEXT` / `--grep TEXT` | Filter by a search term (max 256 chars, truncated client-side). |
@@ -892,7 +892,7 @@ Replies to agent emails land as messages retrievable via `dailybot agent message
 |---------|-------------|
 | `dailybot kudos give` | Give kudos to a user (`--to`), a team (`--team`), or both |
 | `dailybot kudos list` | List kudos you've received or given (`--filter`, search, date flags) |
-| `dailybot kudos org` | Org-wide kudos stats (**API-key-only**) |
+| `dailybot kudos org` | Every kudos in the organization (**admin-only**) |
 | `dailybot kudos wall-of-fame` | Leaderboard of top kudos recipients (`--limit`) |
 
 ### Team

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/README.md

@@ -450,8 +450,8 @@ dailybot kudos list --filter KUDOS_RECEIVED
 dailybot kudos list --filter KUDOS_GIVEN --since 2026-01-01 --until 2026-06-30
 dailybot kudos list --search "release" --all --json
 
-# Org-wide kudos stats
-dailybot kudos org --json
+# Every kudos in the organization (admin-only)
+dailybot kudos org --page-size 20 --since 2026-07-01
 
 # Leaderboard of top kudos recipients
 dailybot kudos wall-of-fame --limit 10
@@ -460,9 +460,9 @@ dailybot kudos wall-of-fame --limit 10
 `dailybot kudos list` accepts the shared list flags (pagination, `--search`, and
 date filters) — see [Listing, search, and pagination](#listing-search-and-pagination).
 
-> `dailybot kudos org` is **API-key-only**: the org-stats endpoint rejects a CLI
-> login (Bearer) session with `403`. Set `DAILYBOT_API_KEY` (or
-> `dailybot config key=...`) before running it.
+> `dailybot kudos org` is **admin-only** and shows the whole organization's kudos
+> feed, where `dailybot kudos list` shows only the ones you gave or received. It
+> accepts the same list flags.
 
 ---
 
@@ -525,7 +525,7 @@ envelope, and list output prints a `Showing X of N` count footer.
 | Flag | Description |
 |------|-------------|
 | `--page N` | Fetch a specific 1-based page. |
-| `--page-size N` | Results per page (max 200). |
+| `--page-size N` | Results per page (max 100). |
 | `--all` | Fetch every page and merge the results. |
 | `--limit N` | Stop after N results. |
 | `--search TEXT` / `--grep TEXT` | Filter by a search term (max 256 chars, truncated client-side). |
@@ -853,7 +853,7 @@ Replies to agent emails land as messages retrievable via `dailybot agent message
 |---------|-------------|
 | `dailybot kudos give` | Give kudos to a user (`--to`), a team (`--team`), or both |
 | `dailybot kudos list` | List kudos you've received or given (`--filter`, search, date flags) |
-| `dailybot kudos org` | Org-wide kudos stats (**API-key-only**) |
+| `dailybot kudos org` | Every kudos in the organization (**admin-only**) |
 | `dailybot kudos wall-of-fame` | Leaderboard of top kudos recipients (`--limit`) |
 
 ### Team

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/dailybot_cli/api_client.py

@@ -10,14 +10,41 @@ import httpx
 from dailybot_cli.config import get_api_key, get_api_url, get_token
 
 _MAX_LIST_PAGES: int = 50  # safety cap for paginated list endpoints
-DEFAULT_PAGE_SIZE: int = 50  # server default page size for paginated list endpoints
-MAX_PAGE_SIZE: int = 200  # server clamps above this; the client clamps too
+DEFAULT_PAGE_SIZE: int = 25  # server default page size for paginated list endpoints
+MAX_PAGE_SIZE: int = 100  # server clamps above this; the client clamps too
 
 MAX_RATE_LIMIT_RETRIES: int = 3  # attempts to retry a generic 429 before raising
 DEFAULT_RETRY_AFTER_SECS: float = 1.0  # backoff floor when a 429 omits Retry-After
 # A free-plan daily throttle is NOT transient — retrying can never succeed today.
 FREE_PLAN_DAILY_LIMIT_CODE: str = "free_plan_daily_limit_exceeded"
 
+MAX_FALLBACK_DETAIL_CHARS: int = 160  # cap for a non-JSON error body echoed to the user
+
+
+def _fallback_detail(response: httpx.Response) -> str:
+    """Build an error detail when the body is not the expected JSON envelope.
+
+    A 5xx can return a rendered HTML page. Echoing that verbatim floods the
+    terminal and leaks server internals (tracebacks, settings, file paths), so
+    only short non-HTML bodies are surfaced.
+    """
+    content_type: str = response.headers.get("content-type", "")
+    text: str = (response.text or "").strip()
+    if not text or "html" in content_type.lower() or text.startswith("<"):
+        return f"HTTP {response.status_code}"
+    return text[:MAX_FALLBACK_DETAIL_CHARS]
+
+
+def resource_uuid(payload: dict[str, Any]) -> str:
+    """Return a resource's canonical identifier from an API payload.
+
+    The API is mid-migration from ``id`` to ``uuid``: forms and their responses
+    now expose only ``uuid``, agent resources expose both with the same value,
+    and check-ins / kudos / workflows still expose only ``id``. Reading through
+    this helper keeps every caller correct under all three shapes.
+    """
+    return str(payload.get("uuid") or payload.get("id") or "")
+
 
 @dataclass
 class PaginatedResult:
@@ -151,8 +178,11 @@ class DailyBotClient:
                 if isinstance(upgrade_url, str):
                     extra["upgrade_url"] = upgrade_url
             except Exception:
-                detail = response.text or f"HTTP {response.status_code}"
-            if response.status_code in (401, 403) and self._agent_auth_mode == "bearer":
+                detail = _fallback_detail(response)
+            # Only a 401 means the session is unusable. A 403 is an authorization
+            # verdict (wrong role, wrong plan) whose server detail explains the
+            # actual cause — overwriting it sends the user into a re-login loop.
+            if response.status_code == 401 and self._agent_auth_mode == "bearer":
                 detail = "Session expired. Run 'dailybot login' to re-authenticate."
             retry_after: float | None = None
             if response.status_code == 429:
@@ -216,23 +246,19 @@ class DailyBotClient:
         page_size: int | None = None,
         fetch_all: bool = False,
         limit: int | None = None,
-        force_paginated: bool = False,
     ) -> PaginatedResult:
         """GET a list endpoint, tolerating both the DRF envelope and a bare array.
 
         - ``page`` / ``page_size`` are sent when provided; ``page_size`` is clamped
           to ``[1, MAX_PAGE_SIZE]``. ``limit`` is a legacy alias that also caps the
           total number of collected items.
-        - ``force_paginated`` adds ``paginated=true`` to the query — required for the
-          two forms endpoints (``/v1/forms/`` and ``/v1/forms/<uuid>/responses/``)
-          that return a bare array unless asked for the envelope.
         - ``fetch_all`` follows ``next`` (bounded by ``_MAX_LIST_PAGES``); otherwise a
-          single page is returned. A bare-array response has no ``next`` and always
-          terminates after one page.
+          single page is returned.
+        - Every ``/v1`` list endpoint now returns the envelope unconditionally. The
+          bare-array branch below is kept only so an older deployment degrades to a
+          single page instead of raising.
         """
         query: dict[str, Any] = dict(params) if params else {}
-        if force_paginated:
-            query["paginated"] = "true"
         if page is not None:
             query["page"] = page
         effective_page_size: int | None = page_size if page_size is not None else limit
@@ -780,8 +806,8 @@ class DailyBotClient:
     ) -> list[dict[str, Any]]:
         """GET /v1/forms/ — optionally expand questions, search, and page.
 
-        Always requests the envelope (``?paginated=true``). When ``meta`` is given
-        it is populated with ``count`` / ``next`` for a pagination footer.
+        When ``meta`` is given it is populated with ``count`` / ``next`` for a
+        pagination footer.
         """
         params: dict[str, Any] = {}
         if include_questions:
@@ -796,7 +822,6 @@ class DailyBotClient:
             page_size=page_size,
             fetch_all=fetch_all,
             limit=limit,
-            force_paginated=True,
         )
         _fill_meta(meta, result)
         return result.results
@@ -868,7 +893,6 @@ class DailyBotClient:
             page_size=page_size,
             fetch_all=fetch_all,
             limit=limit,
-            force_paginated=True,
         )
         _fill_meta(meta, result)
         return result.results
@@ -1210,6 +1234,8 @@ class DailyBotClient:
         self,
         *,
         search: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
         page: int | None = None,
         page_size: int | None = None,
         fetch_all: bool = True,
@@ -1218,7 +1244,7 @@ class DailyBotClient:
     ) -> list[dict[str, Any]]:
         """GET /v1/workflows/ — list workflows (read-only; plan-gated feature)."""
         params: dict[str, Any] = {}
-        _merge_list_query(params, search=search)
+        _merge_list_query(params, search=search, start_date=start_date, end_date=end_date)
         result: PaginatedResult = self._paginated_get(
             f"{self.api_url}/v1/workflows/",
             params=params,
@@ -1239,14 +1265,35 @@ class DailyBotClient:
         )
         return self._handle_response(response)
 
-    def get_kudos_organization(self) -> dict[str, Any]:
-        """GET /v1/kudos/organization/ — org-wide kudos statistics."""
-        response: httpx.Response = httpx.get(
+    def list_kudos_organization(
+        self,
+        *,
+        search: str | None = None,
+        start_date: str | None = None,
+        end_date: str | None = None,
+        page: int | None = None,
+        page_size: int | None = None,
+        fetch_all: bool = True,
+        limit: int | None = None,
+        meta: dict[str, Any] | None = None,
+    ) -> list[dict[str, Any]]:
+        """GET /v1/kudos/organization/ — every kudos in the org (admin-only).
+
+        The org-wide counterpart of ``list_kudos``, which is scoped to the caller.
+        Returns the same paginated envelope, not an aggregate statistics object.
+        """
+        params: dict[str, Any] = {}
+        _merge_list_query(params, search=search, start_date=start_date, end_date=end_date)
+        result: PaginatedResult = self._paginated_get(
             f"{self.api_url}/v1/kudos/organization/",
-            headers=self._headers(),
-            timeout=self.timeout,
+            params=params,
+            page=page,
+            page_size=page_size,
+            fetch_all=fetch_all,
+            limit=limit,
         )
-        return self._handle_response(response)
+        _fill_meta(meta, result)
+        return result.results
 
     def get_kudos_wall_of_fame(self, *, limit: int | None = None) -> dict[str, Any]:
         """GET /v1/kudos/wall-of-fame/ — leaderboard rankings."""

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/dailybot_cli/commands/checkin.py

@@ -31,7 +31,9 @@ from dailybot_cli.commands.public_api_helpers import (
     enforce_plan_access,
     exit_for_api_error,
     require_auth,
+    validate_user_filter,
 )
+from dailybot_cli.commands.query_options import paging_options
 from dailybot_cli.commands.user_scoped_actions import (
     execute_checkin_complete,
     execute_checkin_edit,
@@ -307,6 +309,7 @@ def checkin_show(followup_uuid: str, json_mode: bool) -> None:
 @click.option(
     "--search", "-s", "search", default=None, help="Filter response content (max 256 chars)."
 )
+@paging_options
 @click.option("--json", "json_mode", is_flag=True, help="Emit machine-readable JSON to stdout.")
 def checkin_history(
     followup_uuid: str,
@@ -315,6 +318,9 @@ def checkin_history(
     date_to: str | None,
     user: str | None,
     search: str | None,
+    page: int | None,
+    page_size: int | None,
+    limit: int | None,
     json_mode: bool,
 ) -> None:
     """Show a check-in's response history.
@@ -330,6 +336,7 @@ def checkin_history(
       dailybot checkin history <followup_uuid> --from 2026-06-01 --to 2026-06-30 --json
       dailybot checkin history <followup_uuid> --user <user_uuid> --days 30
     """
+    validate_user_filter(user)
     client = require_auth()
     execute_checkin_history(
         client,
@@ -339,6 +346,9 @@ def checkin_history(
         date_to=date_to,
         user=user,
         search=search,
+        page=page,
+        page_size=page_size,
+        limit=limit,
         json_mode=json_mode,
     )
 

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/dailybot_cli/commands/form.py

@@ -26,8 +26,13 @@ from dailybot_cli.commands.public_api_helpers import (
     enforce_plan_access,
     exit_for_api_error,
     require_auth,
+    validate_user_filter,
+)
+from dailybot_cli.commands.query_options import (
+    build_query_params,
+    paging_options,
+    query_options,
 )
-from dailybot_cli.commands.query_options import build_query_params, query_options
 from dailybot_cli.commands.user_scoped_actions import (
     execute_form_list,
     execute_form_submit,
@@ -51,6 +56,16 @@ from dailybot_cli.display import (
     print_success,
 )
 
+# The server reuses `invalid_workflow_state` for a malformed `--state
+# "Label:#color"` during authoring. On this listing it means the form has no
+# workflow at all, so the shared message would send the user down the wrong path.
+_RESPONSES_ERROR_OVERRIDES: dict[str, str] = {
+    "invalid_workflow_state": (
+        "This form has no workflow, so --state doesn't apply. Drop the flag, or run "
+        "`dailybot form get <form_uuid>` to see the states a workflow form defines."
+    ),
+}
+
 
 def _maybe_load_form(client: DailyBotClient, form_uuid: str) -> dict[str, Any] | None:
     """Return form metadata if accessible; swallow errors (UI-only enrichment)."""
@@ -293,7 +308,11 @@ def form_submit(
 
 @form.command("responses")
 @click.argument("form_uuid")
-@click.option("--state", default=None, help="Filter by current_state (workflow forms only).")
+@click.option(
+    "--state",
+    default=None,
+    help="Filter by workflow state key (e.g. draft, not Draft). Workflow forms only.",
+)
 @click.option(
     "--all",
     "all_responses",
@@ -313,6 +332,7 @@ def form_submit(
     is_flag=True,
     help="Return only the most recent response (continue where you left off).",
 )
+@paging_options
 @click.option("--json", "json_mode", is_flag=True, help="Emit machine-readable JSON to stdout.")
 def form_responses(
     form_uuid: str,
@@ -323,6 +343,9 @@ def form_responses(
     date_to: str | None,
     search: str | None,
     latest: bool,
+    page: int | None,
+    page_size: int | None,
+    limit: int | None,
     json_mode: bool,
 ) -> None:
     """List responses on a form.
@@ -339,6 +362,7 @@ def form_responses(
       dailybot form responses <form_uuid> --all --from 2026-01-01 --to 2026-06-30
       dailybot form responses <form_uuid> --user <user_uuid> --json
     """
+    validate_user_filter(user)
     client = require_auth()
     truncated_search: str | None = search[:256] if search is not None else None
     meta: dict[str, Any] = {}
@@ -352,10 +376,14 @@ def form_responses(
                 date_from=date_from,
                 date_to=date_to,
                 search=truncated_search,
+                page=page,
+                page_size=page_size,
+                fetch_all=page is None and page_size is None and limit is None,
+                limit=limit,
                 meta=meta,
             )
     except APIError as exc:
-        exit_for_api_error(exc, json_mode)
+        exit_for_api_error(exc, json_mode, code_overrides=_RESPONSES_ERROR_OVERRIDES)
 
     if latest:
         responses = responses[:1] if responses else []
@@ -366,7 +394,12 @@ def form_responses(
 
     form_data: dict[str, Any] | None = _maybe_load_form(client, form_uuid)
     print_form_responses_table(form_uuid, responses, form_data)
-    print_pagination_footer(len(responses), meta.get("count"), has_more=bool(meta.get("next")))
+    print_pagination_footer(
+        len(responses),
+        meta.get("count"),
+        has_more=bool(meta.get("next")),
+        more_hint="omit --page/--page-size to fetch every page",
+    )
 
 
 @form.group("response")

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/dailybot_cli/commands/interactive.py

@@ -10,7 +10,7 @@ import questionary
 from questionary import Choice, Separator
 
 from dailybot_cli import __version__
-from dailybot_cli.api_client import APIError, DailyBotClient
+from dailybot_cli.api_client import APIError, DailyBotClient, resource_uuid
 from dailybot_cli.commands.auth import _do_login
 from dailybot_cli.commands.chat import ChatPayloadError, build_chat_payload
 from dailybot_cli.commands.kudos import execute_kudos_give
@@ -94,7 +94,7 @@ def _checkin_label(checkin: dict[str, Any]) -> str:
 
 
 def _form_label(form: dict[str, Any]) -> str:
-    name: str = str(form.get("name") or form.get("id") or "Form")
+    name: str = str(form.get("name") or resource_uuid(form) or "Form")
     active: bool = bool(form.get("is_active"))
     suffix: str = "" if active else " [inactive]"
     return f"{name}{suffix}"
@@ -269,7 +269,7 @@ def _submit_form(client: DailyBotClient) -> None:
     if selected is None:
         raise InteractiveAbort()
 
-    form_uuid: str = str(selected.get("id") or "")
+    form_uuid: str = resource_uuid(selected)
     form_name: str = str(selected.get("name") or form_uuid)
     if not form_uuid:
         print_error("Selected form has no UUID.")

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/dailybot_cli/commands/kudos.py

@@ -17,7 +17,7 @@ from dailybot_cli.commands.public_api_helpers import (
     resolve_team_by_name_or_uuid,
     resolve_user_by_name_or_uuid,
 )
-from dailybot_cli.commands.query_options import build_query_params, query_options
+from dailybot_cli.commands.query_options import build_query_params, query_options, resolve_fetch_all
 from dailybot_cli.display import (
     console,
     print_detail_panel,
@@ -211,13 +211,6 @@ def kudos_give(
     )
 
 
-_KUDOS_ORG_FIELDS: list[tuple[str, str]] = [
-    ("Total kudos", "total_kudos"),
-    ("Total givers", "total_givers"),
-    ("Total receivers", "total_receivers"),
-]
-
-
 @kudos.command("list")
 @click.option(
     "--filter", "kudos_filter", default=None, help="Filter (e.g. KUDOS_RECEIVED, KUDOS_GIVEN)."
@@ -264,7 +257,7 @@ def kudos_list(
         print_error(str(exc))
         raise SystemExit(EXIT_USAGE_ERROR)
     client = require_auth()
-    resolved_fetch_all: bool = spec.fetch_all or (spec.page is None and spec.limit is None)
+    resolved_fetch_all: bool = resolve_fetch_all(spec)
     meta: dict[str, Any] = {}
     try:
         with console.status("Fetching kudos..."):
@@ -289,26 +282,71 @@ def kudos_list(
 
 
 @kudos.command("org")
+@query_options
 @click.option("--json", "json_mode", is_flag=True, help="Emit machine-readable JSON to stdout.")
-def kudos_org(json_mode: bool) -> None:
-    """Show org-wide kudos statistics.
+def kudos_org(
+    json_mode: bool,
+    page: int | None,
+    page_size: int | None,
+    fetch_all: bool,
+    limit: int | None,
+    search: str | None,
+    since: str | None,
+    until: str | None,
+    on_date: str | None,
+    last_week: bool,
+    today: bool,
+) -> None:
+    """Browse every kudos in the organization (admin only).
+
+    \b
+    The org-wide feed. `kudos list` shows only the ones you gave or received.
+    Non-admins receive a 403.
 
     \b
     Examples:
       dailybot kudos org
-      dailybot kudos org --json
+      dailybot kudos org --page-size 20 --since 2026-07-01
+      dailybot kudos org --search onboarding --json
     """
     enforce_plan_access("kudos_org", json_mode=json_mode)
+    try:
+        spec = build_query_params(
+            page=page,
+            page_size=page_size,
+            fetch_all=fetch_all,
+            limit=limit,
+            search=search,
+            since=since,
+            until=until,
+            on_date=on_date,
+            last_week=last_week,
+            today=today,
+        )
+    except ValueError as exc:
+        print_error(str(exc))
+        raise SystemExit(EXIT_USAGE_ERROR)
     client = require_auth()
+    meta: dict[str, Any] = {}
     try:
-        with console.status("Fetching kudos stats..."):
-            data: dict[str, Any] = client.get_kudos_organization()
+        with console.status("Fetching organization kudos..."):
+            kudos_items: list[dict[str, Any]] = client.list_kudos_organization(
+                search=spec.params.get("search"),
+                start_date=spec.params.get("start_date"),
+                end_date=spec.params.get("end_date"),
+                page=spec.page,
+                page_size=spec.page_size,
+                fetch_all=resolve_fetch_all(spec),
+                limit=spec.limit,
+                meta=meta,
+            )
     except APIError as exc:
         exit_for_api_error(exc, json_mode)
     if json_mode:
-        emit_json(data)
+        emit_json(kudos_items)
         return
-    print_detail_panel("Kudos — Organization", data, _KUDOS_ORG_FIELDS)
+    print_kudos_table(kudos_items)
+    print_pagination_footer(len(kudos_items), meta.get("count"), has_more=bool(meta.get("next")))
 
 
 @kudos.command("wall-of-fame")

{dailybot_cli-3.0.2 → dailybot_cli-3.1.0}/dailybot_cli/commands/public_api_helpers.py

@@ -211,7 +211,8 @@ ERROR_CODE_MESSAGES: dict[str, str] = {
     # `extra` (upgrade_url, required/current role) in exit_for_api_error.
     "plan_upgrade_required": (
         "This action requires a paid Dailybot plan. On the free plan the CLI can "
-        "only submit agent reports, send agent emails, and read your own profile."
+        "only submit agent reports and emails, check agent messages and health, "
+        "read your own profile, and view today's pending check-ins."
     ),
     "plan_free_api_keys_forbidden": (
         "API keys aren't available on the free plan. Run `dailybot login` to use a "
@@ -236,6 +237,10 @@ ERROR_CODE_MESSAGES: dict[str, str] = {
     "invalid_date_range": (
         "Invalid date. Use YYYY-MM-DD, and make sure the start date is on or before the end date."
     ),
+    "invalid_user_identifier": (
+        "--user only accepts a user UUID, not an email or a name. "
+        "Run 'dailybot user list' to find it."
+    ),
     # Rate limiting (429)
     "free_plan_daily_limit_exceeded": (
         "You've reached today's free-plan limit for this action. Wait for it to reset "
@@ -263,6 +268,19 @@ UUID_PATTERN: re.Pattern[str] = re.compile(
 )
 
 
+def validate_user_filter(value: str | None) -> None:
+    """Reject a non-UUID ``--user`` filter before it reaches the API.
+
+    The response-listing endpoints accept only a UUID here. Checking locally
+    turns a round-trip and a 400 into an immediate, actionable message.
+    """
+    if value is None:
+        return
+    if not UUID_PATTERN.match(value):
+        print_error(ERROR_CODE_MESSAGES["invalid_user_identifier"])
+        raise SystemExit(1)
+
+
 def require_auth() -> DailyBotClient:
     """Ensure a login session or API key exists and return a client.
 
@@ -305,18 +323,30 @@ def _augment_code_message(base: str, code: str, extra: dict[str, Any]) -> str:
     return base
 
 
-def exit_for_api_error(exc: APIError, json_mode: bool) -> NoReturn:
+def exit_for_api_error(
+    exc: APIError,
+    json_mode: bool,
+    *,
+    code_overrides: dict[str, str] | None = None,
+) -> NoReturn:
     """Map API failures to user-facing messages and process exit codes.
 
     Dispatches strictly on the machine-readable ``code`` (never on ``detail``
     text); falls back to the status-code-based message when ``code`` is absent
     (older backends).
+
+    ``code_overrides`` lets a command replace the shared message for a code the
+    server reuses across surfaces. ``invalid_workflow_state`` means "malformed
+    --state definition" when authoring a form and "this form has no workflow"
+    when filtering its responses; only the calling command can tell them apart.
     """
     code: str | None = getattr(exc, "code", None)
     extra: dict[str, Any] = getattr(exc, "extra", {}) or {}
     mapped_message: str | None = ERROR_CODE_MESSAGES.get(code) if code else None
     if mapped_message and code:
         mapped_message = _augment_code_message(mapped_message, code, extra)
+    if code and code_overrides and code in code_overrides:
+        mapped_message = code_overrides[code]
 
     if exc.status_code == 401:
         message: str = "Session expired. Run: dailybot login"