aac-cli 0.2.6__tar.gz → 0.2.7__tar.gz

{aac_cli-0.2.6 → aac_cli-0.2.7}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.6
+Version: 0.2.7
 Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
 Author: Agent Authority Cloud Project
 License-Expression: Apache-2.0
-Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/aeg.html
+Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/cli/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -32,6 +37,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -59,7 +68,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -796,6 +805,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

aac_cli-0.2.6/aac_cli.egg-info/PKG-INFO → aac_cli-0.2.7/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: aac-cli
-Version: 0.2.6
-Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
-Author: Agent Authority Cloud Project
-License-Expression: Apache-2.0
-Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/aeg.html
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: httpx>=0.28
-Requires-Dist: cryptography>=42.0
-Requires-Dist: PyYAML>=6.0
-Requires-Dist: pyvis<0.4,>=0.3.2
-Requires-Dist: jsonschema>=4.18
-Provides-Extra: test
-Requires-Dist: pytest>=8.0; extra == "test"
-Requires-Dist: pytest-httpx>=0.30; extra == "test"
-Dynamic: license-file
-
 # aac-cli — the `aac` command
 
 `aac` is the command-line tool for tenants of Agent Authority Cloud (AAC).
@@ -32,6 +10,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -59,7 +41,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -796,6 +778,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

{aac_cli-0.2.6 → aac_cli-0.2.7}/aac_cli/__init__.py

@@ -10,4 +10,4 @@ entrypoint (`aac_cli.cli:entrypoint`).
 # test in bin/tests/test_cli_version_parity.py. A literal keeps the
 # shipped code free of import-time metadata lookups (and their
 # not-installed failure mode).
-__version__ = "0.2.6"
+__version__ = "0.2.7"

{aac_cli-0.2.6 → aac_cli-0.2.7}/aac_cli/agent_cli.py

@@ -47,7 +47,15 @@ from aac_cli.agent_record import (
     read_record,
     write_record,
 )
-from aac_cli.config import CliConfigError, CliUsageError, cli_home, credentials_path
+from aac_cli.config import (
+    CANONICAL_TENANT_ID_PATTERN,
+    JSON_OUTPUT_DEFAULT,
+    CliConfigError,
+    CliUsageError,
+    cli_home,
+    credentials_path,
+    validate_hosted_trust_domain,
+)
 from aac_cli.config_render import configuration_summary, outbound_ca_bundle
 from aac_cli.init_cli import (
     SHARED_MATERIAL_FLAGS,
@@ -88,6 +96,18 @@ def _load(args: argparse.Namespace) -> tuple[AgentPaths, TenantPaths | None, Age
             f"[{wanted}]. The `aac agent` commands find the profile through the agent, so omit "
             f"--profile, or name an agent of profile [{wanted}] with --agent."
         )
+    if getattr(args, "field", None):
+        # Structured status retains its existing diagnostic behavior. Scalar
+        # consumers require a complete canonical identity before any stdout.
+        if not isinstance(record.tenant_id, str) or not CANONICAL_TENANT_ID_PATTERN.fullmatch(
+            record.tenant_id
+        ):
+            raise CliConfigError(f"agent {agent.name!r} has no valid tenant identity")
+        if not isinstance(record.hosted_trust_domain, str):
+            raise CliConfigError(f"agent {agent.name!r} has no valid hosted trust domain")
+        domain = validate_hosted_trust_domain(record.tenant_id, record.hosted_trust_domain)
+        if record.workload_spiffe_id != f"spiffe://{domain}/{record.workload_path}":
+            raise CliConfigError(f"agent {agent.name!r} has an invalid workload identity")
     tenant = tenant_paths(record.tenant_id) if record.tenant_id else None
     return agent, tenant, record
 
@@ -203,8 +223,19 @@ def _inventory_report(
 
 
 def cmd_agent_status(args: argparse.Namespace) -> int:
+    if getattr(args, "field", None) and args.remote:
+        raise CliUsageError("--field reports local identity only; omit --remote")
     agent, tenant, record = _load(args)
     health = assess(agent, tenant, record)
+    if getattr(args, "field", None):
+        value = getattr(record, args.field.replace("-", "_"))
+        if not health.healthy:
+            raise CliConfigError(
+                f"agent {agent.name!r} cannot supply {args.field}: "
+                f"{next_step(agent, tenant, record, health) or 'value unavailable'}"
+            )
+        print(value)
+        return 0
     certificates = {
         label: {
             "not_after": report.not_after,
@@ -603,14 +634,24 @@ def cmd_agent_list(args: argparse.Namespace) -> int:
 # --- parser ----------------------------------------------------------------------------
 
 
-def _agent_flags(parser: argparse.ArgumentParser) -> None:
+def _agent_flags(parser: argparse.ArgumentParser, *, scalar: bool = False) -> None:
     parser.add_argument(
         "--agent",
         required=True,
         help="Target agent name under ~/.aac/agents/.",
     )
-    parser.add_argument(
-        "--output", choices=("json", "table"), default="json", help="Output mode (JSON by default)."
+    output = parser.add_mutually_exclusive_group() if scalar else parser
+    if scalar:
+        output.add_argument(
+            "--field",
+            choices=("tenant-id", "hosted-trust-domain", "workload-spiffe-id"),
+            help="Print one local identity value; fail if unavailable or the agent needs attention. Cannot combine with --output or --remote.",
+        )
+    output.add_argument(
+        "--output",
+        choices=("json", "table"),
+        default=JSON_OUTPUT_DEFAULT if scalar else "json",
+        help="Output mode (JSON by default).",
     )
     parser.add_argument(
         "--profile",
@@ -639,7 +680,7 @@ def add_agent_parser(nouns: argparse._SubParsersAction) -> None:
         "status",
         help="Report what exists, certificate expiry, permission problems and the next command.",
     )
-    _agent_flags(status)
+    _agent_flags(status, scalar=True)
     status.add_argument(
         "--remote",
         action="store_true",

{aac_cli-0.2.6 → aac_cli-0.2.7}/aac_cli/cli.py

@@ -97,6 +97,7 @@ from aac_cli.api_key_rotation_state import (
 )
 from aac_cli.config import (
     CANONICAL_TENANT_ID_PATTERN,
+    JSON_OUTPUT_DEFAULT,
     CliConfigError,
     CliUsageError,
     ResolvedConfig,
@@ -284,7 +285,7 @@ def _session_headers(config: ResolvedConfig) -> dict[str, str]:
     return {"Authorization": f"Bearer {credential.access_token}"}
 
 
-def _add_common_flags(parser: argparse.ArgumentParser) -> None:
+def _add_common_flags(parser: argparse.ArgumentParser, *, fields: tuple[str, ...] = ()) -> None:
     parser.add_argument(
         "--profile",
         default=None,
@@ -302,10 +303,17 @@ def _add_common_flags(parser: argparse.ArgumentParser) -> None:
         default=None,
         help="Data-plane-surface base URL (overrides profile).",
     )
-    parser.add_argument(
+    output = parser.add_mutually_exclusive_group() if fields else parser
+    if fields:
+        output.add_argument(
+            "--field",
+            choices=fields,
+            help="Print only the selected server-returned value; cannot combine with --output.",
+        )
+    output.add_argument(
         "--output",
         choices=("json", "table"),
-        default="json",
+        default=JSON_OUTPUT_DEFAULT if fields else "json",
         help="Output mode: json (the default) or table.",
     )
 
@@ -2350,7 +2358,9 @@ def _cmd_tenant_hosted_domain(args: argparse.Namespace) -> int:
                 file=sys.stderr,
             )
             return 3
-        if args.output == "table":
+        if getattr(args, "field", None):
+            print(domain)
+        elif args.output == "table":
             print(f"hosted_domain   : {domain}")
             _print_binding_row(payload["binding"])
         else:
@@ -4382,10 +4392,16 @@ def build_parser() -> argparse.ArgumentParser:
     profile_show.add_argument(
         "name", nargs="?", default=None, help="Profile name (default: selected)."
     )
-    profile_show.add_argument(
+    profile_output = profile_show.add_mutually_exclusive_group()
+    profile_output.add_argument(
+        "--field",
+        choices=("tenant-id",),
+        help="Print the effective tenant ID (AAC_TENANT_ID overrides stored binding); fail if unavailable. Cannot combine with --output.",
+    )
+    profile_output.add_argument(
         "--output",
         choices=("json", "table"),
-        default="json",
+        default=JSON_OUTPUT_DEFAULT,
         help="Output mode: json (the default) or table.",
     )
     profile_show.set_defaults(handler=cmd_profile_show)
@@ -5047,7 +5063,7 @@ def build_parser() -> argparse.ArgumentParser:
                 "      aac tenant bind-trust-domain --profile main --trust-domain example.com\n"
             ),
         )
-        _add_common_flags(hosted)
+        _add_common_flags(hosted, fields=() if reactivation else ("trust-domain",))
         hosted.add_argument(
             "--tenant-id", default=None, help="Tenant (defaults to the selected profile)."
         )

{aac_cli-0.2.6 → aac_cli-0.2.7}/aac_cli/config.py

@@ -64,6 +64,19 @@ from contextlib import contextmanager
 from dataclasses import dataclass
 from pathlib import Path
 
+
+class _OutputDefault(str):
+    """Keep explicit JSON distinguishable from argparse's implicit default.
+
+    Python 3.11 tracks mutually exclusive actions using identity against the
+    default. A plain interned ``"json"`` can therefore bypass the group when
+    passed explicitly. A distinct string subtype preserves the public default
+    and its generated reference while making normal argv strings explicit.
+    """
+
+
+JSON_OUTPUT_DEFAULT = _OutputDefault("json")
+
 __all__ = [
     "CANONICAL_TENANT_ID_PATTERN",
     "CliConfigError",

{aac_cli-0.2.6 → aac_cli-0.2.7}/aac_cli/profiles.py

@@ -205,6 +205,12 @@ def cmd_profile_show(args: argparse.Namespace) -> int:
         key for key in stored if key not in DEFAULT_SETTINGS and key != "hosted_trust_domain"
     )
     effective = resolve_settings(profile=name)
+    if getattr(args, "field", None):
+        tenant_id = effective["tenant_id"].value
+        if not tenant_id:
+            raise CliConfigError(f"profile {name!r} has no effective tenant ID")
+        print(tenant_id)
+        return 0
     payload = {
         "name": name,
         "selected": name == selected,

{aac_cli-0.2.6 → aac_cli-0.2.7}/aac_cli/reference.py

@@ -320,7 +320,7 @@ def _arguments_section(parser: argparse.ArgumentParser) -> list[str]:
 def _output_section(parser: argparse.ArgumentParser) -> list[str]:
     if not any("--output" in action.option_strings for action in parser._actions):
         return []
-    return [
+    lines = [
         "## Output",
         "",
         "`--output json` (the default) prints one JSON document to standard output; "
@@ -328,6 +328,16 @@ def _output_section(parser: argparse.ArgumentParser) -> list[str]:
         "diagnostics go to standard error, so the JSON stays parseable.",
         "",
     ]
+    if any("--field" in action.option_strings for action in parser._actions):
+        lines.extend(
+            [
+                "`--field` prints one unquoted value followed by a newline instead. "
+                "It cannot be combined with an explicit `--output`. A missing or invalid "
+                "value fails without scalar output; diagnostics go to standard error.",
+                "",
+            ]
+        )
+    return lines
 
 
 def _exit_codes_section() -> list[str]:

aac_cli-0.2.6/README.md → aac_cli-0.2.7/aac_cli.egg-info/PKG-INFO

@@ -1,3 +1,30 @@
+Metadata-Version: 2.4
+Name: aac-cli
+Version: 0.2.7
+Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
+Author: Agent Authority Cloud Project
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/cli/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+License-File: THIRD_PARTY_NOTICES.md
+Requires-Dist: httpx>=0.28
+Requires-Dist: cryptography>=42.0
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: pyvis<0.4,>=0.3.2
+Requires-Dist: jsonschema>=4.18
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-httpx>=0.30; extra == "test"
+Dynamic: license-file
+
 # aac-cli — the `aac` command
 
 `aac` is the command-line tool for tenants of Agent Authority Cloud (AAC).
@@ -10,6 +37,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -37,7 +68,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -774,6 +805,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

{aac_cli-0.2.6 → aac_cli-0.2.7}/pyproject.toml

@@ -32,7 +32,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aac-cli"
-version = "0.2.6"
+version = "0.2.7"
 description = "The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit)."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -42,6 +42,13 @@ license = "Apache-2.0"
 # aac_invoke_auth).
 license-files = ["LICENSE", "NOTICE", "THIRD_PARTY_NOTICES.md"]
 authors = [{ name = "Agent Authority Cloud Project" }]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
 
 dependencies = [
     # HTTP client (same floor as the workspace).
@@ -64,7 +71,7 @@ dependencies = [
 ]
 
 [project.urls]
-Documentation = "https://cascadeauth.github.io/aac-starter-guide/aeg.html"
+Documentation = "https://cascadeauth.github.io/aac-starter-guide/cli/"
 
 [project.optional-dependencies]
 test = [