sima-cli 2.1.12__tar.gz → 2.1.13__tar.gz

{sima_cli-2.1.12/sima_cli.egg-info → sima_cli-2.1.13}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sima-cli
-Version: 2.1.12
+Version: 2.1.13
 Summary: CLI tool for SiMa Developer Portal to download models, firmware, and apps.
 Home-page: https://community.sima.ai/
 Author: SiMa.ai

{sima_cli-2.1.12 → sima_cli-2.1.13}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sima-cli"
-version = "2.1.12"
+version = "2.1.13"
 description = "CLI tool for SiMa Developer Portal to download models, firmware, and apps."
 readme = "README.md"
 requires-python = ">=3.8"

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/__version__.py

@@ -1,2 +1,2 @@
 # sima_cli/__version__.py
-__version__ = "2.1.12"
+__version__ = "2.1.13"

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/sdk/cmdexec.py

@@ -18,10 +18,15 @@ from sima_cli.sdk.utils import (
 
 console = Console()
 
+
+class SdkContainerUnavailable(RuntimeError):
+    """Raised when no running SDK container matches a requested tool."""
+
+
 # ─────────────────────────────────────────────
 # Core executer
 # ─────────────────────────────────────────────
-def exec_container_cmd(ctx, keyword: str, cmd: Optional[str] = None):
+def exec_container_cmd(ctx, keyword: str, cmd: Optional[str] = None, raise_on_missing: bool = False):
     """
     Find a running container matching the given SDK keyword (e.g. mpk, yocto),
     optionally filtering by version (from ctx.obj['version_filter']),
@@ -34,6 +39,8 @@ def exec_container_cmd(ctx, keyword: str, cmd: Optional[str] = None):
     containers = get_all_containers(running_containers_only=True)
     if not containers:
         console.print("[yellow]⚠️  No running containers found.[/yellow]")
+        if raise_on_missing:
+            raise SdkContainerUnavailable("No running containers found.")
         sys.exit(0)
 
     # ──────────────────────────────────────────────
@@ -61,11 +68,16 @@ def exec_container_cmd(ctx, keyword: str, cmd: Optional[str] = None):
         )
 
     if not matches:
-        console.print(
-            f"[red]❌ No running containers found for '{keyword}'"
+        message = (
+            f"No running containers found for '{keyword}'"
             + (f" with version '{version_filter}'" if version_filter else "")
-            + ".[/red]"
+            + "."
+        )
+        console.print(
+            f"[red]❌ {message}[/red]"
         )
+        if raise_on_missing:
+            raise SdkContainerUnavailable(message)
         sys.exit(1)
 
     # ──────────────────────────────────────────────

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/sdk/commands.py

@@ -24,10 +24,10 @@ from typing import Optional
 from rich.console import Console
 from rich.panel import Panel
 from sima_cli.sdk.install import setup_and_start
-from sima_cli.sdk.cmdexec import exec_container_cmd
+from sima_cli.sdk.cmdexec import SdkContainerUnavailable, exec_container_cmd
 from sima_cli.sdk.uninstall import remove_containers, remove_unused_images
 from sima_cli.sdk.stop import stop_containers
-from sima_cli.sdk.utils import get_all_containers
+from sima_cli.sdk.utils import get_all_containers, container_matches_sdk_keyword
 from sima_cli.sdk.utils import extract_short_name
 from sima_cli.discover.discover import discover_and_probe
 from rich.table import Table
@@ -38,6 +38,7 @@ from sima_cli.sdk.config import IMAGE_CONFIG
 from sima_cli.sdk.network_doctor import (
     build_network_doctor_report,
     collect_network_doctor_bundle,
+    ensure_existing_neat_container_startable,
     print_network_doctor_report,
     repair_linux_devkit_network,
 )
@@ -156,7 +157,66 @@ def _resolve_devkit_ipv4(devkit: Optional[str]) -> str:
     return value
 
 
-def launch_sdk_tool(tool: str, cmd, ctx):
+def _container_name(container) -> str:
+    return container.get("Names") or container.get("Name") or container.get("name") or ""
+
+
+def _container_is_running(container) -> bool:
+    state = (container.get("State") or "").lower().strip()
+    status = (container.get("Status") or "").lower().strip()
+    return state == "running" or status.startswith("up") or "running" in status
+
+
+def _version_matches(container, version_filter: str) -> bool:
+    if not version_filter:
+        return True
+    needle = version_filter.lower()
+    name = _container_name(container).lower()
+    image = (container.get("Image") or container.get("image") or "").lower()
+    return needle in name or needle in image
+
+
+def _start_stopped_neat_containers(ctx) -> None:
+    version_filter = None
+    if ctx and getattr(ctx, "obj", None):
+        version_filter = ctx.obj.get("version_filter")
+
+    containers = get_all_containers(running_containers_only=False)
+    matches = [
+        container
+        for container in containers
+        if container_matches_sdk_keyword(container, "neat")
+        and _version_matches(container, version_filter)
+        and not _container_is_running(container)
+    ]
+
+    if not matches:
+        message = "No stopped Neat SDK containers found."
+        if version_filter:
+            message = f"No stopped Neat SDK containers found for version '{version_filter}'."
+        raise click.ClickException(f"{message} Run: sima-cli sdk setup")
+
+    for container in matches:
+        name = _container_name(container)
+        if not name:
+            continue
+        try:
+            ensure_existing_neat_container_startable(name)
+            console.print(
+                f"[cyan]▶ Starting existing Neat SDK container:[/cyan] [bold]{name}[/bold] "
+                "[dim](this may take a moment)[/dim]"
+            )
+            subprocess.run(["docker", "start", name], check=True, capture_output=True, text=True)
+        except subprocess.CalledProcessError as e:
+            raise click.ClickException(
+                f"Failed to start Neat SDK container '{name}' while running: {' '.join(e.cmd)}"
+            ) from e
+        except RuntimeError as e:
+            raise click.ClickException(str(e)) from e
+        console.print(f"[green]✅ Started Neat SDK container:[/green] [bold]{name}[/bold]")
+
+
+def launch_sdk_tool(tool: str, cmd, ctx, recover_unavailable: bool = False):
     """
     Launch a selected SDK tool container, optionally executing a command inside it.
     If no command is provided, defaults to an interactive bash login shell.
@@ -182,7 +242,17 @@ def launch_sdk_tool(tool: str, cmd, ctx):
     else:
         cmd_str = str(cmd)
 
-    exec_container_cmd(ctx, tool, cmd_str)
+    if not recover_unavailable:
+        exec_container_cmd(ctx, tool, cmd_str)
+        return
+
+    try:
+        exec_container_cmd(ctx, tool, cmd_str, raise_on_missing=True)
+    except SdkContainerUnavailable:
+        if tool != "neat":
+            raise
+        _start_stopped_neat_containers(ctx)
+        exec_container_cmd(ctx, tool, cmd_str)
 
 
 # ------------------------------------------------------------
@@ -554,13 +624,16 @@ def neat(ctx, cmd):
     running container with bash -lc. If CMD is omitted, sima-cli opens an
     interactive login shell.
 
+    If no matching Neat SDK container is running, existing stopped Neat SDK
+    container(s) are started automatically and the command is retried.
+
     \b
     Examples:
         sima-cli sdk neat
         sima-cli sdk neat python --version
         sima-cli sdk neat "python app.py --config config.json"
     """
-    launch_sdk_tool("neat", cmd, ctx)
+    launch_sdk_tool("neat", cmd, ctx, recover_unavailable=True)
 
 
 @sdk.command(

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/sdk/install.py

@@ -1148,6 +1148,16 @@ def setup_and_start(
                 configure_container_user(existing_container, login_name, user_uid, user_gid)
 
             if devkit_env and is_neat_sdk_image(img):
+                if not skip_insight:
+                    # Re-issue the mounted HTTPS cert for the (possibly new) host
+                    # IP before bootstrap restarts neat-insight, so the browser
+                    # doesn't hit a SAN mismatch ("connection is not private")
+                    # after a re-point.
+                    from sima_cli.sdk.neat import refresh_neat_certificates
+                    refresh_neat_certificates(
+                        workspace, existing_container, devkit_env,
+                        yes_to_all=yes_to_all, noninteractive=noninteractive,
+                    )
                 bootstrap_devkit_container(existing_container, devkit_env)
 
             if len(selected_images) == 1:

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/sdk/neat.py

@@ -256,6 +256,28 @@ def _collect_physical_ipv4s_for_certs() -> List[str]:
     return hosts
 
 
+def _collect_all_ipv4s_for_certs() -> List[str]:
+    """Every usable IPv4 on the host, INCLUDING VPN/tunnel interfaces.
+
+    Unlike the advertised-URL selection (which deliberately prefers a physical
+    interface), a certificate SAN should be inclusive: list every address the
+    browser might connect to so HTTPS is trusted whether or not a VPN is up.
+    Without this, a cert minted while a VPN was connected covers only the VPN IP
+    (and vice versa), so toggling the VPN flips between "secure" and "not secure".
+    """
+    hosts = []
+    try:
+        import psutil
+    except Exception:
+        return hosts
+
+    for _iface, addrs in psutil.net_if_addrs().items():
+        for addr in addrs:
+            if addr.family == socket.AF_INET and _is_usable_ipv4(addr.address):
+                hosts.append(addr.address)
+    return hosts
+
+
 def _collect_cert_hosts(devkit_env: Optional[dict]) -> List[str]:
     hosts = ["localhost", "127.0.0.1"]
     if devkit_env and devkit_env.get("host_ip"):
@@ -268,6 +290,8 @@ def _collect_cert_hosts(devkit_env: Optional[dict]) -> List[str]:
     except Exception:
         pass
     hosts.extend(_collect_physical_ipv4s_for_certs())
+    # Include VPN/tunnel IPv4s too so the cert stays valid across VPN on/off.
+    hosts.extend(_collect_all_ipv4s_for_certs())
 
     seen = set()
     return [host for host in hosts if host and not (host in seen or seen.add(host))]
@@ -474,6 +498,110 @@ def _ensure_certificates(cert_dir: Path, devkit_env: Optional[dict], yes_to_all:
     return cert_file, key_file
 
 
+def _cert_covers_host(cert_file: Path, host_ip: str) -> bool:
+    """Return True if the cert's SAN already lists ``host_ip`` as an IP address.
+
+    Used to avoid needlessly re-issuing (and disrupting) the certificate on a
+    re-point when the host IP hasn't changed. On any failure to verify (no
+    openssl, parse error) returns False so the caller re-issues to be safe.
+    """
+    if not host_ip:
+        return False
+    try:
+        result = subprocess.run(
+            ["openssl", "x509", "-noout", "-ext", "subjectAltName", "-in", str(cert_file)],
+            capture_output=True, text=True, check=False,
+        )
+        text = result.stdout or ""
+        if result.returncode != 0 or "IP Address" not in text:
+            result = subprocess.run(
+                ["openssl", "x509", "-noout", "-text", "-in", str(cert_file)],
+                capture_output=True, text=True, check=False,
+            )
+            text = result.stdout or ""
+        # Parse the comma-separated "IP Address:<ip>" SAN entries and match
+        # exactly. A bare substring check would treat a routed IP that is a
+        # *prefix* of an existing entry as covered (e.g. 192.168.1.5 vs
+        # IP Address:192.168.1.50), wrongly skipping re-issue and leaving the
+        # browser with a SAN mismatch after that re-point.
+        san_ips = []
+        for token in text.replace("\n", ",").split(","):
+            token = token.strip()
+            if token.startswith("IP Address:"):
+                san_ips.append(token[len("IP Address:"):].strip())
+        return host_ip in san_ips
+    except OSError:
+        return False
+
+
+def _container_sdk_cert_dir(container_name: str) -> Optional[Path]:
+    """Return the host directory bind-mounted to ``/sdk-cert`` in the running
+    container, or ``None`` if it can't be determined.
+
+    The ``/sdk-cert`` mount is fixed at ``docker run`` time to the workspace used
+    *then*. We must re-issue into that exact directory, not one reconstructed
+    from the current invocation's workspace -- otherwise a user re-running setup
+    from a different workspace would write the new cert into an unmounted dir
+    while the container keeps serving the old mounted one.
+    """
+    try:
+        result = subprocess.run(
+            ["docker", "inspect", "-f",
+             '{{range .Mounts}}{{if eq .Destination "/sdk-cert"}}{{.Source}}{{end}}{{end}}',
+             container_name],
+            capture_output=True, text=True, check=False,
+        )
+    except OSError:
+        return None
+    if result.returncode != 0:
+        return None
+    source = (result.stdout or "").strip()
+    return Path(source) if source else None
+
+
+def refresh_neat_certificates(
+    workspace: str,
+    container_name: str,
+    devkit_env: Optional[dict],
+    *,
+    yes_to_all: bool = False,
+    noninteractive: bool = False,
+) -> bool:
+    """Re-issue the mounted ``/sdk-cert`` certificate to cover the current host IP.
+
+    On a DevKit re-point (or a host network change) the routed host IP changes,
+    but the HTTPS cert mounted into the Neat container was signed once at
+    container creation with the *old* IP in its SAN -- so the browser shows
+    "Your connection is not private" on the new IP. The host owns the trusted
+    mkcert CA, so the cert must be reissued *here* (not inside the container) to
+    stay trusted; neat-insight is restarted separately (devkit.sh's refresh hook)
+    to pick up the rewritten file from the bind-mounted cert dir.
+
+    (Re)generates when the cert is **missing** (e.g. the user deleted it) or its
+    SAN doesn't cover the current host IP. No-op (returns False) only when there
+    is no host IP, or a valid cert already covers it. Returns True when a cert was
+    generated.
+    """
+    host_ip = (devkit_env or {}).get("host_ip", "")
+    if not host_ip:
+        return False
+    # Use the directory actually bind-mounted to /sdk-cert in the container, so a
+    # re-issue lands where neat-insight reads it even if the current invocation's
+    # workspace differs from the one the container was created with. Fall back to
+    # the workspace-derived path (e.g. container not running / no mount).
+    cert_dir = _container_sdk_cert_dir(container_name) \
+        or (Path(workspace) / f".{container_name}" / "sdk-cert")
+    cert_file = cert_dir / "neat-sdk.pem"
+    if cert_file.exists() and _cert_covers_host(cert_file, host_ip):
+        return False
+    action = "Re-issuing" if cert_file.exists() else "Generating"
+    print(f"🔐 {action} Neat SDK certificate for host IP {host_ip} ...")
+    _ensure_certificates(
+        cert_dir, devkit_env, yes_to_all=yes_to_all, noninteractive=noninteractive
+    )
+    return True
+
+
 def _write_port_map(config_dir: Path, port_map: Dict) -> Path:
     config_dir.mkdir(parents=True, exist_ok=True)
     path = config_dir / "neat-port-map.json"

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/sdk/utils.py

@@ -873,6 +873,7 @@ def ensure_model_sdk_extension_installed(
             print("ℹ️  Skipping Model Compiler extension install.")
             return
 
+    internal_sima_cli_env = "export SIMA_CLI_AUTO_ACCEPT_UPDATE=1; "
     print("ℹ️  Logging in to sima-cli before installing the Model Compiler extension...")
     run_command(
         _docker_exec_interactive_prefix() + [
@@ -881,7 +882,7 @@ def ensure_model_sdk_extension_installed(
             sdk_container_name,
             "bash",
             "-lc",
-            "sima-cli login",
+            f"{internal_sima_cli_env}sima-cli login",
         ]
     )
 
@@ -892,6 +893,7 @@ def ensure_model_sdk_extension_installed(
         f"export HOME={shlex.quote(home_directory)}; "
         f"export USER={shlex.quote(login_name)}; "
         f"export LOGNAME={shlex.quote(login_name)}; "
+        f"{internal_sima_cli_env}"
         "export PATH=\"$HOME/.sima-cli/.venv/bin:$HOME/.local/bin:$PATH\"; "
         "mkdir -p \"$HOME/extension-installation\"; "
         "cd \"$HOME/extension-installation\"; "
@@ -1206,7 +1208,7 @@ def install_neat_playbooks(sdk_container_name: str, login_name: str) -> None:
             "-u",
             login_name,
             "-e",
-            "SIMA_CLI_CHECK_FOR_UPDATE=0",
+            "SIMA_CLI_AUTO_ACCEPT_UPDATE=1",
             "-e",
             "GITHUB_TOKEN",
             sdk_container_name,

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/utils/docker.py

@@ -9,8 +9,6 @@ import getpass
 
 from sima_cli.utils.env import get_environment_type
 
-# Sentinel to break out of an infinite re-exec loop if `sg docker -c …`
-# somehow lands back here without socket access.
 _REEXEC_ENV_FLAG = "SIMA_CLI_DOCKER_GROUP_REEXEC"
 
 
@@ -74,57 +72,92 @@ def _user_in_docker_group(user: str) -> bool:
     return user in members
 
 
-def _reexec_with_docker_group() -> None:
-    """Re-run the current sima-cli invocation under `sg docker -c …`.
+def _active_user_in_docker_group() -> bool:
+    """Check whether this running process has the docker group active."""
+    try:
+        import grp
+
+        group_ids = set(os.getgroups())
+        group_ids.add(os.getgid())
+        group_ids.add(os.getegid())
+        active_group_names = {
+            grp.getgrgid(group_id).gr_name
+            for group_id in group_ids
+        }
+    except (ImportError, KeyError, OSError):
+        return False
+    return "docker" in active_group_names
+
 
-    `sg <group> -c <cmd>` runs <cmd> with that supplementary group active for
-    the new process, which is what gives access to /var/run/docker.sock right
-    after `usermod -aG docker` — without forcing the user to open a new shell.
-    Sets a sentinel env var so a second pass through this code path cannot
-    loop forever. Returns only if re-exec is not possible (caller should fall
-    back to the manual-instruction path).
+def _try_reexec_with_docker_group() -> None:
+    """Best-effort re-run under `sg docker` when it is known to work.
+
+    Some systems allow `sg docker -c ...` to activate a newly-added docker
+    group immediately, while others reject it or prompt for group auth. Probe
+    first so failures can fall back to deterministic user instructions.
     """
     if os.environ.get(_REEXEC_ENV_FLAG) == "1":
-        return  # already retried under sg; don't loop
+        return
     if not shutil.which("sg"):
-        return  # `sg` (from util-linux) unavailable; fall back
+        return
+
+    probe_env = os.environ.copy()
+    probe_env[_REEXEC_ENV_FLAG] = "1"
+    try:
+        probe = subprocess.run(
+            ["sg", "docker", "-c", "docker info >/dev/null 2>&1"],
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            env=probe_env,
+            timeout=10,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return
+    if probe.returncode != 0:
+        return
 
-    new_env = os.environ.copy()
-    new_env[_REEXEC_ENV_FLAG] = "1"
     cmdline = shlex.join(sys.argv)
-    print("🔁 Activating 'docker' group for this command (no new shell needed)...")
+    print("🔁 Activating 'docker' group for this command...")
     try:
-        os.execvpe("sg", ["sg", "docker", "-c", cmdline], new_env)
-    except OSError as e:
-        print(f"⚠️  Could not re-exec under 'sg docker': {e}")
-        return  # caller falls back to manual instructions
+        os.execvpe("sg", ["sg", "docker", "-c", cmdline], probe_env)
+    except OSError:
+        return
+
+
+def _print_docker_group_refresh_instructions() -> None:
+    command = shlex.join(sys.argv)
+    print("ℹ️  Docker group membership is configured, but this shell session cannot use it yet.")
+    print("   Start a shell with the updated group membership, then re-run this command:")
+    print("   newgrp docker")
+    print(f"   {command}")
+    print("   If that still does not work, log out and back in before retrying.")
 
 
 def _handle_docker_socket_permission_denied() -> bool:
     """Linux: daemon is up but the current user can't access the socket.
 
-    Offers to add the user to the 'docker' group via sudo and then re-execs
-    the current command under `sg docker -c …` so it completes in the same
-    shell session. Falls back to printed manual instructions only when the
-    re-exec path is unavailable or has already been retried.
+    Offers to add the user to the 'docker' group via sudo when needed, then
+    exits with clear instructions because newly-added group membership is not
+    available to the current shell/process on many Linux systems.
     """
     user = _current_user()
     print("⚠️  Docker daemon is running, but this user lacks permission to access it.")
     print(f"   (Cannot access /var/run/docker.sock as '{user}'.)")
 
-    already_retried = os.environ.get(_REEXEC_ENV_FLAG) == "1"
-
     if _user_in_docker_group(user):
-        if already_retried:
-            print(f"ℹ️  User '{user}' is already a member of the 'docker' group, but even after")
-            print("   re-exec'ing under 'sg docker' the socket is still not accessible.")
-            print("   👉 Log out and back in, then re-run this command.")
+        if _active_user_in_docker_group():
+            print(f"ℹ️  User '{user}' already has the 'docker' group active in this session.")
+            print("   The socket is still not accessible, so this is likely a Docker daemon")
+            print("   or /var/run/docker.sock ownership issue rather than group activation.")
+            print("   Check:  ls -l /var/run/docker.sock")
+            print("   Check:  sudo systemctl status docker")
             sys.exit(1)
-        print(f"ℹ️  User '{user}' is already a member of the 'docker' group, but the current")
+        print(f"ℹ️  User '{user}' is already a member of the 'docker' group, but this")
         print("   shell session has not picked up that membership yet.")
-        _reexec_with_docker_group()
-        # Re-exec failed; fall through to manual instructions.
-        print("   👉 Run 'newgrp docker' in this shell (or log out and back in), then re-run this command.")
+        _try_reexec_with_docker_group()
+        _print_docker_group_refresh_instructions()
         sys.exit(1)
 
     print(f"ℹ️  User '{user}' is not a member of the 'docker' group.")
@@ -143,12 +176,8 @@ def _handle_docker_socket_permission_denied() -> bool:
         sys.exit(1)
 
     print(f"✅ Added '{user}' to the 'docker' group.")
-    _reexec_with_docker_group()
-    # If we get here, re-exec was not possible (no `sg`, already retried, or
-    # OSError) and the original install/setup operation did NOT complete.
-    # Exit non-zero so parent scripts / CI do not treat this as success.
-    print("ℹ️  Group membership only takes effect in NEW shell sessions.")
-    print("   👉 Run 'newgrp docker' in this shell (or log out and back in), then re-run this command.")
+    _try_reexec_with_docker_group()
+    _print_docker_group_refresh_instructions()
     sys.exit(1)
 
 

{sima_cli-2.1.12 → sima_cli-2.1.13}/sima_cli/vulcan/artifacts.py

@@ -54,6 +54,7 @@ class InstallMetadataResult:
     environment: str
     base_url: str
     repository: str
+    package_path: str
     ref: str
     ref_key: str
     requested_spec: str
@@ -190,22 +191,36 @@ def read_latest_tag(client: ArtifactClient, base_url: str, repository: str, key:
     return latest_tag
 
 
-def parse_install_target(target: str) -> Tuple[str, str, str]:
+def _parse_repository_and_package_path(raw: str) -> Tuple[str, str]:
+    value = raw.strip().strip("/")
+    if not value:
+        raise VulcanArtifactError("Install target repository is empty.")
+
+    parts = [part.strip() for part in value.split("/")]
+    if any(not part for part in parts):
+        raise VulcanArtifactError("Install target must not contain empty path segments.")
+    if any(part == ".." for part in parts):
+        raise VulcanArtifactError("Install target package path must not contain '..'.")
+
+    repository = parts[0]
+    package_path = "/".join(parts[1:])
+    return repository, package_path
+
+
+def parse_install_target(target: str) -> Tuple[str, str, str, str]:
     value = target.strip()
     if not value:
         raise VulcanArtifactError("Install target is empty.")
 
-    repository, separator, ref_spec = value.partition("@")
-    repository = repository.strip()
-    if not repository:
-        raise VulcanArtifactError("Install target repository is empty.")
+    repository_spec, separator, ref_spec = value.partition("@")
+    repository, package_path = _parse_repository_and_package_path(repository_spec)
 
     if not separator or not ref_spec.strip():
-        return repository, "main", "latest"
+        return repository, package_path, "main", "latest"
 
     ref_spec = ref_spec.strip().strip("/")
     if not ref_spec:
-        return repository, "main", "latest"
+        return repository, package_path, "main", "latest"
 
     if ":" in ref_spec:
         ref, spec = ref_spec.rsplit(":", 1)
@@ -215,12 +230,12 @@ def parse_install_target(target: str) -> Tuple[str, str, str]:
             raise VulcanArtifactError(
                 "Install target must use repo@branch:spec when specifying both branch and spec."
             )
-        return repository, ref, spec
+        return repository, package_path, ref, spec
 
     if ref_spec == "latest" or _looks_like_commit_spec(ref_spec):
-        return repository, "main", ref_spec
+        return repository, package_path, "main", ref_spec
 
-    return repository, ref_spec, "latest"
+    return repository, package_path, ref_spec, "latest"
 
 
 def _looks_like_commit_spec(value: str) -> bool:
@@ -250,17 +265,25 @@ def resolve_install_metadata_url(
 ) -> InstallMetadataResult:
     client = client or ArtifactClient()
     resolved_base_url = normalize_base_url(base_url or ENV_BASE_URLS[environment])
-    repository, ref_name, requested_spec = parse_install_target(target)
+    repository, package_path, ref_name, requested_spec = parse_install_target(target)
     key = ref_key(ref_name)
     if requested_spec == "latest":
         resolved_spec = read_latest_tag(client, resolved_base_url, repository, key)
     else:
         resolved_spec = requested_spec
-    metadata_url = join_url(resolved_base_url, repository, key, resolved_spec, metadata_filename(package_type))
+    metadata_url = join_url(
+        resolved_base_url,
+        repository,
+        key,
+        resolved_spec,
+        package_path,
+        metadata_filename(package_type),
+    )
     return InstallMetadataResult(
         environment=environment,
         base_url=resolved_base_url,
         repository=repository,
+        package_path=package_path,
         ref=ref_name,
         ref_key=key,
         requested_spec=requested_spec,