xmemcli 0.0.2__tar.gz → 0.0.4__tar.gz

{xmemcli-0.0.2 → xmemcli-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: xmemcli
-Version: 0.0.2
+Version: 0.0.4
 Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
 Keywords: api,cli,llm,memory,xmemory
 Requires-Python: <4,>=3.12
@@ -70,9 +70,15 @@ xmemcli write-status "$ID1" "$ID2"
 
 Requires **Python 3.12+**. Stdlib only — no runtime dependencies.
 
+Preferred:
+
 ```bash
 uv tool install xmemcli
-# or
+```
+
+When uv is not available:
+
+```bash
 pip install xmemcli
 ```
 
@@ -83,7 +89,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.2**.
+Version: **0.0.4**.
 
 
 ---
@@ -153,7 +159,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.2` (see `xmemcli version`)
+**Version:** `0.0.4` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-governed for key acquisition**; an AI-assisted IDE may run reads, writes, and inventory once credentials exist. Humans acquire API keys and change quota limits in the **Console UI**.
 
@@ -187,7 +193,6 @@ Permission-filtered view of what this API key can see.
 |---------|-------------|
 | **`org list clusters`** | Clusters visible to this credential |
 | **`org list instances`** | Instances visible to this credential |
-| **`instance list`** | Alias for **`org list instances`** |
 | **`org list keys`** | API keys visible to this credential (metadata only; plaintext never returned) |
 
 ---
@@ -199,8 +204,6 @@ Permission-filtered view of what this API key can see.
 | **`instance get`** `<instance_id>` | Fetch one instance |
 | **`instance create`** | Create from XMD/JSON schema. Required `--name`; schema via `--schema-file` or `--schema-stdin`. |
 
-**Operator-only (intentionally omitted from help and this table):** `instance delete` exists for humans at an interactive TTY (type `yes` to confirm) but is **not advertised** in primary CLI docs yet. Automation should use `DELETE /instances/{id}` over HTTP.
-
 ---
 
 ### Schema & XMD
@@ -215,7 +218,7 @@ XMD (xmemory Data) is the typed schema format for instances. These commands mirr
 | Apply migration | **`schema update`** `[instance_id]` | `--schema-file`, optional `--migration-plan`, `--confirm-destructive`. |
 | Preview migration | **`schema dry-run`** `[instance_id]` | Same flags as `schema update`; returns planned DDL without applying. |
 | List migrations | **`schema migrations list`** `[instance_id]` | Newest first. `--limit`, `--before-id`, `--include-yaml`. |
-| Fetch one migration | **`schema migrations get`** `<migration_id>` | Instance from `--instance-id` / `$XMEM_INSTANCE_ID`. `--include-yaml`. |
+| Fetch one migration | **`schema migrations get`** `[instance_id]` `<migration_id>` | Optional positional instance id; else `--instance-id` / `$XMEM_INSTANCE_ID`. `--include-yaml`. |
 | Enhance bound schema | **`xmd enhance --from-instance`** `<description>` | Uses live schema; requires instance id. |
 | Synthesize schema | **`xmd generate`** `<description>` | Cluster-scoped LLM synthesis. `-o` writes YAML. |
 | Enhance from file | **`xmd enhance`** `[schema_file]` `<description>` | From a file, or `--from-instance` for bound enhance. `-o`, `--plan-output`. |
@@ -242,7 +245,7 @@ xmemcli schema update INST_ID --schema-file next.yml --migration-plan plan.json
 
 # 4. Inspect history
 xmemcli schema migrations list INST_ID
-xmemcli schema migrations get MIGRATION_UUID
+xmemcli schema migrations get INST_ID MIGRATION_UUID
 ```
 
 #### Commands
@@ -253,7 +256,7 @@ xmemcli schema migrations get MIGRATION_UUID
 | **`schema update`** `[instance_id]` | Replace schema from `--schema-file`. Optional `--schema-type`, `--migration-plan`, `--confirm-destructive`. |
 | **`schema dry-run`** `[instance_id]` | Preview migration (same schema/plan flags as update). |
 | **`schema migrations list`** `[instance_id]` | Applied migrations, newest first. `--limit` (default 50), `--before-id`, `--include-yaml`. |
-| **`schema migrations get`** `<migration_id>` | One record; instance from global instance flags. `--include-yaml`. |
+| **`schema migrations get`** `[instance_id]` `<migration_id>` | One record. Optional positional instance id; else global instance flags. `--include-yaml`. |
 | **`xmd generate`** `<description>` | LLM-synthesize XMD. Optional `-o`. Requires cluster resolution. |
 | **`xmd enhance`** `[schema_file]` `<description>` | LLM-augment schema from file, or **`--from-instance`** for live schema. `-o`, `--plan-output`. |
 | **`xmd validate`** `<schema_file>` | Validate; YAML vs JSON inferred from `.json` extension. |
@@ -261,7 +264,7 @@ xmemcli schema migrations get MIGRATION_UUID
 | **`xmd validate-json`** `<schema_file>` | Force JSON Schema validation endpoint. |
 | **`xmd convert`** `<json_schema_file>` | JSON Schema → XMD YAML via the API (`validate_json_schema`). Optional `-o`, `--root-object`. |
 
-Instance id for `schema *` commands: positional `[instance_id]`, else **`--instance-id`** / **`$XMEM_INSTANCE_ID`** (except `migrations get`, which takes only `migration_id`).
+Instance id for `schema *` commands: positional `[instance_id]`, else **`--instance-id`** / **`$XMEM_INSTANCE_ID`**.
 
 ---
 
@@ -289,10 +292,23 @@ Instance id for `schema *` commands: positional `[instance_id]`, else **`--insta
 | **`quota`** | Usage / limit / window start for the key's cluster (derived from instance → cluster). |
 
 - **Default:** exit `0` when quota is readable; stderr **warning** when usage is high.
-- **`--fail-if-under THRESHOLD`** — exit non-zero when **remaining** quota is below that share of the limit (`0.1` or `10%`). See `xmemcli help quota`.
+- **`--fail-if-under THRESHOLD`** — exit **7** when **remaining** quota is below that share of the limit (`0.1` or `10%`). Distinct from exit **6** (API quota exhausted). See `xmemcli help quota`.
 
 Quota **increases** are Console-only — see [What `xmemcli` does not do](#what-xmemcli-does-not-do).
 
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | Success |
+| **2** | Usage error (bad flags, unknown `help` topic, missing required args) |
+| **3** | HTTP / request failure (includes unwritable `-o` paths) |
+| **4** | Auth error (missing or rejected API key) |
+| **5** | Timeout |
+| **6** | Quota exhausted (API quota-exceeded response) |
+| **7** | Quota headroom below `--fail-if-under` |
+| **130** | Interrupted (Ctrl+C) |
+
 ---
 
 ## Help
@@ -307,6 +323,8 @@ Quota **increases** are Console-only — see [What `xmemcli` does not do](#what-
 | **`xmemcli help <topic>`** | Usage, options, and subcommands for that topic |
 | **`xmemcli <cmd> … -h`** / **`--help`** | Same as `help <topic>` for that command path |
 
+Unknown help topics exit **2** (same as other usage errors).
+
 **Every command in this document has help.** Examples:
 
 ```text
@@ -315,7 +333,6 @@ xmemcli help write-status
 xmemcli help read
 xmemcli help org
 xmemcli help org list instances
-xmemcli help instance list
 xmemcli help instance create
 xmemcli help schema
 xmemcli help schema get
@@ -340,26 +357,6 @@ Nested topics work at any level that exists in the parser (`help org`, `help org
 
 ---
 
-## Command aliases
-
-Canonical names appear in `xmemcli` and in help. **Aliases are accepted on the command line but never listed in the overview** — use them in scripts if you already have them; prefer canonical names in new work.
-
-| Canonical command | Accepted aliases |
-|-------------------|------------------|
-| **`write-status`** | `write_status`, `writestatus`, `async_write_status`, `asyncwritestatus`, `async-write-status` |
-| **`quota`** | `quota get` |
-
-**Help topic aliases** (same targets, for `xmemcli help …` only):
-
-| `help` topic you type | Resolves to |
-|-----------------------|-------------|
-| `login` | `auth login` |
-| `logout` | `auth logout` |
-| `write-status`, `write_status`, `writestatus`, `async_write_status`, `asyncwritestatus`, `async-write-status` | `write-status` |
-| `quota get`, `quota-get` | `quota` |
-
----
-
 ## What `xmemcli` does **not** do
 
 | Area | Use the Console instead |
@@ -372,7 +369,7 @@ Canonical names appear in `xmemcli` and in help. **Aliases are accepted on the c
 | **Cluster create/delete** | CLI lists clusters; provisioning in Console |
 | **`read --extraction deep`** | Server has no read-depth knob today |
 | **Raw REST proxy** | Curated response fields only |
-| **`instance delete` (advertised)** | Implemented for human operators at a TTY (type `yes`); intentionally **omitted from help and this doc's command table** until product is ready to advertise it. Automation should use `DELETE /instances/{id}` over HTTP. |
+| **Instance deletion** | **Human operators only** — a hidden `instance delete` exists for interactive TTY use (type `yes` to confirm). It is omitted from help and must not be used by agents or automation. Console UI remains the primary human path. |
 
 On HTTP **402** (quota exhausted), stop and ask a human to extend quota in the Console.
 

{xmemcli-0.0.2 → xmemcli-0.0.4}/README.md

@@ -62,9 +62,15 @@ xmemcli write-status "$ID1" "$ID2"
 
 Requires **Python 3.12+**. Stdlib only — no runtime dependencies.
 
+Preferred:
+
 ```bash
 uv tool install xmemcli
-# or
+```
+
+When uv is not available:
+
+```bash
 pip install xmemcli
 ```
 
@@ -75,7 +81,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.2**.
+Version: **0.0.4**.
 
 
 ---
@@ -145,7 +151,7 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.2` (see `xmemcli version`)
+**Version:** `0.0.4` (see `xmemcli version`)
 
 `xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-governed for key acquisition**; an AI-assisted IDE may run reads, writes, and inventory once credentials exist. Humans acquire API keys and change quota limits in the **Console UI**.
 
@@ -179,7 +185,6 @@ Permission-filtered view of what this API key can see.
 |---------|-------------|
 | **`org list clusters`** | Clusters visible to this credential |
 | **`org list instances`** | Instances visible to this credential |
-| **`instance list`** | Alias for **`org list instances`** |
 | **`org list keys`** | API keys visible to this credential (metadata only; plaintext never returned) |
 
 ---
@@ -191,8 +196,6 @@ Permission-filtered view of what this API key can see.
 | **`instance get`** `<instance_id>` | Fetch one instance |
 | **`instance create`** | Create from XMD/JSON schema. Required `--name`; schema via `--schema-file` or `--schema-stdin`. |
 
-**Operator-only (intentionally omitted from help and this table):** `instance delete` exists for humans at an interactive TTY (type `yes` to confirm) but is **not advertised** in primary CLI docs yet. Automation should use `DELETE /instances/{id}` over HTTP.
-
 ---
 
 ### Schema & XMD
@@ -207,7 +210,7 @@ XMD (xmemory Data) is the typed schema format for instances. These commands mirr
 | Apply migration | **`schema update`** `[instance_id]` | `--schema-file`, optional `--migration-plan`, `--confirm-destructive`. |
 | Preview migration | **`schema dry-run`** `[instance_id]` | Same flags as `schema update`; returns planned DDL without applying. |
 | List migrations | **`schema migrations list`** `[instance_id]` | Newest first. `--limit`, `--before-id`, `--include-yaml`. |
-| Fetch one migration | **`schema migrations get`** `<migration_id>` | Instance from `--instance-id` / `$XMEM_INSTANCE_ID`. `--include-yaml`. |
+| Fetch one migration | **`schema migrations get`** `[instance_id]` `<migration_id>` | Optional positional instance id; else `--instance-id` / `$XMEM_INSTANCE_ID`. `--include-yaml`. |
 | Enhance bound schema | **`xmd enhance --from-instance`** `<description>` | Uses live schema; requires instance id. |
 | Synthesize schema | **`xmd generate`** `<description>` | Cluster-scoped LLM synthesis. `-o` writes YAML. |
 | Enhance from file | **`xmd enhance`** `[schema_file]` `<description>` | From a file, or `--from-instance` for bound enhance. `-o`, `--plan-output`. |
@@ -234,7 +237,7 @@ xmemcli schema update INST_ID --schema-file next.yml --migration-plan plan.json
 
 # 4. Inspect history
 xmemcli schema migrations list INST_ID
-xmemcli schema migrations get MIGRATION_UUID
+xmemcli schema migrations get INST_ID MIGRATION_UUID
 ```
 
 #### Commands
@@ -245,7 +248,7 @@ xmemcli schema migrations get MIGRATION_UUID
 | **`schema update`** `[instance_id]` | Replace schema from `--schema-file`. Optional `--schema-type`, `--migration-plan`, `--confirm-destructive`. |
 | **`schema dry-run`** `[instance_id]` | Preview migration (same schema/plan flags as update). |
 | **`schema migrations list`** `[instance_id]` | Applied migrations, newest first. `--limit` (default 50), `--before-id`, `--include-yaml`. |
-| **`schema migrations get`** `<migration_id>` | One record; instance from global instance flags. `--include-yaml`. |
+| **`schema migrations get`** `[instance_id]` `<migration_id>` | One record. Optional positional instance id; else global instance flags. `--include-yaml`. |
 | **`xmd generate`** `<description>` | LLM-synthesize XMD. Optional `-o`. Requires cluster resolution. |
 | **`xmd enhance`** `[schema_file]` `<description>` | LLM-augment schema from file, or **`--from-instance`** for live schema. `-o`, `--plan-output`. |
 | **`xmd validate`** `<schema_file>` | Validate; YAML vs JSON inferred from `.json` extension. |
@@ -253,7 +256,7 @@ xmemcli schema migrations get MIGRATION_UUID
 | **`xmd validate-json`** `<schema_file>` | Force JSON Schema validation endpoint. |
 | **`xmd convert`** `<json_schema_file>` | JSON Schema → XMD YAML via the API (`validate_json_schema`). Optional `-o`, `--root-object`. |
 
-Instance id for `schema *` commands: positional `[instance_id]`, else **`--instance-id`** / **`$XMEM_INSTANCE_ID`** (except `migrations get`, which takes only `migration_id`).
+Instance id for `schema *` commands: positional `[instance_id]`, else **`--instance-id`** / **`$XMEM_INSTANCE_ID`**.
 
 ---
 
@@ -281,10 +284,23 @@ Instance id for `schema *` commands: positional `[instance_id]`, else **`--insta
 | **`quota`** | Usage / limit / window start for the key's cluster (derived from instance → cluster). |
 
 - **Default:** exit `0` when quota is readable; stderr **warning** when usage is high.
-- **`--fail-if-under THRESHOLD`** — exit non-zero when **remaining** quota is below that share of the limit (`0.1` or `10%`). See `xmemcli help quota`.
+- **`--fail-if-under THRESHOLD`** — exit **7** when **remaining** quota is below that share of the limit (`0.1` or `10%`). Distinct from exit **6** (API quota exhausted). See `xmemcli help quota`.
 
 Quota **increases** are Console-only — see [What `xmemcli` does not do](#what-xmemcli-does-not-do).
 
+### Exit codes
+
+| Code | Meaning |
+|------|---------|
+| **0** | Success |
+| **2** | Usage error (bad flags, unknown `help` topic, missing required args) |
+| **3** | HTTP / request failure (includes unwritable `-o` paths) |
+| **4** | Auth error (missing or rejected API key) |
+| **5** | Timeout |
+| **6** | Quota exhausted (API quota-exceeded response) |
+| **7** | Quota headroom below `--fail-if-under` |
+| **130** | Interrupted (Ctrl+C) |
+
 ---
 
 ## Help
@@ -299,6 +315,8 @@ Quota **increases** are Console-only — see [What `xmemcli` does not do](#what-
 | **`xmemcli help <topic>`** | Usage, options, and subcommands for that topic |
 | **`xmemcli <cmd> … -h`** / **`--help`** | Same as `help <topic>` for that command path |
 
+Unknown help topics exit **2** (same as other usage errors).
+
 **Every command in this document has help.** Examples:
 
 ```text
@@ -307,7 +325,6 @@ xmemcli help write-status
 xmemcli help read
 xmemcli help org
 xmemcli help org list instances
-xmemcli help instance list
 xmemcli help instance create
 xmemcli help schema
 xmemcli help schema get
@@ -332,26 +349,6 @@ Nested topics work at any level that exists in the parser (`help org`, `help org
 
 ---
 
-## Command aliases
-
-Canonical names appear in `xmemcli` and in help. **Aliases are accepted on the command line but never listed in the overview** — use them in scripts if you already have them; prefer canonical names in new work.
-
-| Canonical command | Accepted aliases |
-|-------------------|------------------|
-| **`write-status`** | `write_status`, `writestatus`, `async_write_status`, `asyncwritestatus`, `async-write-status` |
-| **`quota`** | `quota get` |
-
-**Help topic aliases** (same targets, for `xmemcli help …` only):
-
-| `help` topic you type | Resolves to |
-|-----------------------|-------------|
-| `login` | `auth login` |
-| `logout` | `auth logout` |
-| `write-status`, `write_status`, `writestatus`, `async_write_status`, `asyncwritestatus`, `async-write-status` | `write-status` |
-| `quota get`, `quota-get` | `quota` |
-
----
-
 ## What `xmemcli` does **not** do
 
 | Area | Use the Console instead |
@@ -364,7 +361,7 @@ Canonical names appear in `xmemcli` and in help. **Aliases are accepted on the c
 | **Cluster create/delete** | CLI lists clusters; provisioning in Console |
 | **`read --extraction deep`** | Server has no read-depth knob today |
 | **Raw REST proxy** | Curated response fields only |
-| **`instance delete` (advertised)** | Implemented for human operators at a TTY (type `yes`); intentionally **omitted from help and this doc's command table** until product is ready to advertise it. Automation should use `DELETE /instances/{id}` over HTTP. |
+| **Instance deletion** | **Human operators only** — a hidden `instance delete` exists for interactive TTY use (type `yes` to confirm). It is omitted from help and must not be used by agents or automation. Console UI remains the primary human path. |
 
 On HTTP **402** (quota exhausted), stop and ask a human to extend quota in the Console.
 

{xmemcli-0.0.2 → xmemcli-0.0.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.2"
+version = "0.0.4"
 description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
 readme = "README.md"
 requires-python = ">=3.12,<4"

{xmemcli-0.0.2 → xmemcli-0.0.4}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.12, <4"
 
 [[package]]
 name = "xmemcli"
-version = "0.0.2"
+version = "0.0.4"
 source = { editable = "." }

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone xmemcli package (``xmemcli`` console script)."""
 
-__version__ = "0.0.2"
+__version__ = "0.0.4"

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/_help.py

@@ -8,7 +8,7 @@ import argparse
 import os
 import re
 import sys
-from typing import Any, IO, NoReturn
+from typing import Any, IO, NoReturn, override
 
 from ._version import CLI_NAME, __version__
 
@@ -37,6 +37,19 @@ _HIDDEN_COMMAND_NAMES = frozenset(
         "write_status",
         "writestatus",
         "async_write_status",
+        "asyncwritestatus",
+        "async-write-status",
+        "delete",
+    }
+)
+# Silent argv aliases for write-status spellings (also hidden from help subcommand lists).
+_WRITE_STATUS_ALIAS_NAMES = frozenset(
+    {
+        "write_status",
+        "writestatus",
+        "async_write_status",
+        "asyncwritestatus",
+        "async-write-status",
     }
 )
 _RESET = "\x1b[0m"
@@ -96,7 +109,6 @@ _OVERVIEW_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
     (
         "Instances",
         (
-            ("instance list", "List instances visible to this credential (alias for org list instances)"),
             ("instance get", "Get a single instance by id"),
             ("instance create", "Create a new instance from an XMD/JSON schema"),
         ),
@@ -183,7 +195,10 @@ def _option_label(action: argparse.Action) -> str:
             return f"{longest} …"
         return longest
     if action.metavar:
-        return action.metavar
+        meta = action.metavar
+        if isinstance(meta, tuple):
+            return " ".join(meta)
+        return meta
     return action.dest
 
 
@@ -498,7 +513,7 @@ def _render_unknown_document(doc: dict[str, Any], stream: IO[str], style: _Style
 
 
 def render_help_document(doc: dict[str, Any], *, stream: IO[str] | None = None) -> None:
-    """Render a :func:`build_help_document` payload for human terminals."""
+    """Render a `build_help_document` payload for human terminals."""
     out = stream if stream is not None else sys.stdout
     style = _Style(_use_color(out))
     kind = doc.get("kind")
@@ -555,13 +570,14 @@ def _format_cli_parse_error(message: str) -> str:
 
 
 class XmemCliArgumentParser(argparse.ArgumentParser):
-    """ArgumentParser that raises :class:`CliParseError` instead of dumping usage."""
+    """ArgumentParser that raises `CliParseError` instead of dumping usage."""
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
         kwargs.setdefault("usage", argparse.SUPPRESS)
         kwargs.setdefault("add_help", False)
         super().__init__(*args, **kwargs)
 
+    @override
     def error(self, message: str) -> NoReturn:
         raise CliParseError(_format_cli_parse_error(message))
 
@@ -702,12 +718,13 @@ def _choice_help(sub: argparse._SubParsersAction, name: str, child: argparse.Arg
 def _parser_title(root: argparse.ArgumentParser, path: tuple[str, ...], parser: argparse.ArgumentParser) -> str:
     if parser.description:
         return parser.description
-    if not path:
+    if len(path) == 0:
         return ""
-    parent = navigate_parser(root, path[:-1]) if len(path) > 1 else root
+    *parent_path, leaf = path
+    parent = navigate_parser(root, tuple(parent_path)) if parent_path else root
     sub = _subparsers_action(parent) if parent is not None else None
     if sub is not None:
-        return _choice_help(sub, path[-1], parser)
+        return _choice_help(sub, leaf, parser)
     return " ".join(path)
 
 

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/_instance_schema.py

@@ -1,6 +1,6 @@
 """Instance lifecycle and XMD/schema workflow commands for ``xmemcli``.
 
-Imported lazily from ``xmem._build_parser`` so ``xmem`` finishes loading before we bind helpers.
+Bound from ``xmem._build_parser`` after core ``xmem`` helpers are defined.
 """
 
 import argparse
@@ -12,7 +12,7 @@ from typing import Any, Protocol
 from urllib.parse import urlencode
 
 from ._output import CliOutput, OutputKind, make_error
-from ._xmem_bridge import curate_instance, http_to_exit, xmem_module
+from ._xmem_bridge import curate_instance, xmem_module
 
 try:
     import yaml as _yaml
@@ -26,6 +26,23 @@ def _yaml_dump_or_json(value: Any) -> str:
     return json.dumps(value, indent=2) + "\n"
 
 
+def _write_text_file(
+    path: str | Path,
+    content: str,
+    *,
+    stage: str = "output",
+) -> tuple[CliOutput, int] | None:
+    """Write *content* to *path*; return ``(error, exit_code)`` on ``OSError``."""
+    target = Path(path)
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        m = xmem_module()
+        return (make_error(f"cannot write {target}: {exc}", stage=stage), m.EXIT_HTTP_ERROR)
+    return None
+
+
 def _infer_schema_type(path: str | None, explicit: str | None) -> str:
     if explicit:
         return explicit
@@ -214,6 +231,12 @@ def _get_with_query(url: str, api_key: str, params: dict[str, Any], *, timeout_s
 
 
 def cmd_instance_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
+    """Return one instance by id.
+
+    Uses cluster-less ``GET /instances/{id}`` by default; the API resolves
+    ``cluster_id`` from the instance record and checks access in one round trip.
+    When ``--cluster`` is set, uses ``GET /clusters/{cluster}/instances/{id}``.
+    """
     m = xmem_module()
     api_key, _ = m._require(args, need_instance=False)
     base = m._api_url(args)
@@ -221,45 +244,26 @@ def cmd_instance_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
 
     explicit_cluster = getattr(args, "cluster", None)
     if explicit_cluster:
-        cluster_ids = [explicit_cluster]
+        url = f"{base}/clusters/{explicit_cluster}/instances/{instance_id}"
     else:
-        try:
-            clusters_env = m._get(f"{base}/clusters?verbose=true", api_key)
-        except m.ApiError as e:
-            return (make_error(f"/clusters failed: {e}", status=e.status), http_to_exit(e.status))
-        cluster_ids = [c["id"] for c in (clusters_env.get("items") or []) if isinstance(c, dict) and c.get("id")]
+        url = f"{base.rstrip('/')}/instances/{instance_id}"
 
-    last_auth_error: m.ApiError | None = None
-    for cid in cluster_ids:
-        try:
-            envelope = m._get(f"{base}/clusters/{cid}/instances/{instance_id}", api_key)
-        except m.ApiError as e:
-            if e.status == 404:
-                continue
-            if e.status in (401, 403):
-                last_auth_error = e
-                continue
-            return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
-        item = m._unwrap_items(envelope)
-        return (CliOutput(OutputKind.INSTANCE_GET, curate_instance(item, args.verbose)), m.EXIT_OK)
+    try:
+        envelope = m._get(url, api_key)
+    except m.ApiError as e:
+        if e.status == 404:
+            msg = (
+                f"instance {instance_id} not found in cluster {explicit_cluster}"
+                if explicit_cluster
+                else f"instance {instance_id} not found or not visible to this key"
+            )
+            return (make_error(msg, status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
+        if e.status in (401, 403):
+            return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
+        return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
 
-    if last_auth_error is not None:
-        return (
-            make_error(
-                f"instance {instance_id} exists in a cluster this key cannot access",
-                status=last_auth_error.status,
-                stage="auth",
-            ),
-            m.EXIT_AUTH_ERROR,
-        )
-    return (
-        make_error(
-            f"instance {instance_id} not found in any cluster visible to this key",
-            status=404,
-            stage="request",
-        ),
-        m.EXIT_HTTP_ERROR,
-    )
+    item = m._unwrap_items(envelope)
+    return (CliOutput(OutputKind.INSTANCE_GET, curate_instance(item, args.verbose)), m.EXIT_OK)
 
 
 def _require_interactive_yes(prompt: str) -> tuple[bool, str | None]:
@@ -267,7 +271,7 @@ def _require_interactive_yes(prompt: str) -> tuple[bool, str | None]:
     if not sys.stdin.isatty():
         return False, "instance delete requires an interactive terminal; type yes when prompted (do not pipe yes)"
     try:
-        # DELIBERATELY print: confirmation prompt must not pollute stdout in machine mode.
+        # DELIBERATELY write to stderr: confirmation prompt must not pollute stdout in machine mode.
         print(prompt, end="", file=sys.stderr, flush=True)
         answer = input().strip().lower()
     except EOFError:
@@ -282,8 +286,7 @@ def cmd_instance_delete(args: argparse.Namespace) -> tuple[CliOutput, int]:
 
     Partial by design: human operators at a real TTY must type ``yes``; piped or
     non-interactive stdin is refused. Agents, harnesses, and automation must use
-    ``DELETE /instances/{id}`` over HTTP instead — see ``cli/HARNESS-FIRST-TEST.md``
-    step 41.
+    ``DELETE /instances/{id}`` over HTTP instead — see harness step 41 in ``HARNESS-FIRST-TEST.md``.
     """
     m = xmem_module()
     api_key, _ = m._require(args, need_instance=False)
@@ -432,7 +435,9 @@ def cmd_xmd_generate(args: argparse.Namespace) -> tuple[CliOutput, int]:
     item = m._unwrap_items(envelope)
     schema = item.get("data_schema") if isinstance(item, dict) else None
     if args.output and schema is not None:
-        Path(args.output).write_text(_yaml_dump_or_json(schema), encoding="utf-8")
+        write_err = _write_text_file(args.output, _yaml_dump_or_json(schema), stage="generate")
+        if write_err is not None:
+            return write_err
     return (CliOutput(OutputKind.XMD_SCHEMA, item), m.EXIT_OK)
 
 
@@ -503,11 +508,15 @@ def cmd_xmd_enhance(args: argparse.Namespace) -> tuple[CliOutput, int]:
             return (make_error(str(e), status=e.status, stage="auth"), m.EXIT_AUTH_ERROR)
         return (make_error(str(e), status=e.status, stage="request"), m.EXIT_HTTP_ERROR)
     item = m._unwrap_items(envelope)
-    migration_plan = item.get("migration_plan") if isinstance(item, dict) else None
     if args.output and isinstance(item, dict) and item.get("data_schema") is not None:
-        Path(args.output).write_text(_yaml_dump_or_json(item["data_schema"]), encoding="utf-8")
+        write_err = _write_text_file(args.output, _yaml_dump_or_json(item["data_schema"]), stage="enhance")
+        if write_err is not None:
+            return write_err
     if args.plan_output and isinstance(item, dict):
-        Path(args.plan_output).write_text(json.dumps(item.get("migration_plan") or {}, indent=2), encoding="utf-8")
+        plan_body = json.dumps(item.get("migration_plan") or {}, indent=2)
+        write_err = _write_text_file(args.plan_output, plan_body, stage="enhance")
+        if write_err is not None:
+            return write_err
     return (CliOutput(OutputKind.XMD_ENHANCE, item), m.EXIT_OK)
 
 
@@ -638,7 +647,9 @@ def cmd_schema_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
     item = m._unwrap_items(envelope)
     schema = item.get("data_schema") if isinstance(item, dict) else None
     if args.output and schema is not None:
-        Path(args.output).write_text(_yaml_dump_or_json(schema), encoding="utf-8")
+        write_err = _write_text_file(args.output, _yaml_dump_or_json(schema), stage="schema")
+        if write_err is not None:
+            return write_err
     return (CliOutput(OutputKind.XMD_SCHEMA, item), m.EXIT_OK)
 
 

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/_login.py

@@ -87,10 +87,6 @@ def redirect_uri_for_port(port: int) -> str:
     return f"http://127.0.0.1:{port}{CALLBACK_PATH}"
 
 
-def redirect_uri() -> str:
-    return redirect_uri_for_port(CALLBACK_PORT)
-
-
 def new_verifier() -> str:
     return secrets.token_urlsafe(32)
 
@@ -151,8 +147,17 @@ def write_login_handoff_prompt(
         "",
         f"Authorize {CLI_NAME} on this machine.",
         "",
-        _login_prompt_line("Browser", "Open this URL and click \"Use this key in the CLI\":"),
+        _login_prompt_line("Browser", "Open this URL in your browser:"),
         f"{body_indent}{login_url}",
+        "",
+        _login_prompt_line(
+            "Onboarding",
+            "During first-instance setup the Console auto-delivers the key — no extra clicks.",
+        ),
+        _login_prompt_line(
+            "After onboarding",
+            "Create a key on API Keys and click \"Use this key in the CLI\".",
+        ),
     ]
     if offer_paste:
         lines.extend(
@@ -168,7 +173,6 @@ def write_login_handoff_prompt(
         [
             "",
             _login_prompt_line("Manual", "Set $XMEM_API_KEY or `.xmemrc.json`"),
-            f"{body_indent}See AUTH-FLOW.md.",
             "",
         ]
     )
@@ -331,8 +335,7 @@ def redeem_token(
             continue
     hint = (
         "Could not reach the accounts API token endpoint. "
-        "Set $XMEM_CONSOLE_URL to your Console (e.g. dk-web…) and ensure it can reach the API "
-        "(ACCOUNTS_API_URL on the Console server)."
+        "Set $XMEM_CONSOLE_URL to your Console origin and retry, or pass --console-url."
     )
     detail = "; ".join(errors[-3:]) if errors else "no endpoints tried"
     raise LoginError(f"token redeem failed: {detail}. {hint}")
@@ -380,7 +383,7 @@ def _read_pasted_api_key_no_echo(*, stop: threading.Event) -> str | None:
         return None
     finally:
         termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
-        # DELIBERATELY print: newline after raw-mode paste must not touch stdout (machine JSON).
+        # DELIBERATELY write to stderr: newline after raw-mode paste must not touch stdout (machine JSON).
         sys.stderr.write("\n")
         sys.stderr.flush()
 

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/_output.py

@@ -19,9 +19,9 @@ keep strictly separated:
 
 To keep the dispatch logic in one place and force every new subcommand to
 declare which family of output it produces, the commands no longer print
-directly. They build a :class:`CliOutput` (a discriminated payload tagged
-with an :class:`OutputKind`), and the entry point in ``cli/xmem.py`` decides
-how to render it via :func:`emit`. The pretty-print branch lives in
+directly. They build a `CliOutput` (a discriminated payload tagged
+with an `OutputKind`), and the entry point in ``cli/xmem.py`` decides
+how to render it via `emit`. The pretty-print branch lives in
 ``cli/_pretty.py`` so the formatting code can grow without cluttering the
 HTTP and argparse plumbing.
 
@@ -33,13 +33,13 @@ Invariants
 - Pretty-print is only ever reached when ``stdout.isatty()`` is true AND
   ``--json`` was not passed. Anything else gets JSON.
 - ``$XMEM_FORCE_TTY_OUTPUT_NOT_JSON`` is a **deliberate, documented escape hatch**
-  for manual E2E runbooks only (see :data:`ENV_FORCE_TTY_OUTPUT_NOT_JSON`). It does
+  for manual E2E runbooks only (see `ENV_FORCE_TTY_OUTPUT_NOT_JSON`). It does
   not change server behavior, credentials, or API payloads — only how ``emit`` chooses
   between JSON and pretty text. Agents, CI, and piped scripts must never set it;
   they use ``--json`` or a real TTY. If unset (the normal case), the non-TTY⇒JSON
   rule is unchanged.
 - A failed command still emits exactly one JSON document on stdout when JSON
-  mode is in effect — :class:`OutputKind.ERROR` + a non-zero exit code. We
+  mode is in effect — `OutputKind.ERROR` + a non-zero exit code. We
   do not silently dump human prose to stderr in machine mode.
 - The pretty-print renderers may fall back to JSON if they can't extract a
   useful summary from the payload; that is intentional and keeps human
@@ -48,11 +48,11 @@ Invariants
 Wire format
 -----------
 
-The JSON document emitted by :func:`emit` is the CURATED payload built by
+The JSON document emitted by `emit` is the CURATED payload built by
 the subcommand (see the ``_curate_*`` helpers in ``cli/xmem.py``) — the
 fields the user asked for, with server internals (SQL, diff plans, raw
 extraction trees) stripped in both output modes. We do NOT wrap it in a
-second envelope keyed by :class:`OutputKind` — adding a layer the consumer
+second envelope keyed by `OutputKind` — adding a layer the consumer
 didn't ask for would make scripts more fragile, not less. The kind is only
 used internally for pretty-print dispatch.
 """
@@ -98,7 +98,7 @@ class OutputKind(StrEnum):
 
     #: Read in ``mode=xresponse``. Curated payload: the reader_result
     #: subtree shaped as an XResponse (objects + relations). Pretty-print
-    #: renders as JSON for the same reason as :attr:`READ_RAW`.
+    #: renders as JSON for the same reason as `READ_RAW`.
     READ_XRESPONSE = "read_xresponse"
 
     #: Output of ``xmemcli org list keys``. Curated payload: a list of
@@ -109,18 +109,18 @@ class OutputKind(StrEnum):
     #: Output of ``xmemcli org list clusters``.
     CLUSTER_LIST = "cluster_list"
 
-    #: Output of ``xmem auth status``. Curated payload:
+    #: Output of ``xmemcli auth status``. Curated payload:
     #: ``{authenticated: bool, key_prefix, email?}`` — whose key the CLI is
     #: holding, resolved via ``/whoami``.
     AUTH_STATUS = "auth_status"
 
-    #: Output of ``xmem auth login`` / ``xmem auth logout``.
+    #: Output of ``xmemcli auth login`` / ``xmemcli auth logout``.
     LOGIN = "login"
 
-    #: Output of ``xmem version``.
+    #: Output of ``xmemcli version``.
     VERSION = "version"
 
-    #: Local-only release health (``xmem status``) — no network.
+    #: Local-only release health (``xmemcli status``) — no network.
     STATUS = "status"
 
     #: Output of ``xmemcli quota``. Curated payload: usage windows.
@@ -129,31 +129,31 @@ class OutputKind(StrEnum):
     #: Output of ``xmemcli org list instances`` (and ``instance list`` alias).
     INSTANCE_LIST = "instance_list"
 
-    #: Output of ``xmem instance get``.
+    #: Output of ``xmemcli instance get``.
     INSTANCE_GET = "instance_get"
 
-    #: Output of ``xmem instance create``.
+    #: Output of ``xmemcli instance create``.
     INSTANCE_CREATE = "instance_create"
 
-    #: Output of ``xmem instance delete``.
+    #: Output of ``xmemcli instance delete``.
     INSTANCE_DELETE = "instance_delete"
 
-    #: Output of ``xmem schema update``.
+    #: Output of ``xmemcli schema update``.
     SCHEMA_UPDATE = "schema_update"
 
-    #: Output of ``xmem schema dry-run``.
+    #: Output of ``xmemcli schema dry-run``.
     SCHEMA_DRY_RUN = "schema_dry_run"
 
-    #: Output of ``xmem schema migrations list`` / ``get``.
+    #: Output of ``xmemcli schema migrations list`` / ``get``.
     SCHEMA_MIGRATIONS = "schema_migrations"
 
-    #: Output of ``xmem xmd generate`` / ``enhance`` / ``validate`` / ``schema get``.
+    #: Output of ``xmemcli xmd generate`` / ``enhance`` / ``validate`` / ``schema get``.
     XMD_SCHEMA = "xmd_schema"
 
-    #: Output of ``xmem xmd enhance`` when a migration plan is included.
+    #: Output of ``xmemcli xmd enhance`` when a migration plan is included.
     XMD_ENHANCE = "xmd_enhance"
 
-    #: Output of ``xmem xmd convert``.
+    #: Output of ``xmemcli xmd convert``.
     XMD_CONVERT = "xmd_convert"
 
     #: Structured help document from ``build_help_document`` (overview, options,
@@ -163,7 +163,7 @@ class OutputKind(StrEnum):
 
     #: A failure surfaced as structured output. ``payload`` carries
     #: ``{"error": str, "status": int|null, "stage": str}`` — see
-    #: :func:`make_error`.
+    #: `make_error`.
     ERROR = "error"
 
 
@@ -183,7 +183,7 @@ class CliOutput(NamedTuple):
 
 
 def make_error(message: str, *, status: int | None = None, stage: str = "request") -> CliOutput:
-    """Construct an :class:`OutputKind.ERROR` payload.
+    """Construct an `OutputKind.ERROR` payload.
 
     ``status`` is the HTTP status code when the failure originated from a
     server response; ``stage`` is a free-form label naming the step that
@@ -219,8 +219,8 @@ def stdout_is_tty() -> bool:
     don't implement it.
 
     ``$XMEM_FORCE_TTY_OUTPUT_NOT_JSON`` — when set to a truthy value, pretend stdout is a
-    TTY so :func:`emit` uses pretty one-liners on piped/captured stdout. Manual Case 4
-    only; see :data:`ENV_FORCE_TTY_OUTPUT_NOT_JSON`. Does not apply when ``force_json``
+    TTY so `emit` uses pretty one-liners on piped/captured stdout. Manual Case 4
+    only; see `ENV_FORCE_TTY_OUTPUT_NOT_JSON`. Does not apply when ``force_json``
     is true (``--json``).
     """
     override = _env_tty_override()
@@ -249,7 +249,7 @@ def emit(
         ``True`` when ``--json`` was passed. Pretty-print is suppressed
         unconditionally and the renderer emits exactly one JSON document.
     is_tty
-        Override for :func:`stdout_is_tty`. Tests can pass an explicit
+        Override for `stdout_is_tty`. Tests can pass an explicit
         boolean to exercise both branches without monkey-patching.
     stream
         Defaults to ``sys.stdout``. Tests pass ``io.StringIO()`` here to

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/_pretty.py

@@ -1,20 +1,20 @@
-"""Human-friendly renderers for :mod:`_output` payloads.
+"""Human-friendly renderers for `cli._output` payloads.
 
 This module is **only** reached when the operator is sitting at a real
 terminal (``sys.stdout.isatty()``) AND did not pass ``--json``. Every other
-invocation gets strict JSON via :func:`_output.emit` — see that module's
+invocation gets strict JSON via `cli._output.emit` — see that module's
 docstring for the rationale.
 
 The renderers are deliberately small, opinionated, and one-shot: they print
 a single short summary (often a single line) keyed off the
-:class:`~cli._output.OutputKind`. The principle is "give the operator the
+`OutputKind`. The principle is "give the operator the
 headline they would have wanted to read aloud", not "render the entire
 payload". If the renderer can't extract a useful headline, it falls through
 to a JSON dump of the relevant sub-tree so the user still sees something
 truthful rather than a guess.
 
-Adding a new :class:`~cli._output.OutputKind` requires adding a renderer
-here keyed by the enum value in :data:`_RENDERERS`. The default handler
+Adding a new `OutputKind` requires adding a renderer
+here keyed by the enum value in `_RENDERERS`. The default handler
 emits the JSON payload, which is a safe (if uninspired) fallback.
 """
 
@@ -31,10 +31,10 @@ Renderer = Callable[[Any, IO[str]], None]
 
 
 def render(kind: str | Enum, payload: Any, stream: IO[str]) -> None:
-    """Dispatch to a renderer by :class:`OutputKind`.
+    """Dispatch to a renderer by `OutputKind`.
 
     Unknown kinds (or any future kind without a registered renderer) fall
-    through to :func:`_default_handler`, which dumps the payload as JSON.
+    through to `_default_handler`, which dumps the payload as JSON.
     """
     dispatch_key = kind.value if isinstance(kind, Enum) else kind
     handler = _RENDERERS.get(dispatch_key, _default_handler)

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/_version.py

@@ -1,4 +1,4 @@
 """Release metadata for the xmemcli CLI (copied into standalone builds)."""
 
 CLI_NAME = "xmemcli"
-__version__ = "0.0.2"
+__version__ = "0.0.4"

{xmemcli-0.0.2 → xmemcli-0.0.4}/xmemcli/cli.py

@@ -4,10 +4,10 @@ This file is the CLI entry point. It deliberately uses only the standard
 library so the demo runs anywhere a Python 3.12+ interpreter exists without
 ``pip install``. The interesting structural decision is that **commands do
 not format output themselves** — every subcommand builds a
-:class:`_output.CliOutput` and returns ``(output, exit_code)``. The
-``main`` dispatch then emits via :func:`_output.emit`, which picks
+`cli._output.CliOutput` and returns ``(output, exit_code)``. The
+``main`` dispatch then emits via `cli._output.emit`, which picks
 between strict JSON (machine consumption) and a one-line human summary
-(interactive terminal) per the rules documented in :mod:`_output`.
+(interactive terminal) per the rules documented in `cli._output`.
 
 Endpoints exercised (under ``$XMEM_API_URL`` unless noted; default
 ``https://api.xmemory.ai``):
@@ -120,6 +120,8 @@ EXIT_TIMEOUT = 5
 # ``QuotaExceededKind`` discriminator on the wire body so the printed
 # message can match (TRIAL ENDED / DAILY QUOTA / MONTHLY QUOTA).
 EXIT_QUOTA_EXCEEDED = 6
+# Local quota headroom gate (`quota --fail-if-under`) — distinct from API 429 / exhausted quota.
+EXIT_QUOTA_THRESHOLD = 7
 # Conventional shell exit for SIGINT (128 + 2) — no stack trace, not a usage error.
 EXIT_INTERRUPTED = 130
 
@@ -471,7 +473,7 @@ class UsageError(Exception):
     an unset instance id, or the localhost-key-at-prod guard.
 
     It carries an ``OutputKind.ERROR`` payload so ``main`` renders it through
-    :func:`emit` like any other result. That keeps the machine-mode invariant:
+    `emit` like any other result. That keeps the machine-mode invariant:
     a failed command still emits **exactly one** JSON document on stdout, never
     bare prose to stderr (see ``cli/_output.py``).
     """
@@ -845,6 +847,7 @@ def cmd_auth_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
                 "logged_in": True,
                 "email": auth_api_key.get("email"),
                 "key_prefix": api_key[:8],
+                "onboarding": bool(auth_api_key.get("onboarding")),
             },
         ),
         EXIT_OK,
@@ -985,7 +988,7 @@ def _resolve_cluster_id(
 
     Order: operator override → instance context → sole visible cluster.
     Agent-facing errors steer toward ``--instance-id``, not cluster ID
-    (see ``maxims/API-CLIENTS.yml`` — *One addressing axis for agents*).
+    Agent-facing errors steer toward ``--instance-id``, not cluster ID (one addressing axis for agents).
     """
     override = _operator_cluster_override(args)
     if override:
@@ -1191,7 +1194,7 @@ def cmd_quota_get(args: argparse.Namespace) -> tuple[CliOutput, int]:
                 and not isinstance(remaining, bool)
                 and (remaining / limit) < fail_threshold
             ):
-                exit_code = EXIT_QUOTA_EXCEEDED
+                exit_code = EXIT_QUOTA_THRESHOLD
     return (CliOutput(OutputKind.QUOTA, curated), exit_code)
 
 
@@ -1225,33 +1228,32 @@ def cmd_status(args: argparse.Namespace) -> tuple[CliOutput, int]:
     return (CliOutput(OutputKind.STATUS, payload), EXIT_OK)
 
 
-from ._instance_schema import (  # noqa: E402 — after ``xmem`` helpers; avoids import cycle at module start
-    cmd_instance_create,
-    cmd_instance_delete,
-    cmd_instance_get,
-    cmd_schema_dry_run,
-    cmd_schema_get,
-    cmd_schema_migrations_get,
-    cmd_schema_migrations_list,
-    cmd_schema_update,
-    cmd_xmd_convert,
-    cmd_xmd_enhance,
-    cmd_xmd_generate,
-    cmd_xmd_validate,
-    cmd_xmd_validate_json,
-    cmd_xmd_validate_yaml,
-)
-from ._org_cluster import (  # noqa: E402
-    cmd_org_list_clusters,
-    cmd_org_list_instances,
-    cmd_org_list_keys,
-)
-
-
 # ── argparse plumbing ──────────────────────────────────────────────────────
 
 
 def _build_parser() -> argparse.ArgumentParser:
+    from ._instance_schema import (
+        cmd_instance_create,
+        cmd_instance_delete,
+        cmd_instance_get,
+        cmd_schema_dry_run,
+        cmd_schema_get,
+        cmd_schema_migrations_get,
+        cmd_schema_migrations_list,
+        cmd_schema_update,
+        cmd_xmd_convert,
+        cmd_xmd_enhance,
+        cmd_xmd_generate,
+        cmd_xmd_validate,
+        cmd_xmd_validate_json,
+        cmd_xmd_validate_yaml,
+    )
+    from ._org_cluster import (
+        cmd_org_list_clusters,
+        cmd_org_list_instances,
+        cmd_org_list_keys,
+    )
+
     p = _help.XmemCliArgumentParser(
         prog=CLI_NAME,
         description="xmemcli — CLI for the xmemory HTTP API (read/write, instance ops, key list).",
@@ -1263,7 +1265,7 @@ def _build_parser() -> argparse.ArgumentParser:
         "--rc-dir",
         help=f"Directory for {RC_FILENAME} (auth login writes here; reads walk up to $HOME)",
     )
-    # Operator-only override; omitted from --help (maxims/API-CLIENTS.yml — One addressing axis for agents).
+    # Operator-only cluster override; omitted from --help (not agent-facing).
     p.add_argument("--cluster-id", help=argparse.SUPPRESS)
     p.add_argument(
         "--json",
@@ -1528,6 +1530,12 @@ def _build_parser() -> argparse.ArgumentParser:
         help="Fetch one migration record by id (MCP get_schema_migration)",
         add_help=False,
     )
+    pschmg.add_argument(
+        "instance_id_arg",
+        metavar="instance_id",
+        nargs="?",
+        help=f"Instance id (default ${ENV_INSTANCE_ID} or --instance-id)",
+    )
     pschmg.add_argument(
         "migration_id_arg",
         metavar="migration_id",
@@ -1632,13 +1640,7 @@ def _build_parser() -> argparse.ArgumentParser:
     return p
 
 
-_WRITE_STATUS_ALIASES = frozenset({
-    "write_status",
-    "writestatus",
-    "async_write_status",
-    "asyncwritestatus",
-    "async-write-status",
-})
+_WRITE_STATUS_ALIASES = _help._WRITE_STATUS_ALIAS_NAMES
 
 # Silent auth shortcuts — normalized before parse; not listed in the overview.
 _AUTH_LOGIN_ALIASES = frozenset({"login", "signin"})
@@ -1679,6 +1681,17 @@ def _auto_resolve_single_instance_id(args: argparse.Namespace, api_key: str) ->
     return instance_id, warning
 
 
+def _normalize_org_list_instances_argv(stripped: list[str]) -> list[str] | None:
+    """Map silent ``instances`` / ``list instances`` spellings to ``org list instances``."""
+    if not stripped:
+        return None
+    if stripped[0] == "instances":
+        return ["org", "list", "instances", *stripped[1:]]
+    if len(stripped) >= 2 and stripped[0] == "list" and stripped[1] == "instances":
+        return ["org", "list", "instances", *stripped[2:]]
+    return None
+
+
 def _normalize_auth_argv(stripped: list[str]) -> list[str] | None:
     """Map silent login/logout spellings to ``auth login`` / ``auth logout``."""
     if not stripped:
@@ -1726,36 +1739,17 @@ def _normalize_argv(argv: list[str]) -> list[str]:
         return ["write-status", *stripped[1:]]
     if len(stripped) >= 2 and stripped[0] == "quota" and stripped[1] == "get":
         return ["quota", *stripped[2:]]
+    org_list_instances = _normalize_org_list_instances_argv(stripped)
+    if org_list_instances is not None:
+        return org_list_instances
     auth_normalized = _normalize_auth_argv(stripped)
     if auth_normalized is not None:
         return auth_normalized
     return stripped
 
 
-def _global_prefix(argv: list[str]) -> list[str]:
-    """Return leading global flags from ``argv`` (preserving order)."""
-    out: list[str] = []
-    i = 0
-    while i < len(argv):
-        tok = argv[i]
-        if tok in _help.GLOBAL_STORE_TRUE_FLAGS:
-            out.append(tok)
-            i += 1
-            continue
-        if tok in _help.GLOBAL_OPTION_FLAGS:
-            out.append(tok)
-            if i + 1 < len(argv) and not argv[i + 1].startswith("-"):
-                out.append(argv[i + 1])
-                i += 2
-            else:
-                i += 1
-            continue
-        break
-    return out
-
-
 def _parse_argv(argv: list[str]) -> list[str]:
-    """``argv`` for :func:`argparse.ArgumentParser.parse_args` — globals + normalized command."""
+    """``argv`` for `argparse.ArgumentParser.parse_args` — globals + normalized command."""
     globals_part, stripped = _help.collect_global_flags(argv)
     command = _normalize_argv(stripped)
     if not command:
@@ -1768,12 +1762,13 @@ def _emit_help(
     path: tuple[str, ...],
     *,
     machine_json: bool,
-) -> None:
+) -> dict[str, Any]:
     doc = _help.build_help_document(parser, path)
     if machine_json:
         emit(CliOutput(OutputKind.HELP, doc), force_json=True)
     else:
         _help.render_help_document(doc)
+    return doc
 
 
 def main(argv: list[str] | None = None) -> int:
@@ -1786,7 +1781,9 @@ def main(argv: list[str] | None = None) -> int:
         return EXIT_OK
     help_path = _help.help_target(command)
     if help_path is not None:
-        _emit_help(parser, help_path, machine_json=machine_json)
+        doc = _emit_help(parser, help_path, machine_json=machine_json)
+        if doc.get("kind") == "unknown":
+            return EXIT_USAGE
         return EXIT_OK
     try:
         args = parser.parse_args(_parse_argv(argv_list))
@@ -1809,7 +1806,11 @@ def main(argv: list[str] | None = None) -> int:
     except UsageError as exc:
         # Pre-flight resolution errors (missing key, malformed rc, …) still go
         # through emit() so machine mode gets a single JSON ERROR document.
-        emit(_with_cli_warnings(exc.output, args, force_json=machine_json or args.json), force_json=machine_json or args.json)
+        force_json = machine_json or args.json
+        emit(
+            _with_cli_warnings(exc.output, args, force_json=force_json),
+            force_json=force_json,
+        )
         return exc.exit_code
     except KeyboardInterrupt:
         if machine_json or args.json: