secflow-cli 0.1.0__py3-none-any.whl

secflow_cli/__init__.py

@@ -0,0 +1 @@
+"""Independent operator CLI; no server imports or executable replacement."""

secflow_cli/__main__.py

@@ -0,0 +1,3 @@
+from secflow_cli.main import main
+
+raise SystemExit(main())

secflow_cli/access_profile_commands.py

@@ -0,0 +1,94 @@
+"""Default access profile metadata through the existing org-admin API."""
+from collections.abc import Mapping
+from uuid import UUID
+from uuid import uuid4
+import re
+import sys
+
+from secflow_sdk import SecFlowConfigError, SecFlowSdkError
+from secflow_cli.account_commands import required_input
+from secflow_cli.errors import CliError
+
+FLAGS = ("allow_cli_login", "allow_api_session", "allow_namespace_request")
+FIELDS = ("profile_id", "domain", "roles", *FLAGS, "allow_audit_read", "allow_plaintext_read")
+
+
+def add_commands(groups):
+    commands = groups.add_parser("access-profile").add_subparsers(dest="action", required=True)
+    command = commands.add_parser("get")
+    command.add_argument("--token-stdin", action="store_true")
+    command = commands.add_parser("set")
+    command.add_argument("--profile-id")
+    for field in FLAGS:
+        command.add_argument("--" + field.replace("_", "-"), choices=("true", "false"))
+    command.add_argument("--token-stdin", action="store_true")
+    command.add_argument("--idempotency-key")
+    command.add_argument("--yes", action="store_true")
+
+
+def prepare(args):
+    profile_id = required_input(args, "profile_id", "profile ID")
+    try:
+        if str(UUID(profile_id)) != profile_id:
+            raise ValueError
+    except ValueError:
+        raise CliError(2, "INVALID_INPUT", "Supply a canonical profile UUID.") from None
+    profile = dict(profile_id=profile_id, domain="intflow.ai", roles=[], allow_audit_read=False, allow_plaintext_read=False)
+    for field in FLAGS:
+        value = required_input(args, field, field.replace("_", " "))
+        if value not in ("true", "false"):
+            raise CliError(2, "INVALID_INPUT", "Profile settings must be true or false.")
+        profile[field] = value == "true"
+    key = args.idempotency_key or "cli-access-profile-" + str(uuid4())
+    if not re.fullmatch(r"[A-Za-z0-9_.:-]{16,128}", key):
+        raise CliError(2, "INVALID_INPUT", "Supply a normalized idempotency key of 16-128 characters.")
+    print("Replace global default access profile: " + profile_id, file=sys.stderr)
+    for field in FLAGS:
+        print(field + ": " + str(profile[field]).lower(), file=sys.stderr)
+    print("Full replacement; concurrent changes are not protected by a server precondition. This does not grant roles or revoke existing credentials.", file=sys.stderr)
+    if not args.yes:
+        if args.non_interactive or args.token_stdin or not sys.stdin.isatty():
+            raise CliError(2, "CONFIRMATION_REQUIRED", "Supply all settings and --yes for unattended execution or when stdin carries a token.")
+        print("Type the profile ID to confirm: ", end="", file=sys.stderr, flush=True)
+        try:
+            answer = input()
+        except EOFError:
+            answer = None
+        if answer != profile_id:
+            raise CliError(2, "CONFIRMATION_CANCELLED", "Profile replacement cancelled; no mutation was sent.")
+    return dict(profile=profile, idempotency_key=key)
+
+
+def execute(client, values, *, mapped_error):
+    key = values["idempotency_key"]
+    print("Idempotency key: " + key, file=sys.stderr)
+    data = dict(idempotency_key=key, outcome="unknown", profile=None)
+    try:
+        result = metadata(client.put_default_access_profile(**values))
+        if result != values["profile"]:
+            raise CliError(7, "INVALID_RESPONSE", "The server did not confirm the requested profile.")
+        data.update(outcome="confirmed", profile=result)
+        return data, None
+    except (SecFlowSdkError, CliError) as caught:
+        error = mapped_error(caught)
+        if isinstance(caught, SecFlowConfigError):
+            data["outcome"] = "not_sent"
+        elif error.status in (2, 3, 4, 5, 6):
+            data["outcome"] = "not_confirmed"
+        else:
+            error = CliError(7, "MUTATION_OUTCOME_UNKNOWN", "Mutation completion is unknown. Inspect current state; any retry must use identical inputs and the same idempotency key.")
+        return data, error
+
+
+def metadata(value):
+    valid_id = False
+    if isinstance(value, Mapping) and isinstance(value.get("profile_id"), str):
+        try:
+            valid_id = str(UUID(value["profile_id"])) == value["profile_id"]
+        except ValueError:
+            pass
+    if (not valid_id or value.get("domain") != "intflow.ai" or value.get("roles") != []
+            or any(type(value.get(field)) is not bool for field in FLAGS)
+            or value.get("allow_audit_read") is not False or value.get("allow_plaintext_read") is not False):
+        raise CliError(7, "INVALID_RESPONSE", "The server returned an invalid default access profile.")
+    return {field: value[field] for field in FIELDS}

secflow_cli/account_commands.py

@@ -0,0 +1,134 @@
+"""Additive account mutations using existing Admin API contracts."""
+from __future__ import annotations
+
+import re
+import hashlib
+import sys
+from collections.abc import Mapping
+from uuid import UUID, uuid4
+
+from secflow_sdk import SecFlowConfigError, SecFlowSdkError
+
+from secflow_cli.errors import CliError
+
+
+ACTIONS = ("create", "update", "reactivate", "suspend", "delete")
+DESTRUCTIVE_ACTIONS = frozenset({"suspend", "delete"})
+
+
+def add_commands(commands):
+    for action in ACTIONS:
+        command = commands.add_parser(action)
+        command.add_argument("--token-stdin", action="store_true")
+        command.add_argument("--idempotency-key")
+        if action == "create":
+            command.add_argument("--email")
+        else:
+            command.add_argument("--account-id")
+        if action in ("create", "update"):
+            command.add_argument("--display-name")
+        if action in DESTRUCTIVE_ACTIONS:
+            command.add_argument("--yes", action="store_true")
+
+
+def required_input(args, field, label):
+    value = getattr(args, field)
+    if value is None and not args.non_interactive and not args.token_stdin and sys.stdin.isatty():
+        print(label + ": ", end="", file=sys.stderr, flush=True)
+        try:
+            value = input()
+        except EOFError:
+            value = None
+    if not isinstance(value, str) or not value.strip() or value != value.strip():
+        raise CliError(2, "INVALID_INPUT", "Supply a non-empty normalized " + label + ".")
+    return value
+
+
+def prepare(args):
+    """Validate metadata and the retry key before any mutation is sent."""
+    key = args.idempotency_key or "cli-account-" + str(uuid4())
+    if not re.fullmatch(r"[A-Za-z0-9_.:-]{16,128}", key):
+        raise CliError(2, "INVALID_INPUT", "Idempotency keys must contain 16-128 letters, digits, dots, underscores, colons, or hyphens.")
+    values = {"idempotency_key": key}
+    if args.action == "create":
+        values["email"] = required_input(args, "email", "email")
+        # The server digests the complete request, including correlation IDs.
+        # Keep these stable when a user retries in a later CLI process.
+        operation = hashlib.sha256(key.encode("ascii")).hexdigest()
+        values["request_id"] = "cli-request-" + operation
+        values["trace_id"] = "cli-trace-" + operation
+    else:
+        values["account_id"] = required_input(args, "account_id", "account ID")
+    if args.action == "update":
+        values["display_name"] = required_input(args, "display_name", "display name")
+    elif args.action == "create" and args.display_name is not None:
+        values["display_name"] = required_input(args, "display_name", "display name")
+    if args.action == "reactivate":
+        values["status"] = "active"
+    if args.action in DESTRUCTIVE_ACTIONS:
+        confirm_destructive(args, values["account_id"])
+    return values
+
+
+def confirm_destructive(args, account_id):
+    try:
+        if str(UUID(account_id)) != account_id:
+            raise ValueError
+    except ValueError:
+        raise CliError(2, "INVALID_INPUT", "Supply an exact canonical account UUID.") from None
+    print(args.action.capitalize() + " account: " + account_id, file=sys.stderr)
+    impact = (
+        "suspension revokes active Admin sessions and SDK tokens. Reactivation does not restore revoked credentials."
+        if args.action == "suspend" else
+        "deletion removes the account, its sessions, SDK tokens, and direct role bindings."
+    )
+    print("Operation semantics, not a server impact preview: " + impact + " Affected counts are unknown.", file=sys.stderr)
+    if args.yes:
+        return
+    if args.non_interactive or not sys.stdin.isatty() or args.token_stdin:
+        raise CliError(2, "CONFIRMATION_REQUIRED", "Supply the exact account ID and --yes for unattended execution or when stdin carries a token.")
+    print("Type the account ID to confirm: ", end="", file=sys.stderr, flush=True)
+    try:
+        answer = input()
+    except EOFError:
+        answer = None
+    if answer != account_id:
+        raise CliError(2, "CONFIRMATION_CANCELLED", "Account operation cancelled; no mutation was sent.")
+
+
+def execute(args, client, values, *, account_metadata, mapped_error):
+    key = values["idempotency_key"]
+    print("Idempotency key: " + key, file=sys.stderr)
+    data = {"idempotency_key": key, "outcome": "unknown", "account": None}
+    if args.action == "delete":
+        data["deletion"] = None
+    try:
+        method = {"create": client.create_account, "update": client.patch_account,
+                  "reactivate": client.patch_account, "suspend": client.suspend_account,
+                  "delete": client.delete_account}[args.action]
+        response = method(**values)
+        if args.action == "delete":
+            if (not isinstance(response, Mapping) or response.get("kind") != "account"
+                    or response.get("id") != values["account_id"] or response.get("deleted") is not True
+                    or not isinstance(response.get("label"), str)):
+                raise CliError(7, "INVALID_RESPONSE", "The server did not confirm deletion of the selected account.")
+            data.update(outcome="confirmed", deletion={name: response[name] for name in ("kind", "id", "label", "deleted")})
+            return data, None
+        account = account_metadata(response)
+        if not isinstance(account.get("account_id"), str) or not account["account_id"]:
+            raise CliError(7, "INVALID_RESPONSE", "The server did not return confirmed account metadata.")
+        if args.action == "suspend" and (account["account_id"] != values["account_id"] or account.get("status") != "suspended"):
+            raise CliError(7, "INVALID_RESPONSE", "The server did not confirm suspension of the selected account.")
+        data.update(account=account, outcome="confirmed")
+        return data, None
+    except (SecFlowSdkError, CliError) as caught:
+        error = mapped_error(caught)
+        if isinstance(caught, SecFlowConfigError):
+            data["outcome"] = "not_sent"
+        elif error.status in (2, 3, 4, 5, 6):
+            # The final request was rejected; an earlier attempt using this
+            # key may have completed. Never imply rollback of that attempt.
+            data["outcome"] = "not_confirmed"
+        else:
+            error = CliError(7, "MUTATION_OUTCOME_UNKNOWN", "Mutation completion is unknown. Inspect current state; any retry must use identical inputs and the same idempotency key.")
+        return data, error

secflow_cli/browser_login.py

@@ -0,0 +1,129 @@
+"""Human browser login; Auth credentials stay on the SecFlow server."""
+from __future__ import annotations
+
+import base64
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+from urllib.error import HTTPError
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+from uuid import UUID
+import webbrowser
+
+from secflow_sdk import SecFlowAdminClient
+from secflow_cli.errors import CliError
+
+
+def rejected():
+    return CliError(3, "BROWSER_LOGIN_FAILED", "Browser login did not complete. Start a new login; uncertain session exchanges are not retried.")
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        return None
+
+
+def post(url, body, timeout):
+    request = Request(url, data=json.dumps(body).encode("utf-8"), method="POST",
+                      headers={"Content-Type": "application/json", "Accept": "application/json"})
+    try:
+        response = build_opener(NoRedirect).open(request, timeout=timeout)
+    except HTTPError as error:
+        status = error.code
+        error.close()
+        return status, {}
+    with response:
+        raw = response.read(16385)
+        if len(raw) > 16384:
+            raise rejected()
+        value = json.loads(raw)
+        if not isinstance(value, dict):
+            raise rejected()
+        return response.status, value
+
+
+def acquire_session(url, timeout, *, no_browser=False):
+    try:
+        return _acquire_session(url, timeout, no_browser=no_browser)
+    except CliError:
+        raise
+    except Exception:
+        raise rejected() from None
+
+
+def _acquire_session(url, timeout, *, no_browser):
+    proof = base64.urlsafe_b64encode(os.urandom(32)).rstrip(b"=").decode("ascii")
+    started_at = time.monotonic()
+    status, created = post(url + "/v1/auth/browser-login", {"poll_challenge": hashlib.sha256(proof.encode()).hexdigest()}, timeout)
+    if status == 404:
+        raise CliError(3, "BROWSER_LOGIN_UNAVAILABLE", "This server has not enabled browser login. Use a Slack-issued Admin session.")
+    if status != 201:
+        raise rejected()
+    identifier = created.get("transaction_id")
+    if str(UUID(identifier)) != identifier:
+        raise rejected()
+    verification_uri = url + "/auth/intflow/start?transaction_id=" + identifier
+    if (created.get("verification_uri") != verification_uri
+            or created.get("user_code") != identifier[:8].upper()
+            or type(created.get("expires_in")) is not int or not 1 <= created["expires_in"] <= 300
+            or type(created.get("interval")) is not int or not 2 <= created["interval"] <= 30):
+        raise rejected()
+    deadline = started_at + created["expires_in"]
+    print("Open " + verification_uri, file=sys.stderr)
+    print("Confirm code " + created["user_code"] + " and approve the login in your browser.", file=sys.stderr)
+    if not no_browser:
+        try:
+            opened = webbrowser.open(verification_uri)
+        except Exception:
+            opened = False
+        if not opened:
+            print("Open the URL above manually to continue.", file=sys.stderr)
+    interval = created["interval"]
+    while time.monotonic() + interval < deadline:
+        time.sleep(interval)
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        status, result = post(url + "/v1/auth/browser-login/redeem",
+                              {"transaction_id": identifier, "poll_secret": proof}, min(timeout, remaining))
+        if status == 202 and result == {"status": "pending"}:
+            continue
+        if status == 429:
+            interval = min(30, interval + 2)
+            continue
+        if status != 200:
+            raise rejected()
+        token = result.get("session_token")
+        if not isinstance(token, str) or not re.fullmatch(r"[A-Za-z0-9_-]{32,256}", token):
+            raise rejected()
+        if any(str(UUID(result.get(field))) != result[field] for field in ("session_id", "account_id")):
+            raise rejected()
+        expiry = datetime.fromisoformat(result["expires_at"].replace("Z", "+00:00"))
+        if expiry.tzinfo is None or expiry <= datetime.now(timezone.utc):
+            raise rejected()
+        return {field: result[field] for field in ("session_token", "session_id", "account_id", "expires_at")}
+    raise CliError(3, "BROWSER_LOGIN_EXPIRED", "Browser login expired. Start a new login.")
+
+
+def login(url, timeout, store, reference, *, no_browser=False):
+    store.check()
+    session = acquire_session(url, timeout, no_browser=no_browser)
+    client = SecFlowAdminClient(url, admin_session_token=session["session_token"], timeout=timeout)
+    try:
+        account = client.get_current_account()
+        if account.get("account_id") != session["account_id"] or account.get("status") != "active":
+            raise rejected()
+        store.set(reference, session["session_token"])
+    except BaseException:
+        # Do not erase a previously stored credential. Revoke only the session
+        # obtained by this invocation when validation/storage is unsuccessful.
+        try:
+            client.revoke_current_session()
+        except Exception:
+            pass
+        raise
+    return account, session["expires_at"]

secflow_cli/config.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+import hashlib
+import ipaddress
+import json
+import os
+from pathlib import Path
+import re
+import sys
+import tempfile
+from urllib.parse import urlsplit
+
+from secflow_cli.errors import CliError
+
+
+def endpoint(value: str) -> str:
+    try:
+        parts = urlsplit(value)
+        host = parts.hostname
+        if (value != value.strip() or any(ord(c) < 33 for c in value) or not host
+                or parts.username is not None or parts.password is not None
+                or parts.query or parts.fragment or parts.path not in ("", "/")
+                or parts.scheme not in ("http", "https")):
+            raise ValueError
+        loopback = host == "localhost"
+        try:
+            loopback = loopback or ipaddress.ip_address(host).is_loopback
+        except ValueError:
+            pass
+        if parts.scheme == "http" and not loopback:
+            raise ValueError
+        port = parts.port
+        if port is not None and port < 1:
+            raise ValueError
+        host = host.encode("idna").decode("ascii").lower()
+        if ":" in host:
+            host = f"[{host}]"
+        suffix = f":{port}" if port and port != (443 if parts.scheme == "https" else 80) else ""
+        return f"{parts.scheme}://{host}{suffix}"
+    except (ValueError, UnicodeError):
+        raise CliError(2, "INVALID_ENDPOINT", "Use an HTTPS server origin without credentials, path, query, or fragment; loopback HTTP is allowed.") from None
+
+
+def profile_name(value: str) -> str:
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,63}", value):
+        raise CliError(2, "INVALID_PROFILE", "Profile names must contain 1-64 letters, digits, dots, underscores, or hyphens.")
+    return value
+
+
+def credential_ref(name: str, url: str) -> str:
+    return "admin:" + hashlib.sha256((profile_name(name) + "\n" + endpoint(url)).encode()).hexdigest()
+
+
+class Profiles:
+    def __init__(self):
+        override = os.environ.get("SECFLOW_CLI_CONFIG_DIR")
+        if override:
+            directory = Path(override).expanduser()
+        elif sys.platform == "win32":
+            directory = Path(os.environ.get("APPDATA", str(Path.home() / "AppData/Roaming"))) / "SecFlow/cli"
+        elif sys.platform == "darwin":
+            directory = Path.home() / "Library/Application Support/SecFlow/cli"
+        else:
+            directory = Path(os.environ.get("XDG_CONFIG_HOME", str(Path.home() / ".config"))) / "secflow/cli"
+        self.path = directory.resolve() / "profiles.json"
+        if any((ancestor / ".git").exists() for ancestor in self.path.parents):
+            raise CliError(2, "INVALID_CONFIG_LOCATION", "CLI configuration must be outside a repository.")
+        self.data = {"version": 1, "current": None, "profiles": {}}
+        try:
+            if self.path.exists():
+                raw = json.loads(self.path.read_text(encoding="utf-8"))
+                if not isinstance(raw, dict) or set(raw) != {"version", "current", "profiles"} or raw["version"] != 1 or not isinstance(raw["profiles"], dict):
+                    raise ValueError
+                for name, profile in raw["profiles"].items():
+                    profile_name(name)
+                    if not isinstance(profile, dict) or set(profile) != {"base_url", "credential_ref"}:
+                        raise ValueError
+                    url = endpoint(profile["base_url"])
+                    if profile["credential_ref"] != credential_ref(name, url):
+                        raise ValueError
+                if raw["current"] is not None and raw["current"] not in raw["profiles"]:
+                    raise ValueError
+                self.data = raw
+        except (OSError, ValueError, TypeError, KeyError):
+            raise CliError(2, "INVALID_CONFIG", "Cannot read valid CLI profile configuration.") from None
+
+    def save(self):
+        self.path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
+        temporary = None
+        try:
+            with tempfile.NamedTemporaryFile(mode="w", encoding="utf-8", dir=self.path.parent, delete=False) as stream:
+                temporary = Path(stream.name)
+                json.dump(self.data, stream, indent=2)
+                stream.write("\n")
+            os.replace(temporary, self.path)
+        except OSError:
+            raise CliError(2, "CONFIG_WRITE_FAILED", "Cannot save CLI profile configuration.") from None
+        finally:
+            if temporary and temporary.exists():
+                temporary.unlink()
+
+    def select(self, name: str | None):
+        selected = name or os.environ.get("SECFLOW_PROFILE") or self.data["current"]
+        if selected is None or selected not in self.data["profiles"]:
+            raise CliError(2, "PROFILE_REQUIRED", "First use: secflowctl login. For a custom server, see secflowctl profile add --help; select an existing profile with --profile.")
+        return selected, self.data["profiles"][selected]

secflow_cli/credentials.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from secflow_cli.errors import CliError
+
+
+class CredentialStore:
+    """Only explicitly supported OS stores; never file-backed fallback plugins."""
+
+    service = "secflow-cli"
+    supported = frozenset({
+        ("keyring.backends.Windows", "WinVaultKeyring"),
+        ("keyring.backends.macOS", "Keyring"),
+        ("keyring.backends.SecretService", "Keyring"),
+    })
+
+    def __init__(self, *, allow_interaction=True):
+        self.backend = None
+        self.allow_interaction = allow_interaction
+
+    def check(self):
+        if self.backend is not None:
+            return
+        try:
+            import keyring
+            backend = keyring.get_keyring()
+            kind = (type(backend).__module__, type(backend).__name__)
+            # Keychain and Secret Service may display OS unlock dialogs. Until
+            # a prompt-free adapter is available, require explicit credentials
+            # in unattended sessions on these platforms.
+            if not self.allow_interaction and kind != ("keyring.backends.Windows", "WinVaultKeyring"):
+                raise RuntimeError
+            if kind not in self.supported or backend.priority <= 0:
+                raise RuntimeError
+            self.backend = backend
+        except Exception:
+            raise CliError(2, "CREDENTIAL_STORE_UNAVAILABLE", "A supported OS credential store is unavailable. Use --ephemeral with token stdin or SECFLOW_ADMIN_SESSION_TOKEN.") from None
+
+    def get(self, reference: str) -> str | None:
+        self.check()
+        try:
+            return self.backend.get_password(self.service, reference)
+        except Exception:
+            raise CliError(3, "CREDENTIAL_READ_FAILED", "Cannot read the selected OS credential entry.") from None
+
+    def set(self, reference: str, token: str):
+        self.check()
+        try:
+            self.backend.set_password(self.service, reference, token)
+        except Exception:
+            raise CliError(2, "CREDENTIAL_WRITE_FAILED", "Credential validation succeeded but secure storage failed.") from None
+
+    def delete(self, reference: str):
+        self.check()
+        try:
+            if self.backend.get_password(self.service, reference) is not None:
+                self.backend.delete_password(self.service, reference)
+        except Exception:
+            raise CliError(2, "CREDENTIAL_DELETE_FAILED", "Cannot clear the selected OS credential entry.") from None

secflow_cli/errors.py

@@ -0,0 +1,8 @@
+class CliError(Exception):
+    """A deliberately safe, locally authored error suitable for rendering."""
+
+    def __init__(self, status: int, code: str, message: str):
+        super().__init__(message)
+        self.status = status
+        self.code = code
+        self.message = message

secflow_cli/help.py

@@ -0,0 +1,100 @@
+"""Offline command discovery; all authorization remains server-side."""
+import argparse
+import sys
+
+GROUPS = {
+    'login': 'Sign in through Intflow; first use creates a profile for https://secflow.intflow.dev.',
+    'profile': 'Manage local server profiles (credentials remain in the OS credential store).',
+    'auth': 'Inspect, import, revoke, or forget your Admin session. Slack sessions remain supported.',
+    'health': 'Check server health and readiness without an Admin session.',
+    'accounts': 'Manage SecFlow accounts; server authorization is required.',
+    'namespaces': 'List and manage namespaces allowed by server authorization.',
+    'tokens': 'List SDK token metadata; this CLI does not issue tokens or display token values.',
+    'roles': 'List, grant, and revoke role bindings; server authorization is required.',
+    'access-profile': 'Read or replace the default access profile; set replaces all supported flags.',
+}
+OPTIONS = {
+    'profile': 'Select a saved profile (or SECFLOW_PROFILE). Global options go before the command.',
+    'base_url': 'HTTPS server origin. An override cannot reuse credentials for another origin.',
+    'output': 'Output format; JSONL is available for list commands only.',
+    'non_interactive': 'Disable prompts and interactive credential-store access.',
+    'timeout': 'Request timeout in seconds (default: 5; maximum: 300).',
+    'token_stdin': 'Read an Admin session from stdin; never pass credentials as arguments.',
+    'ephemeral': 'Validate an imported session for this invocation without storing it.',
+    'query': 'Filter results using the server search query.',
+    'page_size': 'Items per page, 1-200 (default: 50).',
+    'page_token': 'Continue from a previous response next_page_token.',
+    'all': 'Fetch successive pages up to --max-pages.',
+    'max_pages': 'Maximum pages for --all, 1-1000 (default: 100).',
+    'yes': 'Confirm this change without an interactive confirmation.',
+    'idempotency_key': 'Unique retry key for this operation; reuse only for the identical request.',
+    'namespace': 'Namespace identifier, for example dev/example.',
+    'account_id': 'SecFlow account UUID.',
+    'binding_id': 'Role binding UUID to revoke.',
+    'clear_expiration_policy': 'Remove the namespace expiration policy.',
+}
+EXAMPLES = {
+    '': 'secflowctl login\nsecflowctl auth status\nsecflowctl namespaces list --help',
+    'login': 'secflowctl login\nsecflowctl login --no-browser\nsecflowctl --profile staging login',
+    'profile': 'secflowctl profile list\nsecflowctl profile add staging --base-url https://secflow.example.test\nsecflowctl profile use staging',
+    'auth': 'secflowctl login\nsecflowctl auth status\nsecflowctl auth logout',
+    'auth login': 'secflowctl auth login --browser\nsecflowctl auth login\nsecflowctl --non-interactive auth login --token-stdin',
+    'profile add': 'secflowctl profile add staging --base-url https://secflow.example.test',
+    'profile use': 'secflowctl profile use staging',
+    'profile remove': 'secflowctl profile remove staging',
+    'accounts create': 'secflowctl accounts create --email user@intflow.ai --display-name Example',
+    'accounts update': 'secflowctl accounts update --account-id ACCOUNT_UUID --display-name Example',
+    'accounts suspend': 'secflowctl accounts suspend --account-id ACCOUNT_UUID',
+    'accounts reactivate': 'secflowctl accounts reactivate --account-id ACCOUNT_UUID',
+    'accounts delete': 'secflowctl accounts delete --account-id ACCOUNT_UUID',
+    'namespaces create': 'secflowctl namespaces create --namespace dev/example --owner TEAM --administrator ADMIN --audit-logging true',
+    'namespaces update': 'secflowctl namespaces update --namespace dev/example --owner TEAM',
+    'namespaces delete': 'secflowctl namespaces delete --namespace dev/example',
+    'roles grant': 'secflowctl roles grant --account-id ACCOUNT_UUID --role secret_reader --scope-type namespace --scope dev/example',
+    'roles revoke': 'secflowctl roles revoke --binding-id BINDING_UUID',
+    'access-profile set': 'secflowctl access-profile get\nsecflowctl access-profile set --profile-id PROFILE_UUID --allow-cli-login true --allow-api-session true --allow-namespace-request false',
+}
+
+
+def enrich(command):
+    path = command.prog.removeprefix('secflowctl').strip()
+    group = path.split(' ')[0]
+    command.formatter_class = argparse.RawDescriptionHelpFormatter
+    command.description = GROUPS.get(path) or (
+        f'{path.capitalize()}. {GROUPS.get(group, "Manage SecFlow through its Admin API.")}'
+        if path else 'SecFlow CLI: sign in, inspect your access, and manage authorized resources.')
+    example = EXAMPLES.get(path)
+    if example is None:
+        if ' ' not in path and group not in ('health',):
+            example = f'secflowctl {path} list\nsecflowctl {path} --help'
+            if group == 'access-profile':
+                example = 'secflowctl access-profile get\nsecflowctl access-profile set --help'
+        else:
+            action = path.split(' ')[-1]
+            example = f'secflowctl {path}' + (' --help' if action not in ('list', 'get', 'status', 'whoami', 'logout', 'forget', 'show', 'health') else '')
+    command.epilog = 'Examples:\n  ' + example.replace('\n', '\n  ')
+    command.epilog += '\n\nExplore: secflowctl --help; secflowctl <command> --help.\nGlobal options precede the command. Access is checked by the server.'
+    if path == 'auth forget':
+        command.description = 'Remove the local credential only; the server session remains valid. Use auth logout to revoke it.'
+    if path == 'auth logout':
+        command.description = 'Revoke the current server session and clear its local credential.'
+    if path == 'access-profile set':
+        command.epilog += '\nFull replacement: roles become empty; audit/plaintext access flags become false.\nAll three login/request flags are required. Existing sessions are not revoked.'
+    if any(marker in command.epilog for marker in ('ACCOUNT_UUID', 'BINDING_UUID', 'PROFILE_UUID')):
+        command.epilog += '\nReplace uppercase placeholders with IDs from the corresponding list/get command.'
+    for action in command._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            for name, child in action.choices.items():
+                enrich(child)
+                action._choices_actions.append(action._ChoicesPseudoAction(name, [], child.description))
+        elif action.help is None:
+            action.help = OPTIONS.get(action.dest, action.dest.replace('_', ' ').capitalize() + '.')
+
+
+def login_hint(args, account):
+    if args.non_interactive or not sys.stdin.isatty():
+        return
+    print('Signed in. Next: secflowctl auth status; secflowctl namespaces list --help.', file=sys.stderr)
+    if 'org_admin' in account.get('roles', []):
+        print('Account administration: secflowctl accounts --help; secflowctl roles --help.', file=sys.stderr)
+    print('Server roles and policies determine access. Explore all commands with secflowctl --help.', file=sys.stderr)