agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/commands/traces/__init__.py

@@ -0,0 +1,155 @@
+"""`agentcore traces list|get` (port of src/cli/commands/traces)."""
+
+import json
+import math
+from datetime import UTC, datetime
+from typing import Any
+
+import typer
+
+from agentcore.cli.commands.logs.guards import get_project_root_mismatch, project_exists, require_project
+from agentcore.cli.commands.traces import action
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.groups import group
+from agentcore.lib.result import serialize_result
+from agentcore.operations import resolve_agent as resolve_agent_ops
+
+SINCE_HELP = "Start time — defaults to 12h ago (e.g. 5m, 1h, 2d, ISO 8601, epoch ms)"
+UNTIL_HELP = "End time — defaults to now (e.g. now, 1h, ISO 8601, epoch ms)"
+
+
+def _dumps(payload: dict[str, Any]) -> str:
+    return json.dumps({k: v for k, v in payload.items() if v is not None}, separators=(",", ":"), ensure_ascii=False)
+
+
+def format_timestamp(ts: str) -> str:
+    try:
+        num = float(ts)
+    except ValueError:
+        return ts
+    if math.isnan(num):
+        return ts
+    return datetime.fromtimestamp(num / 1000, tz=UTC).strftime("%Y-%m-%d %H:%M:%SZ")
+
+
+def _require_traces_project(as_json: bool) -> None:
+    if not as_json:
+        require_project()
+        return
+    if not project_exists():
+        typer.echo(_dumps({"success": False, "error": "No agentcore project found. Run agentcore create first."}))
+        raise typer.Exit(1)
+    project_root = get_project_root_mismatch()
+    if project_root:
+        typer.echo(
+            _dumps(
+                {"success": False, "error": f"Please run this command from your project root directory: {project_root}"}
+            )
+        )
+        raise typer.Exit(1)
+
+
+def _print_failure(result: dict[str, Any], as_json: bool) -> None:
+    if as_json:
+        typer.echo(_dumps(serialize_result(result)))
+    else:
+        typer.secho(f"Error: {result['error']}", fg=typer.colors.RED)
+        if result.get("consoleUrl"):
+            typer.secho(f"Console: {result['consoleUrl']}", fg="bright_black")
+    raise typer.Exit(1)
+
+
+def _handle_unexpected(exc: Exception, as_json: bool) -> None:
+    if as_json:
+        typer.echo(_dumps({"success": False, "error": get_error_message(exc)}))
+    else:
+        typer.secho(f"Error: {get_error_message(exc)}", fg=typer.colors.RED)
+    raise typer.Exit(1) from None
+
+
+def traces_list(
+    runtime: str | None = typer.Option(None, "--runtime", help="Select specific runtime"),
+    limit: str = typer.Option("20", "--limit", help="Maximum number of traces to display"),
+    since: str | None = typer.Option(None, "--since", help=SINCE_HELP),
+    until: str | None = typer.Option(None, "--until", help=UNTIL_HELP),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """List recent traces for a deployed runtime"""
+    try:
+        _require_traces_project(as_json)
+        context = resolve_agent_ops.load_deployed_project_config()
+        result = action.handle_traces_list(
+            context, action.TracesListOptions(runtime=runtime, limit=limit, since=since, until=until, json=as_json)
+        )
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001 - top-level command boundary, as upstream
+        _handle_unexpected(exc, as_json)
+        return
+    if not result["success"]:
+        _print_failure(result, as_json)
+    if as_json:
+        typer.echo(_dumps(serialize_result(result)))
+        return
+
+    typer.secho(f"Traces for {result.get('agentName')} (target: {result.get('targetName')})", bold=True)
+    typer.echo(" ")
+    traces = result.get("traces") or []
+    if traces:
+        typer.echo(
+            typer.style(f"{'Trace ID':<34}", bold=True)
+            + typer.style(f"{'Timestamp':<22}", bold=True)
+            + typer.style(f"{'Session ID':<38}", bold=True)
+        )
+        for trace in traces:
+            typer.echo(
+                typer.style(f"{trace['traceId']:<34}", fg=typer.colors.CYAN)
+                + f"{format_timestamp(trace['timestamp']):<22}"
+                + typer.style(f"{trace.get('sessionId') or '-':<38}", fg=typer.colors.MAGENTA)
+            )
+    else:
+        typer.secho("No traces found in the specified time range.", fg=typer.colors.YELLOW)
+    typer.echo(" ")
+    if result.get("consoleUrl"):
+        typer.secho(f"Console: {result['consoleUrl']}", fg="bright_black")
+        typer.secho("Note: Traces may take 2-3 minutes to appear in CloudWatch", dim=True)
+
+
+def traces_get(
+    trace_id: str = typer.Argument(..., metavar="TRACEID"),
+    runtime: str | None = typer.Option(None, "--runtime", help="Select specific runtime"),
+    output: str | None = typer.Option(None, "--output", help="Output file path"),
+    since: str | None = typer.Option(None, "--since", help=SINCE_HELP),
+    until: str | None = typer.Option(None, "--until", help=UNTIL_HELP),
+    as_json: bool = typer.Option(False, "--json", help="Output as JSON"),
+) -> None:
+    """Download a trace to a JSON file"""
+    try:
+        _require_traces_project(as_json)
+        context = resolve_agent_ops.load_deployed_project_config()
+        result = action.handle_traces_get(
+            context,
+            trace_id,
+            action.TracesGetOptions(runtime=runtime, output=output, since=since, until=until, json=as_json),
+        )
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001 - top-level command boundary, as upstream
+        _handle_unexpected(exc, as_json)
+        return
+    if not result["success"]:
+        _print_failure(result, as_json)
+    if as_json:
+        typer.echo(_dumps(serialize_result(result)))
+        return
+    typer.secho(f"Trace saved to: {result.get('filePath')}", fg=typer.colors.GREEN)
+    if result.get("consoleUrl"):
+        typer.secho(f"Console: {result['consoleUrl']}", fg="bright_black")
+
+
+def register(app: typer.Typer) -> None:
+    traces = group("traces")
+    traces.command("list", help="List recent traces for a deployed runtime")(traces_list)
+    traces.command("get", help="Download a trace to a JSON file")(traces_get)
+    # Upstream alias `agentcore t`.
+    app.add_typer(traces, name="t", hidden=True)

agentcore/cli/commands/traces/action.py

@@ -0,0 +1,123 @@
+"""Port of src/cli/commands/traces/action.ts.
+
+Handlers return upstream's flat result dicts: ``{"success": True, "agentName", "targetName",
+"consoleUrl", ...}`` or ``{"success": False, "error": <exception>, "consoleUrl"?}`` (serialize with
+``agentcore.lib.result.serialize_result``).
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib.errors.types import ResourceNotFoundError, ValidationError
+from agentcore.lib.utils.time_parser import parse_time_string
+from agentcore.operations import traces as traces_ops
+from agentcore.operations.resolve_agent import DeployedProjectConfig, resolve_agent
+
+PYTHON_ONLY_ERROR = (
+    "Traces are only supported for Python agents. TypeScript agents do not support observability traces."
+)
+
+
+@dataclass
+class TracesListOptions:
+    runtime: str | None = None
+    limit: str | None = None
+    since: str | None = None
+    until: str | None = None
+    json: bool = False
+
+
+@dataclass
+class TracesGetOptions:
+    runtime: str | None = None
+    output: str | None = None
+    since: str | None = None
+    until: str | None = None
+    json: bool = False
+
+
+def _parse_int(value: str) -> int | None:
+    text = value.strip()
+    end = 0
+    while end < len(text) and (text[end].isdigit() or (end == 0 and text[end] in "+-")):
+        end += 1
+    try:
+        return int(text[:end])
+    except ValueError:
+        return None
+
+
+def _resolve(context: DeployedProjectConfig, runtime: str | None) -> tuple[Any, str] | dict[str, Any]:
+    resolved = resolve_agent(context, runtime)
+    if not resolved.success:
+        return {"success": False, "error": ResourceNotFoundError(resolved.error or "")}
+    agent = resolved.agent
+    spec = next((r for r in context.project.runtimes or [] if r.name == agent.agent_name), None)
+    entrypoint = str(spec.entrypoint) if spec is not None and spec.entrypoint else ""
+    if not (entrypoint.endswith(".py") or ".py:" in entrypoint):
+        return {"success": False, "error": ValidationError(PYTHON_ONLY_ERROR)}
+    console_url = traces_ops.build_trace_console_url(
+        region=agent.region, account_id=agent.account_id, runtime_id=agent.runtime_id, agent_name=agent.agent_name
+    )
+    return agent, console_url
+
+
+def _times(since: str | None, until: str | None) -> tuple[int | None, int | None]:
+    return (parse_time_string(since) if since else None, parse_time_string(until) if until else None)
+
+
+def handle_traces_list(context: DeployedProjectConfig, options: TracesListOptions) -> dict[str, Any]:
+    resolved = _resolve(context, options.runtime)
+    if isinstance(resolved, dict):
+        return resolved
+    agent, console_url = resolved
+
+    limit = _parse_int(options.limit) if options.limit else 20
+    if limit is None:
+        return {"success": False, "error": ValidationError("--limit must be a number")}
+
+    start_time, end_time = _times(options.since, options.until)
+    result = traces_ops.list_traces(
+        region=agent.region,
+        runtime_id=agent.runtime_id,
+        agent_name=agent.agent_name,
+        limit=limit,
+        start_time=start_time,
+        end_time=end_time,
+    )
+    if not result.success:
+        return {"success": False, "error": result.error, "consoleUrl": console_url}
+    return {
+        "success": True,
+        "agentName": agent.agent_name,
+        "targetName": agent.target_name,
+        "consoleUrl": console_url,
+        "traces": result.value["traces"],
+    }
+
+
+def handle_traces_get(context: DeployedProjectConfig, trace_id: str, options: TracesGetOptions) -> dict[str, Any]:
+    resolved = _resolve(context, options.runtime)
+    if isinstance(resolved, dict):
+        return resolved
+    agent, console_url = resolved
+
+    start_time, end_time = _times(options.since, options.until)
+    result = traces_ops.get_trace(
+        region=agent.region,
+        runtime_id=agent.runtime_id,
+        agent_name=agent.agent_name,
+        trace_id=trace_id,
+        output_path=options.output,
+        start_time=start_time,
+        end_time=end_time,
+    )
+    if not result.success:
+        return {"success": False, "error": result.error, "consoleUrl": console_url}
+    return {
+        "success": True,
+        "agentName": agent.agent_name,
+        "targetName": agent.target_name,
+        "consoleUrl": console_url,
+        "filePath": result.value["filePath"],
+    }

agentcore/cli/commands/update/__init__.py

@@ -0,0 +1,63 @@
+"""`agentcore update` / `agentcore update cli` (port of src/cli/commands/update/command.tsx)."""
+
+from __future__ import annotations
+
+import typer
+
+from agentcore.cli.commands.update.action import get_install_command_display, handle_update
+from agentcore.cli.constants import ANSI
+from agentcore.cli.errors import get_error_message
+from agentcore.cli.groups import group
+
+
+def _run_update(check: bool, rerun_command: str) -> None:
+    green, yellow, red, reset = ANSI.green, ANSI.yellow, ANSI.red, ANSI.reset
+    try:
+        typer.echo("Checking for updates...")
+        result = handle_update(check)
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"{red}Error: {get_error_message(exc)}{reset}")
+        raise typer.Exit(1) from None
+
+    if result.status == "up-to-date":
+        typer.echo(f"{green}You are already on the latest version ({result.current_version}){reset}")
+    elif result.status == "newer-local":
+        typer.echo(
+            f"{yellow}Your version ({result.current_version}) is newer than the published version "
+            f"({result.latest_version}){reset}"
+        )
+    elif result.status == "update-available":
+        typer.echo(f"Update available: {result.current_version} → {green}{result.latest_version}{reset}")
+        typer.echo(f"Run `{rerun_command}` to install the update.")
+    elif result.status == "manual-install":
+        typer.echo(f"Update available: {result.current_version} → {green}{result.latest_version}{reset}")
+        typer.echo(f"Run `{result.install_command}` to install the update.")
+    elif result.status == "updated":
+        typer.echo(f"{green}Successfully updated to {result.latest_version}{reset}")
+    else:
+        typer.echo(f"{red}Failed to install update. Try running: {get_install_command_display()}{reset}")
+        raise typer.Exit(1)
+
+
+def register(app: typer.Typer) -> None:
+    update = group("update")
+    update.info.no_args_is_help = False
+
+    @update.callback(invoke_without_command=True)
+    def update_root(
+        ctx: typer.Context,
+        check: bool = typer.Option(False, "-c", "--check", help="Check for updates without installing"),
+    ) -> None:
+        """Check for and install CLI updates"""
+        if ctx.invoked_subcommand is not None:
+            return
+        _run_update(check, "agentcore update")
+
+    @update.command("cli", help="Update the AgentCore CLI to the latest version")
+    def update_cli(
+        check: bool = typer.Option(False, "-c", "--check", help="Check for updates without installing"),
+    ) -> None:
+        _run_update(check, "agentcore update cli")
+
+
+__all__ = ["register"]

agentcore/cli/commands/update/action.py

@@ -0,0 +1,164 @@
+"""`agentcore update` logic (port of src/cli/commands/update/action.ts).
+
+Deliberate deviation: the Python port is published on PyPI as ``agentcore-cli``. The latest version
+comes from the PyPI JSON API; installs run ``python -m pip install -U agentcore-cli`` — unless the
+CLI lives in a pipx or uv-tool environment, in which case the matching upgrade command is printed
+instead of running pip.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+from dataclasses import dataclass
+from typing import Literal
+
+from agentcore import __version__
+
+PACKAGE_NAME = "agentcore-cli"
+PYPI_URL = f"https://pypi.org/pypi/{PACKAGE_NAME}/json"
+PIP_INSTALL_ARGS = [sys.executable, "-m", "pip", "install", "-U", PACKAGE_NAME]
+
+InstallMethod = Literal["pip", "pipx", "uv"]
+UpdateStatus = Literal["up-to-date", "newer-local", "update-available", "updated", "update-failed", "manual-install"]
+
+
+def _http_get_json(url: str) -> tuple[int, str, object]:
+    """Network seam (tests replace it): returns (status, reason, parsed JSON or None)."""
+    request = urllib.request.Request(url, headers={"accept": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=10) as response:  # noqa: S310 - fixed https URL
+            return response.status, response.reason or "", json.loads(response.read())
+    except urllib.error.HTTPError as exc:
+        return exc.code, exc.reason or "", None
+
+
+def fetch_latest_version() -> str:
+    status, reason, data = _http_get_json(PYPI_URL)
+    if not 200 <= status < 300 or not isinstance(data, dict):
+        raise Exception(f"Failed to fetch latest version: {reason}")
+    return str(data["info"]["version"])
+
+
+def _semver_compare(current: str, latest: str) -> int:
+    """Upstream's semver-style comparison (1 when ``latest`` is newer)."""
+
+    def parse(v: str) -> tuple[list[float], str]:
+        core, _, prerelease = v.partition("-")
+        nums: list[float] = []
+        for part in core.split("."):
+            try:
+                nums.append(float(part))
+            except ValueError:
+                nums.append(float("nan"))
+        return nums, prerelease
+
+    curr, lat = parse(current), parse(latest)
+    for i in range(3):
+        c = curr[0][i] if i < len(curr[0]) else 0
+        n = lat[0][i] if i < len(lat[0]) else 0
+        if n > c:
+            return 1
+        if n < c:
+            return -1
+    if not curr[1] and not lat[1]:
+        return 0
+    if not curr[1]:
+        return -1
+    if not lat[1]:
+        return 1
+    cs, ls = curr[1].split("."), lat[1].split(".")
+    for i in range(max(len(cs), len(ls))):
+        if i >= len(cs):
+            return 1
+        if i >= len(ls):
+            return -1
+        a, b = cs[i], ls[i]
+        if a.isdigit() and b.isdigit():
+            if int(b) > int(a):
+                return 1
+            if int(b) < int(a):
+                return -1
+        else:
+            if b > a:
+                return 1
+            if b < a:
+                return -1
+    return 0
+
+
+def compare_versions(current: str, latest: str) -> int:
+    """1 if ``latest`` is newer, -1 if older, 0 if equal. PEP 440 when both parse, else semver."""
+    from packaging.version import InvalidVersion, Version
+
+    try:
+        c, n = Version(current), Version(latest)
+    except InvalidVersion:
+        return _semver_compare(current, latest)
+    return 1 if n > c else -1 if n < c else 0
+
+
+def detect_install_method(prefix: str | None = None) -> InstallMethod:
+    """pipx and ``uv tool`` keep each tool in its own venv under a recognisable directory."""
+    parts = [p.lower() for p in os.path.normpath(prefix or sys.prefix).split(os.sep)]
+    for i, part in enumerate(parts[:-1]):
+        if part == "venvs" and i > 0 and "pipx" in parts[i - 1]:
+            return "pipx"
+        if part == "tools" and i > 0 and parts[i - 1] == "uv":
+            return "uv"
+    return "pip"
+
+
+def get_install_command_display(method: InstallMethod | None = None) -> str:
+    method = method or detect_install_method()
+    if method == "pipx":
+        return f"pipx upgrade {PACKAGE_NAME}"
+    if method == "uv":
+        return f"uv tool upgrade {PACKAGE_NAME}"
+    return f"pip install -U {PACKAGE_NAME}"
+
+
+def _run_pip_install() -> None:
+    subprocess.run(PIP_INSTALL_ARGS, check=True)
+
+
+@dataclass
+class UpdateResult:
+    status: UpdateStatus
+    current_version: str
+    latest_version: str
+    install_command: str | None = None
+
+
+def handle_update(check_only: bool) -> UpdateResult:
+    latest = fetch_latest_version()
+    comparison = compare_versions(__version__, latest)
+    if comparison == 0:
+        return UpdateResult("up-to-date", __version__, latest)
+    if comparison < 0:
+        return UpdateResult("newer-local", __version__, latest)
+    if check_only:
+        return UpdateResult("update-available", __version__, latest)
+    method = detect_install_method()
+    if method != "pip":
+        return UpdateResult("manual-install", __version__, latest, get_install_command_display(method))
+    try:
+        _run_pip_install()
+        return UpdateResult("updated", __version__, latest)
+    except (OSError, subprocess.CalledProcessError):
+        return UpdateResult("update-failed", __version__, latest)
+
+
+__all__ = [
+    "PIP_INSTALL_ARGS",
+    "PYPI_URL",
+    "UpdateResult",
+    "compare_versions",
+    "detect_install_method",
+    "fetch_latest_version",
+    "get_install_command_display",
+    "handle_update",
+]

agentcore/cli/commands/validate.py

@@ -0,0 +1,165 @@
+"""`agentcore validate` (port of src/cli/commands/validate)."""
+
+import json
+import os
+
+import typer
+from rich.console import Console
+
+from agentcore.lib.errors.types import (
+    ConfigNotFoundError,
+    ConfigParseError,
+    ConfigReadError,
+    ConfigValidationError,
+    NoProjectError,
+)
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import ConfigIO
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.lib.utils.credentials import SecureCredentials
+from agentcore.lib.utils.env import read_env_file
+from agentcore.operations.deploy.preflight import validate_harness_specs  # noqa: E402
+from agentcore.primitives.credential_utils import (
+    compute_payment_credential_env_var_names,
+    compute_stripe_privy_credential_env_var_names,
+)
+
+DESCRIPTION = "Validate agentcore/ config files."
+
+
+def _expected_vars(connector) -> list[str]:
+    """Env vars a manual payment connector needs in .env.local."""
+    if (connector.provider or "CoinbaseCDP") == "StripePrivy":
+        v = compute_stripe_privy_credential_env_var_names(connector.credential_name)
+        return [v.app_id, v.app_secret, v.authorization_private_key, v.authorization_id]
+    v = compute_payment_credential_env_var_names(connector.credential_name)
+    return [v.api_key_id, v.api_key_secret, v.wallet_secret]
+
+
+def _validate_payments(project_spec, config_root: str) -> Exception | None:
+    payments = project_spec.payments or []
+    if not payments:
+        return None
+
+    credentials = {c.name: c for c in reversed(project_spec.credentials or [])}  # first match wins
+    for payment in payments:
+        if not payment.connectors:
+            return Exception(
+                f'Payment manager "{payment.name}" has no connectors. Add a connector with '
+                f"`agentcore add payment-connector --manager {payment.name}`"
+            )
+        for connector in payment.connectors:
+            if connector.provision_mode == "QUICK_CREATE":
+                continue
+            credential = credentials.get(connector.credential_name)
+            if credential is None:
+                return Exception(
+                    f'Payment connector "{connector.name}" (manager "{payment.name}") references credential '
+                    f'"{connector.credential_name}" which does not exist.'
+                )
+            if credential.authorizer_type != "PaymentCredentialProvider":
+                return Exception(
+                    f'Payment connector "{connector.name}" references credential "{connector.credential_name}" '
+                    f'with type "{credential.authorizer_type}" — expected "PaymentCredentialProvider".'
+                )
+            connector_provider = connector.provider or "CoinbaseCDP"
+            credential_provider = getattr(credential, "provider", None)
+            if credential_provider and credential_provider != connector_provider:
+                return Exception(
+                    f'Payment connector "{connector.name}" uses provider "{connector_provider}" but credential '
+                    f'"{connector.credential_name}" is configured for "{credential_provider}".'
+                )
+
+    manual = [c for p in payments for c in p.connectors if c.provision_mode != "QUICK_CREATE"]
+    env_path = os.path.join(config_root, ".env.local")
+    if manual and not os.path.exists(env_path):
+        expected = "\n".join(f"  {name}" for c in manual for name in _expected_vars(c))
+        return Exception(
+            f"agentcore/.env.local not found. Payment credentials required:\n{expected}\n\n"
+            "Run 'agentcore add payment-connector --manager <name>' to set credentials interactively."
+        )
+    if os.path.exists(env_path):
+        try:
+            creds = SecureCredentials.from_env_vars(read_env_file(config_root))
+        except Exception as exc:  # noqa: BLE001
+            return Exception(
+                f"Failed to read .env.local: {exc}. Fix the file or re-run 'agentcore add payment-connector' "
+                "to set credentials."
+            )
+        for payment in payments:
+            for connector in payment.connectors:
+                if connector.provision_mode == "QUICK_CREATE":
+                    continue
+                missing = [name for name in _expected_vars(connector) if not (creds.get(name) or "").strip()]
+                if missing:
+                    provider = connector.provider or "CoinbaseCDP"
+                    return Exception(
+                        f'Missing {provider} credentials for connector "{connector.name}" in .env.local: '
+                        + ", ".join(missing)
+                    )
+    return None
+
+
+def _format_error(err: Exception, file_name: str) -> str:
+    if isinstance(err, ConfigValidationError):
+        return str(err)
+    cause = err.__cause__ if err.__cause__ is not None else err
+    if isinstance(err, ConfigParseError):
+        return f"Invalid JSON in {file_name}: {cause}"
+    if isinstance(err, ConfigReadError):
+        return f"Failed to read {file_name}: {cause}"
+    if isinstance(err, ConfigNotFoundError):
+        return f"Required file not found: {file_name}"
+    return str(err)
+
+
+def handle_validate(directory: str | None = None) -> Ok[None] | Err[Exception]:
+    config_root = find_config_root(directory or os.getcwd())
+    if not config_root:
+        return Err(NoProjectError())
+
+    io = ConfigIO(base_dir=config_root)
+    try:
+        project_spec = io.read_project_spec()
+    except Exception as exc:  # noqa: BLE001
+        return Err(Exception(_format_error(exc, "agentcore.json")))
+
+    if payment_error := _validate_payments(project_spec, config_root):
+        return Err(payment_error)
+
+    try:
+        io.read_aws_deployment_targets()
+    except Exception as exc:  # noqa: BLE001
+        return Err(Exception(_format_error(exc, "aws-targets.json")))
+
+    if io.config_exists("state"):
+        try:
+            io.read_deployed_state()
+        except Exception as exc:  # noqa: BLE001
+            return Err(Exception(_format_error(exc, ".cli/state.json")))
+
+    try:
+        validate_harness_specs(project_spec, config_root)
+    except Exception as exc:  # noqa: BLE001
+        return Err(exc)
+
+    return Ok(None)
+
+
+def register(app: typer.Typer) -> None:
+    @app.command("validate", help=DESCRIPTION)
+    def validate(
+        directory: str | None = typer.Option(
+            None, "-d", "--directory", help="Project directory containing agentcore config"
+        ),
+        as_json: bool = typer.Option(False, "--json", help="Output as JSON [non-interactive]"),
+    ) -> None:
+        result = handle_validate(directory)
+        if as_json:
+            payload = {"success": True} if result.success else {"success": False, "error": str(result.error)}
+            typer.echo(json.dumps(payload, separators=(",", ":")))
+        elif result.success:
+            Console().print("[green]Valid[/green]")
+        else:
+            Console().print(str(result.error), style="red", markup=False, highlight=False, soft_wrap=True)
+        raise typer.Exit(0 if result.success else 1)