secflow-cli 0.1.0__tar.gz → 0.2.0__tar.gz

secflow_cli-0.2.0/PKG-INFO

@@ -0,0 +1,133 @@
+Metadata-Version: 2.4
+Name: secflow-cli
+Version: 0.2.0
+Summary: SecFlow operator CLI
+License-Expression: MIT
+Project-URL: Repository, https://github.com/yeon3724/secflow
+Project-URL: Issues, https://github.com/yeon3724/secflow/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: secflow-sdk==0.1.8
+Requires-Dist: keyring<26,>=25
+Dynamic: license-file
+
+# SecFlow CLI
+
+Use Intflow browser login or an existing Slack-issued Admin session. Both distributions provide the same `secflowctl` commands.
+
+## Install and update
+
+Choose one distribution per machine; both own the same `secflowctl` command and share profiles and the OS credential store.
+
+```sh
+pipx install secflow-cli
+# Or in a Python environment:
+python -m pip install secflow-cli
+
+# Alternative: Node.js 22+; no separate Python installation required
+npm install --global @intflow/secflow-cli
+secflowctl --version
+```
+
+The Python distribution requires Python 3.10+. Installation automatically includes the Admin-capable `secflow-sdk==0.1.8` dependency.
+
+The npm distribution includes Python and the CLI dependencies in OS-specific native packages. Initial targets: Windows x64, macOS Intel/Apple Silicon, and Linux x64 with glibc 2.35+ (Ubuntu 22.04+). Alpine/musl and Linux ARM are not npm targets yet; use the Python distribution there. Keep npm optional dependencies enabled. Installation has no postinstall script or runtime download. Native binaries are not platform-signed or notarized.
+
+The bundled interpreter includes CA certificates for HTTPS. An explicit `SSL_CERT_FILE` or `SSL_CERT_DIR` takes precedence for organization-managed trust; TLS certificate verification stays enabled.
+
+```sh
+pipx upgrade secflow-cli
+# Or use the same installer as the initial installation:
+python -m pip install --upgrade secflow-cli
+npm install --global @intflow/secflow-cli@latest
+```
+
+## Connect
+
+```sh
+secflowctl login
+secflowctl auth status
+secflowctl namespaces list --help
+secflowctl namespaces list --all
+secflowctl --help
+```
+
+`secflowctl` without arguments displays a quick start. `secflowctl login` opens Intflow login and creates the `production` profile for `https://secflow.intflow.dev` on first use. Existing profiles retain their selected server. For another server, first use `secflowctl profile add staging --base-url https://secflow.example.test`, then `secflowctl --profile staging login`. Global options precede the command. Every command supports `--help`, including examples. Account and role administration requires server authorization.
+
+`auth login` remains compatible with Slack-issued Admin sessions and prompts without echo for an existing session. Sessions are stored in Windows Credential Manager, macOS Keychain, or Linux Secret Service. Linux persistent login needs an unlocked Secret Service (for example GNOME Keyring) and a D-Bus session. If secure storage is unavailable, login fails without a plaintext file fallback. Installing the CLI does not create an account or grant access.
+
+When browser login is enabled on the server, run `secflowctl auth login --browser`. Sign in to Intflow, compare the code with your terminal, and approve the SecFlow login. Use `--browser --no-browser` to open the displayed URL manually. This requires an interactive terminal, an existing authorized SecFlow account, and OS credential storage. The CLI stores only the resulting SecFlow session. If login expires or the exchange fails, start a new login.
+
+For automation use `SECFLOW_ADMIN_SESSION_TOKEN` supplied by your secret manager, or `--token-stdin` with `--non-interactive`. Never put tokens in command arguments, profiles, shell history, or tracked files. SDK tokens cannot authorize these Admin commands. `auth logout` revokes the current server session; `auth forget` only removes the local credential.
+
+To uninstall, use `pipx uninstall secflow-cli`, `python -m pip uninstall secflow-cli`, or `npm uninstall --global @intflow/secflow-cli` as appropriate. Uninstalling does not revoke server sessions or erase profiles; log out and remove unwanted profiles first.
+
+## Expanded commands in 0.2.0
+
+CLI 0.2.0 adds the commands below. Metadata catalogs, details, permission checks, and per-secret access changes require the additive operator APIs on the server. An older server can still serve existing commands. `auth status` reports expiry and capabilities on newer servers and falls back to identity-only metadata when the session endpoint is absent. Authorization or dependency failures are not treated as an old server.
+
+| Task | Discover commands |
+| --- | --- |
+| Identity, permissions, service state | `auth status`, `auth capabilities`, `health`, `dashboard` |
+| Find authorized targets | `catalog accounts`, `catalog namespaces`, `catalog token-accounts`, `catalog actors` |
+| Account and namespace details | `accounts get --help`, `namespaces get --help` |
+| Namespace members and scoped roles | `namespaces members list`, `add`, `remove`; `roles list --namespace` or `--account-id` |
+| Delete impact | `namespaces impact`, `accounts impact`; `delete` shows the same counts before confirming |
+| Secret lifecycle | `secrets create`, `get`, `list`, `update`, `rotate`, `activate-revision`, `delete`; inspect each with `--help` |
+| Direct secret access overrides | `secrets access list`, `grant`, `block`, `reset`; reset restores inherited access |
+| SDK tokens and Admin sessions | `tokens issue --help`, `tokens revoke --help`, `auth sessions issue --help` |
+| Policies | `policies list`, `get`, `draft`, `preview`, `put`, `templates list`, `templates build` |
+| Audit metadata | `audit events list --help`, `audit exports --help` |
+| SDK access diagnostics | `runtime validate`, `metadata`, `permission-check`, `revoke-leases` |
+| Offline reference preparation | `refs build`, `validate`, `prepare`, `list`, `remove` |
+| Diagnostics | `doctor`; `doctor --watch --interval 60 --count 30` emits one JSONL record per run |
+| Metadata reports | `reports tokens`, `reports rotation`, `reports access --namespace` |
+| Repeatable setup | `manifest export`, `manifest plan`, `manifest apply` (see below) |
+| Shell completion | `completion bash`, `zsh`, or `powershell` |
+
+Without saved profiles, `secflowctl health` checks the default production origin without logging in or writing a profile. Use `--base-url` before `health` to select another origin. An explicitly selected profile must exist. Collection commands support bounded pagination where shown in help; audit events have a maximum page size of 100.
+
+## Repeat namespace setup
+
+```sh
+secflowctl manifest export --namespace dev/example > manifest.json
+# Edit owners, audit logging, expiration policy, or members (account_id + secret_reader/secret_writer).
+secflowctl --profile staging manifest plan --file manifest.json > plan.json
+secflowctl --profile staging manifest apply --file plan.json
+```
+
+A manifest covers namespace metadata and namespace members only; it never holds secret values, tokens, or policies, and it never deletes a namespace. `plan` changes nothing; `--prune` also revokes members missing from the manifest. A plan is bound to the server it was made for and cannot be edited. `apply` re-reads each item first: an item already in the desired state is skipped, and an item whose current state differs from the plan stops the run with exit 6. After an interruption or an uncertain result (exit 8), run the same `apply` again; it resumes and retries with each item's original idempotency key. Earlier items stay applied; nothing is rolled back.
+
+## Review and replace a policy
+
+First find the active policy with `secflowctl policies list --namespace dev/example`. Then use its ID:
+
+```sh
+secflowctl policies get --namespace dev/example --policy-id POLICY_UUID > current.json
+secflowctl policies draft --file current.json > draft.json
+# Edit draft.json's data.rules, preserving rules that must remain active.
+secflowctl policies preview --file draft.json
+secflowctl policies put --file draft.json
+```
+
+Draft creation is offline. It preserves scope and rules, generates a new policy ID, and increments the version. `put` still submits the supplied policy unchanged: it replaces the complete active policy for that scope. Do not reuse the current policy ID for a new revision. UTF-8, UTF-8 BOM, and BOM-marked UTF-16 files from Windows PowerShell redirection are accepted. Raw API policy JSON and successful CLI get/draft/template-build envelopes are supported.
+
+To append a template rule without discarding existing rules:
+
+```sh
+secflowctl policies templates list
+secflowctl policies templates build --file current.json --template runtime_read --account-id ACCOUNT_UUID --ref secret://dev/example/token/primary > draft.json
+secflowctl policies preview --file draft.json
+secflowctl policies put --file draft.json
+```
+
+Template building reads the authorized server catalog and writes only a draft. The SecretRef must belong to the policy namespace; existing deny rules still take precedence. Preview validates a document without saving it and does not prove future authorization or protect against concurrent policy changes. There is no server compare-and-swap precondition: review the latest active policy and coordinate concurrent edits before replacing it.
+
+For automation, use `--non-interactive` before the command and `--yes` on `put`. Keep the exact draft file and the idempotency key printed to stderr for an identical retry. Do not generate another draft or key when a mutation outcome is uncertain.
+
+## Credentials and values
+
+`tokens issue --save-as NAME` stores an SDK token separately from Admin profiles; `runtime ... --sdk-name NAME` uses it. `auth sessions issue --save-as PROFILE` creates a new destination profile. Both require a new destination name or explicit `--token-stdout` to redirected stdout; raw credentials never appear in ordinary JSON/table results. Linux/macOS non-interactive invocations require an explicitly injected credential rather than unlocking the OS store.
+
+Secret create/rotate reads exact UTF-8 or base64 input through hidden input, `--value-stdin`, or `--value-file`. Do not put values in command arguments. Stdin cannot simultaneously carry an Admin token and a secret or policy document. Runtime commands use SDK credentials only; Admin sessions are never substituted. No plaintext resolve command is provided.

secflow_cli-0.2.0/USAGE.md

@@ -0,0 +1,119 @@
+# SecFlow CLI
+
+Use Intflow browser login or an existing Slack-issued Admin session. Both distributions provide the same `secflowctl` commands.
+
+## Install and update
+
+Choose one distribution per machine; both own the same `secflowctl` command and share profiles and the OS credential store.
+
+```sh
+pipx install secflow-cli
+# Or in a Python environment:
+python -m pip install secflow-cli
+
+# Alternative: Node.js 22+; no separate Python installation required
+npm install --global @intflow/secflow-cli
+secflowctl --version
+```
+
+The Python distribution requires Python 3.10+. Installation automatically includes the Admin-capable `secflow-sdk==0.1.8` dependency.
+
+The npm distribution includes Python and the CLI dependencies in OS-specific native packages. Initial targets: Windows x64, macOS Intel/Apple Silicon, and Linux x64 with glibc 2.35+ (Ubuntu 22.04+). Alpine/musl and Linux ARM are not npm targets yet; use the Python distribution there. Keep npm optional dependencies enabled. Installation has no postinstall script or runtime download. Native binaries are not platform-signed or notarized.
+
+The bundled interpreter includes CA certificates for HTTPS. An explicit `SSL_CERT_FILE` or `SSL_CERT_DIR` takes precedence for organization-managed trust; TLS certificate verification stays enabled.
+
+```sh
+pipx upgrade secflow-cli
+# Or use the same installer as the initial installation:
+python -m pip install --upgrade secflow-cli
+npm install --global @intflow/secflow-cli@latest
+```
+
+## Connect
+
+```sh
+secflowctl login
+secflowctl auth status
+secflowctl namespaces list --help
+secflowctl namespaces list --all
+secflowctl --help
+```
+
+`secflowctl` without arguments displays a quick start. `secflowctl login` opens Intflow login and creates the `production` profile for `https://secflow.intflow.dev` on first use. Existing profiles retain their selected server. For another server, first use `secflowctl profile add staging --base-url https://secflow.example.test`, then `secflowctl --profile staging login`. Global options precede the command. Every command supports `--help`, including examples. Account and role administration requires server authorization.
+
+`auth login` remains compatible with Slack-issued Admin sessions and prompts without echo for an existing session. Sessions are stored in Windows Credential Manager, macOS Keychain, or Linux Secret Service. Linux persistent login needs an unlocked Secret Service (for example GNOME Keyring) and a D-Bus session. If secure storage is unavailable, login fails without a plaintext file fallback. Installing the CLI does not create an account or grant access.
+
+When browser login is enabled on the server, run `secflowctl auth login --browser`. Sign in to Intflow, compare the code with your terminal, and approve the SecFlow login. Use `--browser --no-browser` to open the displayed URL manually. This requires an interactive terminal, an existing authorized SecFlow account, and OS credential storage. The CLI stores only the resulting SecFlow session. If login expires or the exchange fails, start a new login.
+
+For automation use `SECFLOW_ADMIN_SESSION_TOKEN` supplied by your secret manager, or `--token-stdin` with `--non-interactive`. Never put tokens in command arguments, profiles, shell history, or tracked files. SDK tokens cannot authorize these Admin commands. `auth logout` revokes the current server session; `auth forget` only removes the local credential.
+
+To uninstall, use `pipx uninstall secflow-cli`, `python -m pip uninstall secflow-cli`, or `npm uninstall --global @intflow/secflow-cli` as appropriate. Uninstalling does not revoke server sessions or erase profiles; log out and remove unwanted profiles first.
+
+## Expanded commands in 0.2.0
+
+CLI 0.2.0 adds the commands below. Metadata catalogs, details, permission checks, and per-secret access changes require the additive operator APIs on the server. An older server can still serve existing commands. `auth status` reports expiry and capabilities on newer servers and falls back to identity-only metadata when the session endpoint is absent. Authorization or dependency failures are not treated as an old server.
+
+| Task | Discover commands |
+| --- | --- |
+| Identity, permissions, service state | `auth status`, `auth capabilities`, `health`, `dashboard` |
+| Find authorized targets | `catalog accounts`, `catalog namespaces`, `catalog token-accounts`, `catalog actors` |
+| Account and namespace details | `accounts get --help`, `namespaces get --help` |
+| Namespace members and scoped roles | `namespaces members list`, `add`, `remove`; `roles list --namespace` or `--account-id` |
+| Delete impact | `namespaces impact`, `accounts impact`; `delete` shows the same counts before confirming |
+| Secret lifecycle | `secrets create`, `get`, `list`, `update`, `rotate`, `activate-revision`, `delete`; inspect each with `--help` |
+| Direct secret access overrides | `secrets access list`, `grant`, `block`, `reset`; reset restores inherited access |
+| SDK tokens and Admin sessions | `tokens issue --help`, `tokens revoke --help`, `auth sessions issue --help` |
+| Policies | `policies list`, `get`, `draft`, `preview`, `put`, `templates list`, `templates build` |
+| Audit metadata | `audit events list --help`, `audit exports --help` |
+| SDK access diagnostics | `runtime validate`, `metadata`, `permission-check`, `revoke-leases` |
+| Offline reference preparation | `refs build`, `validate`, `prepare`, `list`, `remove` |
+| Diagnostics | `doctor`; `doctor --watch --interval 60 --count 30` emits one JSONL record per run |
+| Metadata reports | `reports tokens`, `reports rotation`, `reports access --namespace` |
+| Repeatable setup | `manifest export`, `manifest plan`, `manifest apply` (see below) |
+| Shell completion | `completion bash`, `zsh`, or `powershell` |
+
+Without saved profiles, `secflowctl health` checks the default production origin without logging in or writing a profile. Use `--base-url` before `health` to select another origin. An explicitly selected profile must exist. Collection commands support bounded pagination where shown in help; audit events have a maximum page size of 100.
+
+## Repeat namespace setup
+
+```sh
+secflowctl manifest export --namespace dev/example > manifest.json
+# Edit owners, audit logging, expiration policy, or members (account_id + secret_reader/secret_writer).
+secflowctl --profile staging manifest plan --file manifest.json > plan.json
+secflowctl --profile staging manifest apply --file plan.json
+```
+
+A manifest covers namespace metadata and namespace members only; it never holds secret values, tokens, or policies, and it never deletes a namespace. `plan` changes nothing; `--prune` also revokes members missing from the manifest. A plan is bound to the server it was made for and cannot be edited. `apply` re-reads each item first: an item already in the desired state is skipped, and an item whose current state differs from the plan stops the run with exit 6. After an interruption or an uncertain result (exit 8), run the same `apply` again; it resumes and retries with each item's original idempotency key. Earlier items stay applied; nothing is rolled back.
+
+## Review and replace a policy
+
+First find the active policy with `secflowctl policies list --namespace dev/example`. Then use its ID:
+
+```sh
+secflowctl policies get --namespace dev/example --policy-id POLICY_UUID > current.json
+secflowctl policies draft --file current.json > draft.json
+# Edit draft.json's data.rules, preserving rules that must remain active.
+secflowctl policies preview --file draft.json
+secflowctl policies put --file draft.json
+```
+
+Draft creation is offline. It preserves scope and rules, generates a new policy ID, and increments the version. `put` still submits the supplied policy unchanged: it replaces the complete active policy for that scope. Do not reuse the current policy ID for a new revision. UTF-8, UTF-8 BOM, and BOM-marked UTF-16 files from Windows PowerShell redirection are accepted. Raw API policy JSON and successful CLI get/draft/template-build envelopes are supported.
+
+To append a template rule without discarding existing rules:
+
+```sh
+secflowctl policies templates list
+secflowctl policies templates build --file current.json --template runtime_read --account-id ACCOUNT_UUID --ref secret://dev/example/token/primary > draft.json
+secflowctl policies preview --file draft.json
+secflowctl policies put --file draft.json
+```
+
+Template building reads the authorized server catalog and writes only a draft. The SecretRef must belong to the policy namespace; existing deny rules still take precedence. Preview validates a document without saving it and does not prove future authorization or protect against concurrent policy changes. There is no server compare-and-swap precondition: review the latest active policy and coordinate concurrent edits before replacing it.
+
+For automation, use `--non-interactive` before the command and `--yes` on `put`. Keep the exact draft file and the idempotency key printed to stderr for an identical retry. Do not generate another draft or key when a mutation outcome is uncertain.
+
+## Credentials and values
+
+`tokens issue --save-as NAME` stores an SDK token separately from Admin profiles; `runtime ... --sdk-name NAME` uses it. `auth sessions issue --save-as PROFILE` creates a new destination profile. Both require a new destination name or explicit `--token-stdout` to redirected stdout; raw credentials never appear in ordinary JSON/table results. Linux/macOS non-interactive invocations require an explicitly injected credential rather than unlocking the OS store.
+
+Secret create/rotate reads exact UTF-8 or base64 input through hidden input, `--value-stdin`, or `--value-file`. Do not put values in command arguments. Stdin cannot simultaneously carry an Admin token and a secret or policy document. Runtime commands use SDK credentials only; Admin sessions are never substituted. No plaintext resolve command is provided.

{secflow_cli-0.1.0 → secflow_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "secflow-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "SecFlow operator CLI"
 readme = "USAGE.md"
 license = "MIT"

{secflow_cli-0.1.0 → secflow_cli-0.2.0}/src/secflow_cli/account_commands.py

@@ -9,6 +9,7 @@ from uuid import UUID, uuid4
 
 from secflow_sdk import SecFlowConfigError, SecFlowSdkError
 
+from secflow_cli.command_support import preview_delete, require_confirmable
 from secflow_cli.errors import CliError
 
 
@@ -65,24 +66,32 @@ def prepare(args):
         values["display_name"] = required_input(args, "display_name", "display name")
     if args.action == "reactivate":
         values["status"] = "active"
-    if args.action in DESTRUCTIVE_ACTIONS:
+    if args.action == "delete":
+        canonical_account(values["account_id"])
+        require_confirmable(args, "Supply the exact account ID and --yes for unattended execution or when stdin carries a token.")
+    elif args.action in DESTRUCTIVE_ACTIONS:
         confirm_destructive(args, values["account_id"])
     return values
 
 
-def confirm_destructive(args, account_id):
+def canonical_account(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)
+
+
+def preview(args, client, values):
+    return preview_delete(args, client, kind="account", target=values["account_id"], operation="accounts.impact",
+                          query={"account_id": values["account_id"]},
+                          semantics="deletion removes the account, its sessions, SDK tokens, and direct role bindings.")
+
+
+def confirm_destructive(args, account_id):
+    canonical_account(account_id)
+    print("Suspend account: " + account_id, file=sys.stderr)
+    print("Operation semantics, not a server impact preview: suspension revokes active Admin sessions and SDK tokens. Reactivation does not restore revoked credentials. Affected counts are unknown.", file=sys.stderr)
     if args.yes:
         return
     if args.non_interactive or not sys.stdin.isatty() or args.token_stdin:

secflow_cli-0.2.0/src/secflow_cli/command_support.py

@@ -0,0 +1,93 @@
+"""Shared validation for operator commands; never render request payloads."""
+import hashlib
+import re
+import sys
+from uuid import UUID, uuid4
+
+from secflow_cli.errors import CliError
+
+
+def mutation_options(command, *, confirm=False):
+    command.add_argument('--token-stdin', action='store_true')
+    command.add_argument('--idempotency-key')
+    if confirm:
+        command.add_argument('--yes', action='store_true')
+
+
+def mutation_key(args):
+    key = args.idempotency_key or 'cli-operation-' + 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 normalized characters.')
+    return key
+
+
+def correlation(key):
+    digest = hashlib.sha256(key.encode('ascii')).hexdigest()
+    return dict(request_id='cli-request-' + digest, trace_id='cli-trace-' + digest)
+
+
+def canonical_id(value):
+    try:
+        if str(UUID(value)) == value:
+            return value
+    except (ValueError, TypeError, AttributeError):
+        pass
+    raise CliError(2, 'INVALID_INPUT', 'Supply a canonical resource UUID.')
+
+
+def confirm(args, target):
+    if args.yes:
+        return
+    if args.non_interactive or args.token_stdin or not sys.stdin.isatty():
+        raise CliError(2, 'CONFIRMATION_REQUIRED', 'Inspect the exact target, then supply --yes to confirm this change.')
+    print('Type the exact target to confirm: ' + target, file=sys.stderr)
+    try:
+        answer = input()
+    except EOFError:
+        answer = None
+    if answer != target:
+        raise CliError(2, 'CONFIRMATION_CANCELLED', 'Cancelled; no mutation was sent.')
+
+
+BLOCKING = frozenset({'current_account'})
+
+
+def require_confirmable(args, message):
+    if not args.yes and (args.non_interactive or args.token_stdin or not sys.stdin.isatty()):
+        raise CliError(2, 'CONFIRMATION_REQUIRED', message)
+
+
+def server_impact(client, operation, query):
+    from secflow_sdk import SecFlowSdkError
+    try:
+        response = client._request_json('GET', '/v1/admin/operator/' + operation, query=tuple(query.items()))
+    except SecFlowSdkError:
+        return None
+    impact, blocking = response.get('impact'), response.get('blocking')
+    if (not isinstance(impact, dict) or not isinstance(blocking, list)
+            or not all(isinstance(key, str) and (value is None or type(value) is int) for key, value in impact.items())
+            or not all(isinstance(item, str) for item in blocking)):
+        return None
+    return {'impact': dict(impact), 'blocking': [item if item in BLOCKING else 'unknown_precondition' for item in blocking]}
+
+
+def preview_delete(args, client, *, kind, target, operation, query, semantics):
+    """Show the server's current-state impact, then require exact confirmation."""
+    print('Delete ' + kind + ': ' + target, file=sys.stderr)
+    impact = server_impact(client, operation, query)
+    if impact is None:
+        print('Operation semantics, not a server impact preview: ' + semantics + ' Affected counts are unknown.', file=sys.stderr)
+    else:
+        counts = ', '.join(key + '=' + ('not counted' if value is None else str(value)) for key, value in impact['impact'].items())
+        print('Server impact preview of current state (not a reservation): ' + counts, file=sys.stderr)
+        if impact['blocking']:
+            raise CliError(6, 'PRECONDITION_FAILED', 'The server reports a blocking precondition (' + ', '.join(impact['blocking']) + '); no mutation was sent.')
+    if not args.yes:
+        print('Type the ' + kind + ' to confirm: ', end='', file=sys.stderr, flush=True)
+        try:
+            answer = input()
+        except EOFError:
+            answer = None
+        if answer != target:
+            raise CliError(2, 'CONFIRMATION_CANCELLED', kind.capitalize() + ' deletion cancelled; no mutation was sent.')
+    return impact

secflow_cli-0.2.0/src/secflow_cli/completion.py

@@ -0,0 +1,58 @@
+"""Offline shell completion generated from the parser; never fetches server catalogs."""
+import argparse
+import json
+
+
+def add_commands(groups):
+    completion = groups.add_parser('completion', help='Print a shell completion script (bash, zsh, or PowerShell).')
+    completion.add_argument('shell', choices=('bash', 'zsh', 'powershell'))
+
+
+def tree(parser, path=()):
+    words = {}
+    options = [option for action in parser._actions for option in action.option_strings if option.startswith('--')]
+    children = {}
+    for action in parser._actions:
+        if isinstance(action, argparse._SubParsersAction):
+            children = action.choices
+    words[' '.join(path)] = sorted(children) + sorted(options)
+    for name, child in children.items():
+        words.update(tree(child, (*path, name)))
+    return words
+
+
+BASH = r'''_secflowctl() {
+  local cur="${COMP_WORDS[COMP_CWORD]}" path="" word i
+  for ((i = 1; i < COMP_CWORD; i++)); do
+    word="${COMP_WORDS[i]}"
+    [[ "$word" == -* ]] && continue
+    case " ${_SECFLOWCTL_WORDS[${path:-_}]} " in *" $word "*) path="${path:+$path }$word" ;; esac
+  done
+  COMPREPLY=($(compgen -W "${_SECFLOWCTL_WORDS[${path:-_}]}" -- "$cur"))
+}
+complete -F _secflowctl secflowctl
+'''
+
+POWERSHELL = r'''Register-ArgumentCompleter -Native -CommandName secflowctl -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $path = ''
+  foreach ($element in $commandAst.CommandElements | Select-Object -Skip 1) {
+    $word = $element.ToString()
+    if ($word -eq $wordToComplete -or $word.StartsWith('-')) { continue }
+    if ($SecflowctlWords[$path] -contains $word) { $path = ($path + ' ' + $word).Trim() }
+  }
+  $SecflowctlWords[$path] | Where-Object { $_ -like "$wordToComplete*" } |
+    ForEach-Object { [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_) }
+}
+'''
+
+
+def script(shell, parser):
+    words = tree(parser)
+    if shell == 'powershell':
+        entries = '\n'.join('  ' + json.dumps(key) + ' = @(' + ', '.join("'" + word + "'" for word in value) + ')'
+                            for key, value in sorted(words.items()))
+        return '$SecflowctlWords = @{\n' + entries + '\n}\n' + POWERSHELL
+    entries = '\n'.join('  [' + json.dumps(key or '_') + ']=' + json.dumps(' '.join(value)) for key, value in sorted(words.items()))
+    prefix = 'autoload -U +X bashcompinit && bashcompinit\n' if shell == 'zsh' else ''
+    return prefix + 'declare -A _SECFLOWCTL_WORDS=(\n' + entries + '\n)\n' + BASH

secflow_cli-0.2.0/src/secflow_cli/doctor_commands.py

@@ -0,0 +1,93 @@
+"""Bounded connection and credential diagnostics; health never proves secret resolution."""
+from datetime import datetime, timedelta, timezone
+import sys
+import time
+
+from secflow_sdk import SecFlowHttpError, SecFlowSdkError
+from secflow_cli.errors import CliError
+
+
+def add_commands(groups):
+    doctor = groups.add_parser('doctor', help='Diagnose the selected profile, credential, server health, and session.')
+    doctor.add_argument('--token-stdin', action='store_true')
+    doctor.add_argument('--watch', action='store_true', help='Repeat the diagnosis; each run is one JSONL record.')
+    doctor.add_argument('--interval', type=float, default=30.0, help='Seconds between runs with --watch, 5-3600 (default: 30).')
+    doctor.add_argument('--count', type=int, default=10, help='Number of runs with --watch, 1-1000 (default: 10).')
+    doctor.set_defaults(jsonl_ok=True)
+
+
+def check(name, status, detail):
+    return {'check': name, 'status': status, 'detail': detail}
+
+
+def session_checks(client, now):
+    try:
+        session = client._request_json('GET', '/v1/admin/operator/session')
+    except SecFlowHttpError as error:
+        if error.status_code == 404:
+            client.get_current_account()
+            return [check('session', 'ok', 'Admin session accepted.'),
+                    check('server_features', 'warn', 'The server predates operator metadata; newer commands are unavailable.')]
+        if error.status_code in (401, 403):
+            return [check('session', 'fail', 'The server rejected the Admin session; sign in again.')]
+        raise
+    expires = session.get('expires_at')
+    try:
+        remaining = datetime.fromisoformat(expires.replace('Z', '+00:00')) - now
+    except (AttributeError, TypeError, ValueError):
+        return [check('session', 'warn', 'Admin session accepted; expiry is unknown.')]
+    if remaining <= timedelta(0):
+        return [check('session', 'fail', 'The Admin session has expired.')]
+    status = 'warn' if remaining < timedelta(days=1) else 'ok'
+    return [check('session', status, 'Admin session accepted; expires at ' + expires + '.'),
+            check('server_features', 'ok', 'Operator metadata is available.')]
+
+
+def diagnose(args, name, url, client_factory, health):
+    checks = [check('profile', 'ok', name + ' -> ' + url)]
+    result, error = health(url, args.timeout)
+    checks.append(check('health', 'fail' if error else 'ok',
+                        'healthz=' + result['healthz']['status'] + ', readyz=' + result['readyz']['status']))
+    try:
+        client = client_factory()
+    except CliError as caught:
+        checks.append(check('credential', 'fail', caught.message))
+        return checks
+    checks.append(check('credential', 'ok', 'An Admin session is available (value not shown).'))
+    try:
+        checks += session_checks(client, datetime.now(timezone.utc))
+    except SecFlowSdkError:
+        checks.append(check('session', 'fail', 'The session could not be verified; the server request did not complete.'))
+    return checks
+
+
+def run(args, name, url, client_factory, command, output):
+    from secflow_cli.main import envelope, health, render
+    if args.watch and (not 5 <= args.interval <= 3600 or not 1 <= args.count <= 1000):
+        raise CliError(2, 'INVALID_INPUT', 'Interval must be 5-3600 seconds and count 1-1000.')
+    runs = args.count if args.watch else 1
+    output = 'jsonl' if args.watch and output == 'json' else output
+    cache = []
+
+    def cached_client():
+        # stdin carries the credential once; later runs reuse the same client.
+        if not cache:
+            try:
+                cache.append(client_factory())
+            except CliError as error:
+                cache.append(error)
+        if isinstance(cache[0], CliError):
+            raise cache[0]
+        return cache[0]
+
+    status = 0
+    for index in range(runs):
+        checks = diagnose(args, name, url, cached_client, health)
+        failed = any(item['status'] == 'fail' for item in checks)
+        error = CliError(7, 'DIAGNOSIS_FAILED', 'One or more checks failed.') if failed else None
+        render(envelope(command, checks, error=error), output)
+        status = error.status if error else 0
+        if index + 1 < runs:
+            sys.stdout.flush()
+            time.sleep(args.interval)
+    return status