agentcore-cli 0.31.1__py3-none-any.whl

agentcore/cli/groups.py

@@ -0,0 +1,23 @@
+"""Shared command groups (`run`, `pause`, `logs`, ...).
+
+Groups whose subcommands come from several feature areas are created once here; any command
+module attaches to them with ``group("run").command("eval")(...)``. `cli/main.py` mounts every
+group created this way.
+"""
+
+import typer
+
+from agentcore.cli.tree import GROUPS
+
+_groups: dict[str, typer.Typer] = {}
+
+
+def group(name: str) -> typer.Typer:
+    if name not in _groups:
+        help_text = GROUPS[name][0] if name in GROUPS else None
+        _groups[name] = typer.Typer(help=help_text, no_args_is_help=True)
+    return _groups[name]
+
+
+def created_groups() -> dict[str, typer.Typer]:
+    return dict(_groups)

agentcore/cli/interactive.py

@@ -0,0 +1,85 @@
+"""Interactive prompts that replace upstream's Ink TUI screens.
+
+Upstream runs a full-screen wizard when a command gets no flags. The Python port asks the
+same questions as sequential prompts. Every prompt exits cleanly (code 130) on Ctrl-C/Esc.
+"""
+
+import sys
+from collections.abc import Callable, Sequence
+from dataclasses import dataclass
+from typing import Any, TypeVar
+
+import questionary
+import typer
+
+T = TypeVar("T")
+
+
+def require_tty() -> None:
+    """Port of tui/guards/tty.ts: interactive flows must not hang in CI or piped stdin."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        typer.echo(
+            "Error: This command requires an interactive terminal. Use --help to see non-interactive flags.",
+            err=True,
+        )
+        raise typer.Exit(1)
+
+
+def _answer(question: questionary.Question) -> Any:
+    value = question.ask()
+    if value is None:  # questionary returns None on Ctrl-C / Esc
+        raise typer.Exit(130)
+    return value
+
+
+@dataclass(frozen=True)
+class Choice:
+    title: str
+    value: Any
+    description: str | None = None
+    disabled: str | None = None
+
+
+def select(message: str, choices: Sequence[Choice | str], default: Any = None) -> Any:
+    qchoices = [
+        c
+        if isinstance(c, str)
+        else questionary.Choice(c.title, value=c.value, description=c.description, disabled=c.disabled)
+        for c in choices
+    ]
+    return _answer(questionary.select(message, choices=qchoices, default=default))
+
+
+def checkbox(message: str, choices: Sequence[Choice | str], checked: Sequence[Any] = ()) -> list[Any]:
+    qchoices = [
+        questionary.Choice(c, value=c, checked=c in checked)
+        if isinstance(c, str)
+        else questionary.Choice(c.title, value=c.value, description=c.description, checked=c.value in checked)
+        for c in choices
+    ]
+    return _answer(questionary.checkbox(message, choices=qchoices))
+
+
+def text(
+    message: str,
+    default: str = "",
+    validate: Callable[[str], str | None] | None = None,
+    secret: bool = False,
+) -> str:
+    """``validate`` returns an error message, or None when the value is acceptable."""
+
+    def _validate(value: str) -> bool | str:
+        if validate is None:
+            return True
+        error = validate(value)
+        return True if error is None else error
+
+    prompt = questionary.password if secret else questionary.text
+    kwargs: dict[str, Any] = {"validate": _validate}
+    if not secret:
+        kwargs["default"] = default
+    return _answer(prompt(message, **kwargs))
+
+
+def confirm(message: str, default: bool = False) -> bool:
+    return _answer(questionary.confirm(message, default=default))

agentcore/cli/main.py

@@ -0,0 +1,137 @@
+"""Entry point for the `agentcore` command (port of src/cli/cli.ts).
+
+Commands are discovered: every module in ``agentcore.cli.commands`` that defines
+``register(app)`` is registered, and add/remove subcommands come from the primitive registry.
+Anything in ``agentcore.cli.tree`` still unregistered after that becomes a stub.
+"""
+
+import importlib
+import pkgutil
+
+import typer
+from rich.console import Console
+
+import agentcore.cli.commands as commands_package
+from agentcore import __version__
+from agentcore.cli.groups import created_groups
+from agentcore.cli.tree import GROUPS, PROGRAM_DESCRIPTION, RESOURCE_KINDS, TOP_LEVEL
+from agentcore.primitives.registry import all_primitives
+
+err = Console(stderr=True)
+
+# Unported stubs accept any arguments so `--help` and argument parsing never get in the way.
+STUB_SETTINGS = {"allow_extra_args": True, "ignore_unknown_options": True}
+
+app = typer.Typer(
+    name="agentcore",
+    help=PROGRAM_DESCRIPTION,
+    no_args_is_help=True,
+    context_settings={"help_option_names": ["-h", "--help"]},
+    # Upstream help text uses literal "[non-interactive]" tags, which Rich markup would swallow.
+    rich_markup_mode=None,
+)
+add_app = typer.Typer(help="Add resources to project config.", no_args_is_help=True)
+remove_app = typer.Typer(help="Remove resources from project config.", no_args_is_help=True)
+
+
+def _stub(path: str):
+    def command(ctx: typer.Context) -> None:
+        err.print(f"[yellow]`agentcore {path}` is not ported to Python yet.[/yellow]")
+        raise typer.Exit(2)
+
+    return command
+
+
+def _command_names(typer_app: typer.Typer) -> set[str]:
+    names = {c.name for c in typer_app.registered_commands if c.name}
+    return names | {g.name for g in typer_app.registered_groups if g.name}
+
+
+def _group(typer_app: typer.Typer, name: str) -> typer.Typer | None:
+    for info in typer_app.registered_groups:
+        if info.name == name:
+            return info.typer_instance
+    return None
+
+
+def _register_commands() -> None:
+    for info in sorted(pkgutil.iter_modules(commands_package.__path__), key=lambda m: m.name):
+        if info.name.startswith("_"):
+            continue
+        module = importlib.import_module(f"{commands_package.__name__}.{info.name}")
+        register = getattr(module, "register", None)
+        if callable(register):
+            register(app)
+
+
+def _register_primitives() -> None:
+    from agentcore.cli.commands.add import install_add_shell
+    from agentcore.cli.commands.remove import install_remove_shell
+
+    # Bare `agentcore add` / `agentcore remove` menus and `remove all`.
+    install_add_shell(add_app)
+    install_remove_shell(remove_app)
+    for primitive in all_primitives():
+        primitive.register_commands(add_app, remove_app)
+
+
+def _stub_missing(typer_app: typer.Typer, prefix: str, commands: dict[str, str]) -> None:
+    existing = _command_names(typer_app)
+    for name, help_text in commands.items():
+        if name not in existing:
+            path = f"{prefix} {name}".strip()
+            typer_app.command(name, help=help_text, context_settings=STUB_SETTINGS)(_stub(path))
+
+
+def _register_stubs() -> None:
+    _stub_missing(app, "", TOP_LEVEL)
+
+    taken = _command_names(app)
+    for group, (help_text, subcommands) in GROUPS.items():
+        if group in taken:
+            # A partly ported group gets stubs for just its missing subcommands.
+            if (sub := _group(app, group)) is not None:
+                _stub_missing(sub, group, subcommands)
+            continue
+        if not subcommands:
+            _stub_missing(app, "", {group: help_text})
+            continue
+        sub = typer.Typer(help=help_text, no_args_is_help=True)
+        _stub_missing(sub, group, subcommands)
+        app.add_typer(sub, name=group)
+
+    labels = {kind: ("an" if label[0] in "aeiou" else "a", label) for kind, label in RESOURCE_KINDS.items()}
+    _stub_missing(add_app, "add", {k: f"Add {a} {label} to the project" for k, (a, label) in labels.items()})
+    _stub_missing(
+        remove_app,
+        "remove",
+        {k: f"Remove {a} {label} from the project" for k, (a, label) in labels.items()}
+        | {"all": "Remove all resources from the project"},
+    )
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False, "--version", "-V", callback=_version_callback, is_eager=True, help="Show version"
+    ),
+) -> None:
+    # Background update check, with its notice printed at exit (upstream checkForUpdate in cli.ts).
+    from agentcore.cli.notices import install_post_command_notices
+
+    install_post_command_notices()
+
+
+_register_commands()
+_register_primitives()
+for _name, _group_app in created_groups().items():
+    app.add_typer(_group_app, name=_name)
+app.add_typer(add_app, name="add")
+app.add_typer(remove_app, name="remove")
+_register_stubs()

agentcore/cli/naming.py

@@ -0,0 +1,11 @@
+"""Wizard naming helpers (port of src/cli/tui/utils/naming.ts)."""
+
+
+def generate_unique_name(base_name: str, existing_names: list[str], separator: str = "") -> str:
+    """Append a numeric suffix when needed: MyAgent -> MyAgent1 -> MyAgent2."""
+    if base_name not in existing_names:
+        return base_name
+    counter = 1
+    while f"{base_name}{separator}{counter}" in existing_names:
+        counter += 1
+    return f"{base_name}{separator}{counter}"

agentcore/cli/notices.py

@@ -0,0 +1,42 @@
+"""Post-command notices (port of src/cli/notices.ts).
+
+The telemetry notice is not ported (telemetry is out of scope for the Python port).
+"""
+
+from __future__ import annotations
+
+import atexit
+import os
+import sys
+
+from agentcore.cli.update_notifier import BackgroundUpdateCheck, print_update_notification, should_check_for_updates
+
+
+def print_post_command_notices(update_check: BackgroundUpdateCheck | None) -> None:
+    result = update_check.result() if update_check is not None else None
+    if result is not None and result.update_available:
+        print_update_notification(result)
+
+
+_installed = False
+
+
+def install_post_command_notices(argv: list[str] | None = None) -> BackgroundUpdateCheck | None:
+    """Start the background update check now and print its notice when the process exits.
+
+    Only for a real ``agentcore`` invocation (the console script), never on import from tests or
+    other programs, and never when ``AGENTCORE_DISABLE_UPDATE_CHECK`` is set.
+    """
+    global _installed
+    argv = list(sys.argv if argv is None else argv)
+    if _installed or not argv or os.path.basename(argv[0]) not in ("agentcore", "agentcore.exe"):
+        return None
+    if not should_check_for_updates(argv):
+        return None
+    _installed = True
+    check = BackgroundUpdateCheck().start()
+    atexit.register(print_post_command_notices, check)
+    return check
+
+
+__all__ = ["install_post_command_notices", "print_post_command_notices"]

agentcore/cli/project.py

@@ -0,0 +1,34 @@
+"""Default project spec (port of ``src/cli/project.ts``)."""
+
+from typing import Any
+
+from agentcore.cli.constants import SCHEMA_VERSION
+from agentcore.lib import get_schema_url_for_version
+
+
+def create_default_project_spec(project_name: str) -> dict[str, Any]:
+    """Create a default AgentCore project spec (camelCase JSON dict) with standard defaults."""
+    return {
+        "$schema": get_schema_url_for_version(SCHEMA_VERSION),
+        "name": project_name,
+        "version": SCHEMA_VERSION,
+        "managedBy": "CDK",
+        "runtimes": [],
+        "memories": [],
+        "knowledgeBases": [],
+        "credentials": [],
+        "evaluators": [],
+        "onlineEvalConfigs": [],
+        "agentCoreGateways": [],
+        "policyEngines": [],
+        "harnesses": [],
+        "configBundles": [],
+        "abTests": [],
+        "datasets": [],
+        "payments": [],
+        "capacityProviders": [],
+        "tags": {
+            "agentcore:created-by": "agentcore-cli",
+            "agentcore:project-name": project_name,
+        },
+    }

agentcore/cli/run_command.py

@@ -0,0 +1,27 @@
+"""Port of ``runCliCommand`` (src/cli/telemetry/cli-command-run.ts) without telemetry.
+
+Runs a non-interactive command body; on any exception prints ``{"success":false,"error":...}``
+(with ``--json``) or the message on stderr, and exits 1. Exits 0 on success.
+"""
+
+import json
+from collections.abc import Callable
+from typing import Any
+
+import typer
+
+from agentcore.cli.errors import get_error_message
+
+
+def run_cli_command(as_json: bool, fn: Callable[[], Any]) -> None:
+    try:
+        fn()
+    except typer.Exit:
+        raise
+    except Exception as exc:  # noqa: BLE001 - top-level command boundary, as upstream
+        if as_json:
+            typer.echo(json.dumps({"success": False, "error": get_error_message(exc)}, separators=(",", ":")))
+        else:
+            typer.echo(get_error_message(exc), err=True)
+        raise typer.Exit(1) from None
+    raise typer.Exit(0)

agentcore/cli/tree.py

@@ -0,0 +1,135 @@
+"""Declarative map of the upstream command tree (src/cli/commands, src/cli/primitives).
+
+Commands not yet ported are registered from this table as stubs so `--help` shows the full
+surface. When a command is ported, register it in its own module under `cli/commands/`
+and drop it from here.
+"""
+
+# Mirrors COMMAND_DESCRIPTIONS in src/cli/constants.ts.
+PROGRAM_DESCRIPTION = "Build and deploy Agentic AI applications on AgentCore"
+
+TOP_LEVEL: dict[str, str] = {
+    "create": "Create a new AgentCore project",
+    "dev": "Launch local dev server, or invoke an agent locally.",
+    "deploy": "Deploy project infrastructure to AWS via CDK.",
+    "exec": "Open an interactive shell or run a one-shot command in a deployed agent container.",
+    "invoke": "Invoke a deployed agent endpoint.",
+    "package": "Package agent artifacts without deploying.",
+    "status": "Show deployed resource details and status.",
+    "feedback": "Send feedback about the AgentCore CLI to the team.",
+    "view": "View A/B test or insights jobs.",
+}
+
+GROUPS: dict[str, tuple[str, dict[str, str]]] = {
+    "archive": (
+        "Archive (delete) a batch evaluation or recommendation on the service and clear local history.",
+        {
+            "batch-evaluation": "Archive a batch evaluation.",
+            "recommendation": "Archive a recommendation.",
+            "ab-test": "Delete an A/B test on the service and clear local history.",
+            "insights": "Delete an insights job on the service and clear local history.",
+        },
+    ),
+    "batch-evaluations": ("View batch evaluation history.", {"history": "View past batch evaluation runs."}),
+    "capacity-provider": (
+        "Manage capacity provider sessions.",
+        {"delete-session": "Delete a capacity provider session."},
+    ),
+    "config-bundle": (
+        "Manage configuration bundle versions and diffs.",
+        {
+            "versions": "List version history for a bundle.",
+            "diff": "Diff two versions of a bundle.",
+            "create-branch": "Create a new branch on an existing bundle.",
+        },
+    ),
+    "dataset": (
+        "Manage dataset versions.",
+        {
+            "download": "Download a dataset version locally.",
+            "publish-version": "Publish a new dataset version.",
+            "remove-version": "Remove a dataset version.",
+        },
+    ),
+    "evals": ("View saved eval and batch eval results from past runs.", {"history": "View past eval runs."}),
+    "export": ("Export a harness to a Strands runtime agent.", {"harness": "Export a harness config to app/."}),
+    "fetch": ("Fetch access info for deployed resources.", {"access": "Fetch access info for a deployed resource."}),
+    "help": ("Show help topics.", {"modes": "Explain interactive vs non-interactive modes."}),
+    "import": (
+        "Import a runtime, memory, or starter toolkit into this project. [experimental]",
+        {
+            "runtime": "Import an existing runtime.",
+            "memory": "Import an existing memory.",
+            "gateway": "Import an existing gateway.",
+            "evaluator": "Import an existing evaluator.",
+            "online-eval": "Import an existing online eval config.",
+        },
+    ),
+    "logs": ("Stream or search agent runtime logs.", {"evals": "Stream or search online eval logs."}),
+    "pause": (
+        "Pause a deployed resource (online eval config, A/B test).",
+        {
+            "online-eval": "Pause a deployed online eval config.",
+            "ab-test": "Pause traffic splitting for a running A/B test.",
+            "online-insights": "Pause a deployed online insights config.",
+        },
+    ),
+    "promote": ("Promote a winning variant.", {"ab-test": "Apply the winning A/B variant to agentcore.json."}),
+    "recommendations": (
+        "View recommendation history from past runs.",
+        {"history": "View past recommendation runs."},
+    ),
+    "resume": (
+        "Resume a paused resource (online eval config, A/B test).",
+        {
+            "online-eval": "Resume a paused online eval config.",
+            "ab-test": "Resume a paused A/B test.",
+            "online-insights": "Resume a paused online insights config.",
+        },
+    ),
+    "run": (
+        "Run evaluations, batch evaluations, or optimization recommendations.",
+        {
+            "eval": "Run on-demand evaluation against agent traces.",
+            "batch-evaluation": "Run evaluators across all sessions.",
+            "insights": "Run on-demand failure analysis across recent sessions.",
+            "recommendation": "Optimize prompts and tool descriptions.",
+            "ingest": "Ingest knowledge base data sources.",
+            "ab-test": "Start an A/B test on a gateway.",
+        },
+    ),
+    "stop": (
+        "Stop a running batch evaluation or A/B test.",
+        {"ab-test": "Stop a running A/B test.", "batch-evaluation": "Stop a running batch evaluation."},
+    ),
+    "traces": (
+        "View and download agent traces.",
+        {"list": "List recent traces for a deployed agent.", "get": "Download a trace to a JSON file."},
+    ),
+    "update": ("Check for and install CLI updates", {"cli": "Update the CLI."}),
+}
+
+# Resource kinds registered by src/cli/primitives/registry.ts (ALL_PRIMITIVES), plus the
+# standalone `add/remove tool|skill` commands.
+RESOURCE_KINDS: dict[str, str] = {
+    "agent": "agent",
+    "harness": "harness",
+    "memory": "memory",
+    "dataset": "dataset",
+    "credential": "credential",
+    "evaluator": "evaluator",
+    "online-eval": "online eval config",
+    "online-insights": "online insights config",
+    "gateway": "gateway",
+    "gateway-target": "gateway target",
+    "knowledge-base": "knowledge base",
+    "policy-engine": "policy engine",
+    "policy": "policy",
+    "config-bundle": "config bundle",
+    "runtime-endpoint": "runtime endpoint",
+    "payment-manager": "payment manager",
+    "payment-connector": "payment connector",
+    "capacity-provider": "capacity provider",
+    "tool": "harness tool",
+    "skill": "harness skill",
+}

agentcore/cli/update_notifier.py

@@ -0,0 +1,123 @@
+"""Background update check (port of src/cli/update-notifier.ts).
+
+Deliberate deviation: this port is distributed on PyPI as ``agentcore-cli``, so the latest version
+comes from ``https://pypi.org/pypi/agentcore-cli/json`` and the suggested install command is
+pip / pipx / uv tool depending on how the CLI was installed. The cache file and its one-day check
+interval match upstream. Set ``AGENTCORE_DISABLE_UPDATE_CHECK=1`` to skip the background check.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import threading
+import time
+from dataclasses import dataclass
+
+from agentcore import __version__
+from agentcore.lib.time_constants import ONE_DAY_MS
+
+CHECK_INTERVAL_MS = ONE_DAY_MS
+CACHE_FILE = "update-check.json"
+DISABLE_ENV = "AGENTCORE_DISABLE_UPDATE_CHECK"
+
+
+def get_config_dir() -> str:
+    return os.environ.get("AGENTCORE_CONFIG_DIR") or os.path.join(os.path.expanduser("~"), ".agentcore")
+
+
+@dataclass
+class UpdateCheckResult:
+    update_available: bool
+    latest_version: str
+
+
+def _read_cache() -> dict | None:
+    try:
+        with open(os.path.join(get_config_dir(), CACHE_FILE), encoding="utf-8") as fh:
+            data = json.load(fh)
+        return data if isinstance(data, dict) else None
+    except (OSError, ValueError):
+        return None
+
+
+def _write_cache(data: dict) -> None:
+    try:
+        directory = get_config_dir()
+        os.makedirs(directory, exist_ok=True)
+        with open(os.path.join(directory, CACHE_FILE), "w", encoding="utf-8") as fh:
+            fh.write(json.dumps(data, separators=(",", ":")))
+    except OSError:
+        pass  # silently ignore cache write failures
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def check_for_update() -> UpdateCheckResult | None:
+    """Cached for a day; ``None`` on any failure."""
+    from agentcore.cli.commands.update.action import compare_versions, fetch_latest_version
+
+    try:
+        cache = _read_cache()
+        now = _now_ms()
+        if cache and isinstance(cache.get("lastCheck"), (int, float)) and now - cache["lastCheck"] < CHECK_INTERVAL_MS:
+            latest = str(cache["latestVersion"])
+            return UpdateCheckResult(compare_versions(__version__, latest) > 0, latest)
+        latest = fetch_latest_version()
+        _write_cache({"lastCheck": now, "latestVersion": latest})
+        return UpdateCheckResult(compare_versions(__version__, latest) > 0, latest)
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def print_update_notification(result: UpdateCheckResult) -> None:
+    from agentcore.cli.commands.update.action import get_install_command_display
+    from agentcore.cli.constants import ANSI
+
+    yellow, cyan, reset = ANSI.yellow, ANSI.cyan, ANSI.reset
+    sys.stderr.write(
+        f"\n{yellow}Update available:{reset} {__version__} → {cyan}{result.latest_version}{reset}\n"
+        f"Run {cyan}`{get_install_command_display()}`{reset} to update.\n"
+    )
+
+
+class BackgroundUpdateCheck:
+    """Non-blocking ``checkForUpdate()`` promise: started before the command, awaited after it."""
+
+    def __init__(self) -> None:
+        self._result: UpdateCheckResult | None = None
+        self._thread = threading.Thread(target=self._run, name="agentcore-update-check", daemon=True)
+
+    def _run(self) -> None:
+        self._result = check_for_update()
+
+    def start(self) -> BackgroundUpdateCheck:
+        self._thread.start()
+        return self
+
+    def result(self, timeout: float | None = 5.0) -> UpdateCheckResult | None:
+        self._thread.join(timeout)
+        return None if self._thread.is_alive() else self._result
+
+
+def should_check_for_updates(argv: list[str]) -> bool:
+    """Upstream skips the check for `update` itself; --help/--version exit before notices print."""
+    if os.environ.get(DISABLE_ENV):
+        return False
+    args = argv[1:]
+    if args and args[0] == "update":
+        return False
+    return not any(a in ("-h", "--help", "-V", "--version") for a in args)
+
+
+__all__ = [
+    "CHECK_INTERVAL_MS",
+    "BackgroundUpdateCheck",
+    "UpdateCheckResult",
+    "check_for_update",
+    "print_update_notification",
+    "should_check_for_updates",
+]

agentcore/cli/variadic.py

@@ -0,0 +1,50 @@
+"""Commander-style variadic options (``-e a b c``) for Typer commands.
+
+Commander's ``.option('-e, --evaluator <names...>')`` consumes every following argument up to the
+next option-looking token. Click only supports repeating the flag (``-e a -e b``). ``variadic(...)``
+returns a command class that rewrites ``-e a b c`` into ``-e a -e b -e c`` before Click parses, so
+both spellings work.
+"""
+
+from collections.abc import Iterable
+
+from typer.core import TyperCommand
+
+
+def expand_variadic(args: list[str], flags: frozenset[str]) -> list[str]:
+    out: list[str] = []
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            out.extend(args[i:])
+            break
+        if arg in flags:
+            i += 1
+            values = []
+            while i < len(args) and not (args[i].startswith("-") and len(args[i]) > 1):
+                values.append(args[i])
+                i += 1
+            if not values:
+                out.append(arg)  # let Click report the missing value
+            for value in values:
+                out += [arg, value]
+            continue
+        out.append(arg)
+        i += 1
+    return out
+
+
+def variadic(*flags: str) -> type[TyperCommand]:
+    """A TyperCommand subclass treating ``flags`` as variadic options."""
+    flag_set = frozenset(flags)
+
+    class VariadicCommand(TyperCommand):
+        def parse_args(self, ctx, args: list[str]):  # type: ignore[no-untyped-def]
+            return super().parse_args(ctx, expand_variadic(list(args), flag_set))
+
+    return VariadicCommand
+
+
+def flags_of(*groups: Iterable[str]) -> tuple[str, ...]:
+    return tuple(f for g in groups for f in g)