zen-cli 0.1.7__tar.gz → 0.1.8__tar.gz

{zen_cli-0.1.7 → zen_cli-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: zen-cli
-Version: 0.1.7
+Version: 0.1.8
 Summary: CLI for Zen Desktop Service. Designed for AI and Human.
 Project-URL: Homepage, https://pypi.org/project/zen-cli/
 Author: zen-cli authors
@@ -18,6 +18,7 @@ Requires-Dist: pyjwt
 Requires-Dist: python-dotenv
 Requires-Dist: pyyaml
 Requires-Dist: questionary
+Requires-Dist: rich-click>=1.8
 Requires-Dist: tabulate
 Requires-Dist: yumako
 Provides-Extra: dev
@@ -52,23 +53,31 @@ Description-Content-Type: text/markdown
 ### 前置条件
 
 * Python 3.12 或更新版本
-* Pip
+* [uv](https://docs.astral.sh/uv/) 或 [pipx](https://pipx.pypa.io/)
 
 ### 安装
 
-#### Mac 与 Linux
+```text
+uv tool install zen-cli
+```
+
+或：
 
 ```text
-pip install zen-cli
+pipx install zen-cli
 ```
 
-#### Windows
+装完后若找不到 `zen`，跑 `uv tool update-shell` 或 `pipx ensurepath`，然后开一个新终端。Windows 同样适用。
+
+升级：
 
 ```text
-pip install zen-cli
+zen upgrade
+uv tool upgrade zen-cli
+pipx upgrade zen-cli
 ```
 
-如果安装 Python 时没有勾选 “Add python to PATH”，请把 Python 及其 `Scripts` 目录加入 PATH。
+`zen upgrade` 会按当前是 uv、pipx 还是普通环境选择对应方式。
 
 ### 使用 CLI
 

{zen_cli-0.1.7 → zen_cli-0.1.8}/README.md

@@ -20,23 +20,31 @@
 ### 前置条件
 
 * Python 3.12 或更新版本
-* Pip
+* [uv](https://docs.astral.sh/uv/) 或 [pipx](https://pipx.pypa.io/)
 
 ### 安装
 
-#### Mac 与 Linux
+```text
+uv tool install zen-cli
+```
+
+或：
 
 ```text
-pip install zen-cli
+pipx install zen-cli
 ```
 
-#### Windows
+装完后若找不到 `zen`，跑 `uv tool update-shell` 或 `pipx ensurepath`，然后开一个新终端。Windows 同样适用。
+
+升级：
 
 ```text
-pip install zen-cli
+zen upgrade
+uv tool upgrade zen-cli
+pipx upgrade zen-cli
 ```
 
-如果安装 Python 时没有勾选 “Add python to PATH”，请把 Python 及其 `Scripts` 目录加入 PATH。
+`zen upgrade` 会按当前是 uv、pipx 还是普通环境选择对应方式。
 
 ### 使用 CLI
 

{zen_cli-0.1.7 → zen_cli-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "zen-cli"
-version = "0.1.7"
+version = "0.1.8"
 description = "CLI for Zen Desktop Service. Designed for AI and Human."
 readme = "README.md"
 license = "MIT"
@@ -14,6 +14,7 @@ authors = [{ name = "zen-cli authors" }]
 dependencies = [
     "authlib",
     "click>=8.1",
+    "rich-click>=1.8",
     "coloredlogs",
     "httpx2",
     "mcp>=2",

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cli.py

@@ -4,7 +4,7 @@ import sys
 from pathlib import Path
 from typing import Any
 
-import click
+import rich_click as click
 from dotenv import load_dotenv
 from yumako import env
 
@@ -174,6 +174,7 @@ def main() -> None:
     load_dotenv(".env")
     if not logger.color_enabled():
         CONTEXT_SETTINGS["color"] = False
+        CONTEXT_SETTINGS["rich_help_config"] = {"color_system": None, "force_terminal": False}
     if os.environ.get("_ZEN_COMPLETE"):
         ctxp.telemetry.disable()
     ctxp.init_cli(main_cli=cli, commands_dir=str(_COMMANDS_DIR))

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/api.py

@@ -48,21 +48,19 @@ def _build_headers(header: list[str], content_type: str | None) -> dict[str, str
     "--mdc",
     type=str,
     required=False,
-    help="MDC name to use. Only valid when the service is a global service.",
+    help="MDC name.",
 )
 @click.option(
     "--region",
     type=str,
     required=False,
-    help="Regional name to use. Only valid when the service is a regional service.",
+    help="Region name.",
 )
 @click.option(
     "--raise-on-404",
     is_flag=True,
     default=False,
-    help=(
-        "Raise an error on HTTP 404 responses. If not set, returns None on 404. Only valid for GET and DELETE methods."
-    ),
+    help="Raise on HTTP 404.",
 )
 @click.option(
     "--all-pages",

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/auth/details.py

@@ -11,7 +11,7 @@ from zen_cli.support import auth as auth_support
     "--service",
     "-s",
     required=False,
-    help="Get the auth details for a target service. Useful if per-service auth override is configured.",
+    help="Target service.",
 )
 def details(service: str | None) -> Any:
     """Show cached token, JWT claims, and org."""

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/auth/status.py

@@ -10,7 +10,7 @@ from zen_cli.support import auth as auth_support
     "--service",
     "-s",
     required=False,
-    help="Report login status for a target service override.",
+    help="Target service.",
 )
 def status(service: str | None) -> Any:
     """Show whether you are logged in, TTL, and main JWT identity (name, acct, org, roles)."""

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/auth/token.py

@@ -10,7 +10,7 @@ from zen_cli.support import auth as auth_support
     "--service",
     "-s",
     required=False,
-    help="Get the access token for a target service. Useful if per-service auth override is configured.",
+    help="Target service.",
 )
 def token(service: str | None) -> Any:
     """Print the current access token."""

zen_cli-0.1.8/src/zen_cli/cmds/completion.py

@@ -0,0 +1,44 @@
+import click
+from click.shell_completion import get_completion_class
+
+_SHELLS = ("bash", "zsh", "fish", "powershell")
+
+
+@click.command()
+@click.argument("shell", type=click.Choice(_SHELLS, case_sensitive=False), metavar="SHELL")
+def completion(shell: str) -> None:
+    """Print a shell completion script for tab-completing zen.
+
+    After the script is loaded, type `zen` and press Tab to complete commands,
+    groups, and flags. Examples: `zen <Tab>`, `zen org <Tab>`, `zen --<Tab>`.
+
+    \b
+    Enable for this session:
+        bash:        eval "$(zen completion bash)"
+        zsh:         eval "$(zen completion zsh)"
+        fish:        zen completion fish | source
+        powershell:  zen completion powershell | Out-String | Invoke-Expression
+
+    \b
+    Make it permanent (open a new terminal afterward):
+        bash:        echo 'eval "$(zen completion bash)"' >> ~/.bashrc
+        zsh:         echo 'eval "$(zen completion zsh)"' >> ~/.zshrc
+        fish:        mkdir -p ~/.config/fish/completions
+                     zen completion fish > ~/.config/fish/completions/zen.fish
+        powershell:  Add the Invoke-Expression line to your $PROFILE
+                     (create it with `New-Item -Force $PROFILE` if missing)
+
+    bash needs the bash-completion package. zsh needs `compinit` in ~/.zshrc
+    (oh-my-zsh and most configs already have it).
+    """
+    ctx = click.get_current_context().find_root()
+    prog_name = ctx.info_name or "zen"
+    complete_var = f"_{prog_name.replace('-', '_').upper()}_COMPLETE"
+    cls = get_completion_class(shell)
+    if cls is None:
+        raise click.UsageError(f"Unsupported shell: {shell}")
+    script = cls(ctx.command, {}, prog_name, complete_var).source()
+    click.echo(script, nl=not script.endswith("\n"))
+
+
+completion.ignore_default_io = True  # type: ignore[attr-defined]

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/credential/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create a credential from a JSON payload."""
+    """Create a credential."""
     return run_create("credential", credential.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/deployment/create.py

@@ -11,7 +11,7 @@ from zen_cli.support.payload import payload_options, run_create
 @cli.org_id
 @payload_options
 def create(org: str, data_arg: str | None, json_arg: str | None) -> Any:
-    """Create an express deployment from a JSON payload."""
+    """Create an express deployment."""
 
     def _create(payload: Any) -> Any:
         return deployment.create(payload, org_id=cli.get_org_id(org))

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/entitlement/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create an entitlement from a JSON payload."""
+    """Create an entitlement."""
     return run_create("entitlement", entitlement.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/group/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create a pool group from a JSON payload."""
+    """Create a pool group."""
     return run_create("group", pool_group.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/login.py

@@ -37,7 +37,7 @@ from zen_cli.support import profile as profile_support
     "--org",
     type=str,
     required=False,
-    help="The CSP organization to login. If not specified, the user's default organization will be used.",
+    help="CSP organization to login.",
 )
 @click.option("--api-token", type=str, required=False, help="Login with a user CSP API token.")
 @click.option("--client-id", type=str, required=False, help="Login with OAuth client ID/secret.")
@@ -49,27 +49,27 @@ from zen_cli.support import profile as profile_support
     "--browser",
     is_flag=True,
     default=False,
-    help="Login with browser SSO. Not used unless this flag is set.",
+    help="Login with browser SSO.",
 )
 @click.option(
     "--device-code",
     is_flag=True,
     default=False,
-    help="Login with OAuth device code (open the URL on any device; no localhost callback).",
+    help="Login with OAuth device code.",
 )
 @click.option(
     "--refresh",
     "-r",
     default=False,
     is_flag=True,
-    help="Forcefully refresh the cached access token. Used only in non-interactive mode.",
+    help="Force-refresh the cached access token.",
 )
 @click.option(
     "--verbose",
     "-v",
     is_flag=True,
     default=False,
-    help="If specified, print verbose output.",
+    help="Print verbose output.",
 )
 def login(
     org: str | None,
@@ -87,22 +87,16 @@ def login(
 ) -> Any:
     """Login Zen Desktop Service.
 
-    This command works with the current profile and will update the current profile.
-    --org is the login org, not a resource --org. --verbose is this command's own flag.
+    Updates the current profile. With no method flag, reuses cache or configured
+    credentials; otherwise starts device-code login.
 
-    With no method flag, reuses the cached token or configured credentials.
-    If neither is available, starts device-code login. Browser SSO runs only
-    with `--browser`.
-
-    On success, prints the same JSON as `zen auth status`.
-    Inspect or refresh later with `zen auth details`, `zen auth token`, `zen auth refresh`.
-    Per-service tokens: `zen auth details --service` / `zen auth token --service`.
+    On success, prints session status.
 
     \b
     Examples:
         1. Re-login with cache, configured credentials, or device code:
             zen login
-        2. Login with OAuth device code (any browser, no localhost callback):
+        2. Login with OAuth device code:
             zen login --device-code
         3. Login with OAuth client id/secret:
             zen login --client-id <oauth-client-id> --client-secret <oauth-client-secret>
@@ -110,7 +104,7 @@ def login(
             zen login --api-token <csp-org-scope-user-api-token>
         5. Login with CSP HTTP basic auth token:
             zen login --basic <csp-http-basic-auth-token>
-        6. Login with CSP OAuth2 access token (normally short-lived):
+        6. Login with CSP OAuth2 access token:
             zen login --access-token <csp-access-token>
         7. Login with CSP OAuth2 refresh token:
             zen login --refresh-token <csp-refresh-token>

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/mcp.py

@@ -5,12 +5,16 @@ import click
 def mcp() -> None:
     """Run the zen MCP server over stdio.
 
-    Uses stdout for the MCP protocol; I/O flags do not apply.
-    Skips the startup upgrade check.
-
     Tools: api, plus get/list for org, activity, entitlement, group, provider,
     sag, network, credential, deployment, notification, pool, vm, and task.
+
+    \b
+    Examples:
+        zen mcp
     """
     from zen_cli.mcp import server as mcp_server
 
     mcp_server.run()
+
+
+mcp.ignore_default_io = True  # type: ignore[attr-defined]

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/network/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create a network infrastructure deployment from a JSON payload."""
+    """Create a network infrastructure deployment."""
     return run_create("network", network.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/org/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create org details from a JSON payload."""
+    """Create org details."""
     return run_create("org", org_svc.create, data_arg, json_arg, id_field="orgId")

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/pool/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create a pool from a JSON payload."""
+    """Create a pool."""
     return run_create("pool", pool.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/provider/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create a provider instance from a JSON payload."""
+    """Create a provider instance."""
     return run_create("provider", provider.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/sag/create.py

@@ -9,5 +9,5 @@ from zen_cli.support.payload import payload_options, run_create
 @click.command()
 @payload_options
 def create(data_arg: str | None, json_arg: str | None) -> Any:
-    """Create a SAG deployment from a JSON payload."""
+    """Create a SAG deployment."""
     return run_create("sag", sag.create, data_arg, json_arg)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/task/delete.py

@@ -25,10 +25,7 @@ def delete(
     confirm: bool,
     **kwargs: Any,
 ) -> Any:
-    """Delete a task.
-
-    Not implemented. Prints TODO on stderr and exits 1.
-    """
+    """Delete a task."""
     namespace, group, key = parse_task_param(namespace, group, smart_path)
     org_id = cli.get_org_id(org)
     ret = task.get(org_id, namespace, group, key, **kwargs)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/task/get.py

@@ -14,7 +14,7 @@ from zen_cli.support.task import parse_task_param
 @click.option("--location", hidden=True, type=str, required=False, help="Task location.")
 @click.argument("smart_path", type=str, required=False)
 def get(org: str, namespace: str, group: str, location: str, smart_path: str, **kwargs: Any) -> Any:
-    """Get a task. E.g. 'task get [[<namespace>/]<group>/]<key>'."""
+    """Get a task. Path: [[<namespace>/]<group>/]<key>."""
     namespace, group, key = parse_task_param(namespace, group, smart_path)
     org_id = cli.get_org_id(org)
     return task.get(org_id, namespace, group, key, location=location, **kwargs)

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/task/log.py

@@ -16,15 +16,12 @@ from zen_cli.support.task import (
 @click.option("--namespace", "-n", type=str, required=False)
 @click.option("--group", "-g", type=str, required=False)
 @click.argument("smart_path", type=str, required=False)
-@click.option("--last", is_flag=True, default=False, help="If specified, return only the last log instead of all logs.")
+@click.option("--last", is_flag=True, default=False, help="Return only the last log.")
 @click.option(
     "--state",
     type=str,
     required=False,
-    help=(
-        "Filter tasks by state, for one-time tasks only. "
-        "Comma separated values. E.g. Init,Running,Canceled,Error,Success"
-    ),
+    help="Filter by one-time task state. Comma-separated: Init,Running,Canceled,Error,Success",
 )
 @cli.search
 @cli.limit

zen_cli-0.1.8/src/zen_cli/cmds/upgrade.py

@@ -0,0 +1,68 @@
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+
+_PKG = "zen-cli"
+
+
+def _managed_by(prefix: Path | None = None) -> str | None:
+    root = Path(prefix or sys.prefix)
+    if (root / "uv-receipt.toml").is_file():
+        return "uv"
+    if (root / "pipx_metadata.json").is_file():
+        return "pipx"
+    parts = [part.lower() for part in root.parts]
+    if "pipx" in parts and "venvs" in parts:
+        return "pipx"
+    for i, part in enumerate(parts[:-1]):
+        if part == "uv" and parts[i + 1] == "tools":
+            return "uv"
+    return None
+
+
+def _upgrade_cmd() -> list[str]:
+    manager = _managed_by()
+    if manager == "uv":
+        uv = shutil.which("uv")
+        if uv:
+            return [uv, "tool", "upgrade", _PKG]
+    elif manager == "pipx":
+        pipx = shutil.which("pipx")
+        if pipx:
+            return [pipx, "upgrade", _PKG]
+    return [
+        sys.executable,
+        "-m",
+        "pip",
+        "install",
+        "-U",
+        _PKG,
+        "--upgrade-strategy",
+        "eager",
+        "--no-cache-dir",
+    ]
+
+
+@click.command()
+def upgrade() -> None:
+    """Upgrade zen-cli from PyPI.
+
+    \b
+    Examples:
+        zen upgrade
+    """
+    cmd = _upgrade_cmd()
+    p = subprocess.run(cmd, stdout=sys.stdout, stderr=sys.stderr, check=False)
+    if p.returncode:
+        if _managed_by() is None and sys.prefix == getattr(sys, "base_prefix", sys.prefix):
+            print(
+                "Install with: uv tool install zen-cli   or   pipx install zen-cli",
+                file=sys.stderr,
+            )
+        raise SystemExit(p.returncode)
+
+
+upgrade.ignore_default_io = True  # type: ignore[attr-defined]

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/cmds/vm/wait.py

@@ -22,7 +22,7 @@ from zen_cli.support.vm import vm_from_path
     type=str,
     required=False,
     default="5m",
-    help="How long to wait (not --wait). Examples: '2m', '30s', '1h30m'. Default: 5m.",
+    help="How long to wait. Examples: '2m', '30s', '1h30m'. Default: 5m.",
 )
 @click.option(
     "--fail-fast/--fail-timeout",
@@ -35,8 +35,6 @@ from zen_cli.support.vm import vm_from_path
 def wait(vm_path: str, org: str, property: str, timeout: str, fail_fast: bool, **kwargs: Any) -> Any:
     """Wait for a VM field.
 
-    Uses --timeout/-t (default 5m) instead of --wait.
-
     \b
     Examples:
         zen vm wait -p agentStatus=AVAILABLE,ERROR --timeout 5m

{zen_cli-0.1.7 → zen_cli-0.1.8}/src/zen_cli/ctxp/__init__.py

@@ -1,3 +1,4 @@
+from . import _patch_click as _patch_click
 from . import config as config
 from . import profile as profile
 from . import state as state

zen_cli-0.1.8/src/zen_cli/ctxp/_patch_click.py

@@ -0,0 +1,5 @@
+"""Install rich-click types onto the stdlib click module before commands load."""
+
+from rich_click.patch import patch
+
+patch()