videosdkagent-cli 0.0.1__py2.py3-none-any.whl → 0.0.5__py2.py3-none-any.whl

videosdk_cli/build.py

@@ -1,49 +1,147 @@
-from email.policy import default
 import click
 import sys
 import subprocess
 import os
 import asyncio
 from pathlib import Path
-from rich.prompt import Prompt
-from rich.console import Console
-from InquirerPy import inquirer
-from videosdk_cli.secret_set import secret_set
-from videosdk_cli.utils.project_config import get_config_option
 from docker_image.reference import Reference
+from videosdk_cli.utils.project_config import get_config_option
 from videosdk_cli.utils.apis.deployment_client import DeploymentClient
 from videosdk_cli.utils.ui.progress_runner import run_with_progress
-from videosdk_cli.utils.manager.agent_manager import init_agent, list_agents_manager,describe_agent_manager,image_pull_secret_manager
-console = Console()
+from videosdk_cli.utils.ui.theme import (
+    console,
+    print_header,
+    print_success,
+    print_error,
+    print_warning,
+    print_info,
+    print_key_value,
+    print_divider,
+)
+from videosdk_cli.utils.manager.agent_manager import (
+    init_agent,
+    list_versions_manager,
+    list_sessions_manager,
+    describe_version_manager,
+    image_pull_secret_manager,
+    secret_set_manager,
+    list_secret_manager,
+    remove_secret_set,
+    describe_secret_set,
+    add_secret_set,
+    remove_secret_set_key,
+    version_logs_manager,
+)
+
 
+# =============================================================================
+# MAIN AGENT GROUP
+# =============================================================================
 @click.group()
 def agent_cli():
-    """Build a Docker image from a Dockerfile and push it to a registry."""
+    """
+    Manage VideoSDK AI Agents.
+
+    Build, deploy, and manage your AI agents with VideoSDK cloud infrastructure.
+
+    \b
+    Quick Start:
+      $ videosdk agent init --name my-agent
+      $ videosdk agent build --image myrepo/myagent:v1
+      $ videosdk agent push --image myrepo/myagent:v1
+      $ videosdk agent deploy --image myrepo/myagent:v1
+    """
     pass
 
+
+# =============================================================================
+# AGENT INIT
+# =============================================================================
 @agent_cli.command(name="init")
-@click.option("--name", "-n", default=None, help='Name of the agent')
-def init(name):
-    console.print("[bold blue]Initializing Agent...[/bold blue]")
+@click.option(
+    "--name",
+    "-n",
+    default=None,
+    help="Name for your deployment (auto-generated if not provided)",
+)
+@click.option(
+    "--template",
+    "-t",
+    default=None,
+    help="Template ID to use (e.g., Template01)",
+)
+def init(name, template):
+    """
+    Initialize a new agent deployment.
+
+    Creates a new agent and deployment in VideoSDK cloud and generates a
+    videosdk.yaml configuration file with the agent ID and deployment ID.
+
+    \b
+    Examples:
+      $ videosdk agent init --name my-assistant --template Template01
+      $ videosdk agent init -n my-bot -t Template01
+      $ videosdk agent init  # auto-generates name
+    """
+    print_header("Initializing Deployment")
     try:
-        asyncio.run(run_with_progress(
-            init_agent(Path(os.getcwd()), name),
-            console=console,
-            title="Initializing Agent",
-            duration=5.0,
-        ))
-        console.print(f"[bold green]Agent initialized successfully.[/bold green]")
+        asyncio.run(
+            run_with_progress(
+                init_agent(Path(os.getcwd()), name=name, template=template),
+                console=console,
+                title="Initializing Deployment",
+                duration=5.0,
+            )
+        )
+        print_success("Deployment initialized successfully")
+        print_info("Next step: Build your agent Docker image")
+        console.print(
+            "  [bold]videosdk agent build --image <your-docker-username>/<image-name>:<tag>[/bold]"
+        )
     except Exception as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
+        print_error(f"Error: {e}")
         sys.exit(1)
 
 
+# =============================================================================
+# AGENT BUILD
+# =============================================================================
 @agent_cli.command(name="build")
-@click.option('--tag','-t', default=None, help='Name and optionally a tag in the \'name:tag\' format.')
-@click.option('--file','-f', 'dockerfile',default=None, help='Name of the Dockerfile')
-def build(tag, dockerfile):
-    """Build a Docker image from a Dockerfile."""
-    platform = 'linux/arm64'
+@click.option(
+    "--image",
+    "-i",
+    default=None,
+    help="Image name with optional tag (e.g., myrepo/myagent:v1)",
+)
+@click.option(
+    "--file",
+    "-f",
+    "dockerfile",
+    default=None,
+    help="Path to Dockerfile (default: ./Dockerfile)",
+)
+@click.option(
+    "--enable-logs",
+    is_flag=True,
+    default=False,
+    help="Upload build logs to VideoSDK cloud",
+)
+def build(image, dockerfile, enable_logs):
+    """
+    Build a Docker image for your agent.
+
+    Builds a Docker image using the specified Dockerfile. The image tag
+    can be provided via --image flag or read from videosdk.yaml.
+
+    \b
+    Examples:
+      $ videosdk agent build --image myrepo/myagent:v1
+      $ videosdk agent build --image myrepo/myagent:v1 --file Dockerfile.prod
+      $ videosdk agent build --enable-logs  # upload build logs to cloud
+      $ videosdk agent build  # uses image from videosdk.yaml
+    """
+    platform = "linux/arm64"
+
     # Determine Dockerfile path
     if dockerfile:
         dockerfile_path = Path(os.getcwd()) / dockerfile
@@ -52,379 +150,1381 @@ def build(tag, dockerfile):
         dockerfile = "Dockerfile"
 
     if not dockerfile_path.exists():
-        console.print(f"[bold red]Error:[/bold red] Dockerfile not found at {dockerfile_path}")
+        print_error(f"Dockerfile not found at {dockerfile_path}")
         sys.exit(1)
 
-    # Resolve tag
-    tag = get_config_option(
-        tag, 
-        ['agent', 'image'], 
-        required=True, 
-        fail_message="--tag not provided and 'agent.image' not found in videosdk.yaml"
+    # Resolve image tag: CLI > build.image > agent.image (legacy)
+    image = get_config_option(
+        image,
+        ["build", "image"],
+        required=False,
     )
-    tag = tag.lower()
+    if image is None:
+        image = get_config_option(
+            None,
+            ["agent", "image"],
+            required=True,
+            fail_message="--image not provided and 'build.image' or 'agent.image' not found in videosdk.yaml",
+        )
+    image = image.lower()
+
+    # If logs enabled, get deployment_id and presigned URL
+    presigned_url = None
+    build_id = None
+    deployment_id = None
+
+    if enable_logs:
+        deployment_id = get_config_option(
+            None,
+            ["deploy", "id"],
+            required=True,
+            fail_message="--enable-logs requires 'deploy.id' in videosdk.yaml. Run 'videosdk agent init' first.",
+        )
+
+        # Extract tag from image (e.g., "myrepo/myagent:v1" -> "v1")
+        if ":" in image:
+            image_tag = image.split(":")[-1]
+        else:
+            image_tag = "latest"
+
+        print_info("Getting presigned URL for build logs...")
+        try:
+            client = DeploymentClient()
+            response = asyncio.run(
+                client.get_build_log_presigned_url(
+                    deployment_id=deployment_id,
+                    tag=image_tag,
+                )
+            )
+            presigned_url = response.get("presignedUrl")
+            build_id = response.get("buildId")
+            print_success(f"Build ID: {build_id}")
+        except Exception as e:
+            print_warning(f"Failed to get presigned URL: {e}")
+            print_warning("Build will continue without log upload")
+            enable_logs = False
 
-    console.print(f"[bold blue]Building Docker image...[/bold blue]")
-    console.print(f"Platform: [green]{platform}[/green]")
-    console.print(f"Tag: [green]{tag}[/green]")
-    console.print(f"Dockerfile: [green]{dockerfile_path}[/green]")
+    print_header("Building Docker Image")
+    print_key_value("Platform", platform)
+    print_key_value("Image", image)
+    print_key_value("Dockerfile", str(dockerfile_path))
+    if enable_logs:
+        print_key_value("Log Upload", "Enabled")
+        print_key_value("Build ID", build_id)
+    print_divider()
 
     cmd = [
-        "docker", "build",
-        "--platform", platform,
-        "-t", tag,
-        "-f", str(dockerfile),
-        "."
+        "docker",
+        "build",
+        "--platform",
+        platform,
+        "-t",
+        image,
+        "-f",
+        str(dockerfile),
+        ".",
     ]
 
+    build_success = False
+    build_output = ""
+
     try:
-        subprocess.run(cmd, check=True)
-        console.print(f"[bold green]Successfully built image: {tag}[/bold green]")
+        if enable_logs:
+            # Run with captured output (still shows to user via PIPE + real-time read)
+            process = subprocess.Popen(
+                cmd,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.STDOUT,
+                text=True,
+                bufsize=1,
+            )
+
+            output_lines = []
+            for line in process.stdout:
+                console.print(line, end="")
+                output_lines.append(line)
+
+            process.wait()
+            build_output = "".join(output_lines)
+
+            if process.returncode != 0:
+                raise subprocess.CalledProcessError(process.returncode, cmd)
+        else:
+            # Run without capturing (direct output to terminal)
+            subprocess.run(cmd, check=True)
+
+        build_success = True
+        console.print()
+        print_success(f"Successfully built image: {image}")
+        print_info(f"Next step: Push your image to registry")
+        console.print(f"  [bold]videosdk agent push --image {image}[/bold]")
+
     except subprocess.CalledProcessError as e:
-        console.print(f"[bold red]Failed to build image.[/bold red]")
-        sys.exit(e.returncode)
+        print_error("Failed to build image")
+        build_success = False
+        if not enable_logs:
+            sys.exit(e.returncode)
     except FileNotFoundError:
-        console.print(f"[bold red]Error:[/bold red] 'docker' command not found. Please ensure Docker is installed and in your PATH.")
+        print_error(
+            "'docker' command not found. Please ensure Docker is installed and in your PATH."
+        )
         sys.exit(1)
 
+    # Handle build logs and yaml updates
+    from videosdk_cli.utils.videosdk_yaml_helper import (
+        update_agent_config,
+        BuildConfig,
+        BuildLogsConfig,
+    )
+    import yaml
+
+    if enable_logs and presigned_url and build_output:
+        # Upload logs if enabled
+        print_info("Uploading build logs...")
+        try:
+            import aiohttp
 
+            async def upload_logs():
+                async with aiohttp.ClientSession() as session:
+                    async with session.put(
+                        presigned_url,
+                        data=build_output.encode("utf-8"),
+                        headers={"Content-Type": "text/plain"},
+                    ) as resp:
+                        if resp.status not in (200, 201, 204):
+                            raise Exception(f"Upload failed with status {resp.status}")
+
+            asyncio.run(upload_logs())
+            print_success("Build logs uploaded successfully")
+
+            # Save new build_id to videosdk.yaml (replaces any old one)
+            build_config = BuildConfig(logs=BuildLogsConfig(id=build_id, enabled=True))
+            update_agent_config(
+                app_dir=Path(os.getcwd()),
+                build_config=build_config,
+            )
+            print_success(f"Build ID saved to videosdk.yaml: {build_id}")
+
+        except Exception as e:
+            print_warning(f"Failed to upload build logs: {e}")
+    elif not enable_logs:
+        # Clear build logs from yaml if logs are not enabled
+        # This ensures old build IDs don't get used for new builds
+        try:
+            config_file = Path(os.getcwd()) / "videosdk.yaml"
+            if config_file.exists():
+                with open(config_file, "r") as f:
+                    config_data = yaml.safe_load(f) or {}
+
+                # Remove build.logs section if it exists
+                if "build" in config_data and isinstance(config_data["build"], dict):
+                    if "logs" in config_data["build"]:
+                        del config_data["build"]["logs"]
+                        # If build section is now empty, remove it
+                        if not config_data["build"]:
+                            del config_data["build"]
+
+                # Write back
+                with open(config_file, "w") as f:
+                    yaml.dump(config_data, f, default_flow_style=False, sort_keys=False)
+        except Exception:
+            # Silently fail if yaml doesn't exist or can't be updated
+            pass
+
+    # Exit with error if build failed
+    if not build_success:
+        sys.exit(1)
+
+
+# =============================================================================
+# AGENT PUSH
+# =============================================================================
 @agent_cli.command(name="push")
-@click.option( "-t", "--tag", default=None, help='Name and optionally a tag in the \'name:tag\' format.')
-@click.option("-r", "--registry", default=None, help='Registry URL custom or default dockerhub.io')
-@click.option("-u", "--username", default=None, help='Registry username')
-@click.option("-p", "--password", default=None, help='Registry password')
-def push(tag, registry, username, password):
-    """Push a Docker image to a registry."""
-    
-    # 1. Resolve Tag
-    tag = get_config_option(
-        tag, 
-        ['agent', 'image'], 
-        required=True, 
-        fail_message="--tag not provided and 'agent.image' not found in videosdk.yaml"
+@click.option(
+    "--image", "-i", default=None, help="Image name with tag (e.g., myrepo/myagent:v1)"
+)
+@click.option(
+    "--server", "-s", default=None, help="Registry server URL (default: docker.io)"
+)
+@click.option(
+    "--username", "-u", default=None, help="Registry username for authentication"
+)
+@click.option(
+    "--password", "-p", default=None, help="Registry password for authentication"
+)
+def push(image, server, username, password):
+    """
+    Push a Docker image to a container registry.
+
+    Pushes the built Docker image to Docker Hub or a private registry.
+    Optionally authenticate with username/password.
+
+    \b
+    Examples:
+      $ videosdk agent push --image myrepo/myagent:v1
+      $ videosdk agent push --image myrepo/myagent:v1 --server ghcr.io -u user -p token
+      $ videosdk agent push  # uses image from videosdk.yaml
+    """
+
+    # Resolve image tag: CLI > build.image > agent.image (legacy)
+    image = get_config_option(
+        image,
+        ["build", "image"],
+        required=False,
     )
-    tag = tag.lower()
-    ref = Reference.parse_normalized_named(tag)
-    hostname,name =ref.split_hostname()
-    registry = registry or hostname
+    if image is None:
+        image = get_config_option(
+            None,
+            ["agent", "image"],
+            required=True,
+            fail_message="--image not provided and 'build.image' or 'agent.image' not found in videosdk.yaml",
+        )
+    image = image.lower()
+    ref = Reference.parse_normalized_named(image)
+    hostname, name = ref.split_hostname()
+    registry = server or hostname
 
-    console.print(f"[bold blue]Pushing Docker image...[/bold blue]")
-    console.print(f"Tag: [green]{tag}[/green]")
-    console.print(f"Registry: [green]{registry}[/green]")
+    print_header("Pushing Docker Image")
+    print_key_value("Image", image)
+    print_key_value("Registry", registry)
+    print_divider()
 
-    # 4. Docker Login (if credentials provided)
+    # Docker Login (if credentials provided)
     if username and password:
         login_cmd = ["docker", "login", "-u", username, "-p", password]
         if registry != "docker.io":
             login_cmd.append(registry)
-        
-        console.print(f"Logging into {registry}...")
+
+        print_info(f"Logging into {registry}...")
         try:
             subprocess.run(login_cmd, check=True)
-            console.print(f"[bold green]Login successful.[/bold green]")
+            print_success("Login successful")
         except subprocess.CalledProcessError:
-            console.print(f"[bold red]Login failed.[/bold red]")
+            print_error("Login failed")
             sys.exit(1)
         except FileNotFoundError:
-            console.print(f"[bold red]Error:[/bold red] 'docker' command not found.")
+            print_error("'docker' command not found")
             sys.exit(1)
 
-    # 5. Docker Push
-    push_cmd = ["docker", "push", tag]
+    # Docker Push
+    push_cmd = ["docker", "push", image]
     try:
         subprocess.run(push_cmd, check=True)
-        console.print(f"[bold green]Successfully pushed image: {tag}[/bold green]")
+        console.print()
+        print_success(f"Successfully pushed image: {image}")
+        print_info(f"Next step: Deploy your agent")
+        console.print(f"  [bold]videosdk agent deploy --image {image}[/bold]")
     except subprocess.CalledProcessError:
-        console.print(f"[bold red]Failed to push image.[/bold red]")
+        print_error("Failed to push image")
         sys.exit(1)
     except FileNotFoundError:
-        console.print(f"[bold red]Error:[/bold red] 'docker' command not found.")
+        print_error("'docker' command not found")
         sys.exit(1)
 
 
+# =============================================================================
+# AGENT DEPLOY (creates a new version)
+# =============================================================================
 @agent_cli.command(name="deploy")
-@click.option("--tag", "-t", default=None, help='Name and optionally a tag in the \'name:tag\' format.')
+@click.argument("name", required=False, default=None)
 @click.option(
-    "--minReplica",
-    default=1,
+    "--image", "-i", default=None, help="Docker image URL (e.g., myrepo/myagent:v1)"
+)
+@click.option(
+    "--version-tag",
+    default=None,
+    help="Version tag (e.g., main/0.0.2)",
+)
+@click.option(
+    "--min-replica",
     type=click.IntRange(min=0),
-    help="Minimum replicas (>= 0)",
+    help="Minimum number of replicas (default: 1)",
+)
+@click.option(
+    "--max-replica",
+    type=click.IntRange(min=0, max=10),
+    help="Maximum number of replicas (default: 5)",
+)
+@click.option(
+    "--profile",
+    default="cpu-small",
+    help="Compute profile: cpu-small, cpu-medium, cpu-large (default: cpu-small)",
+)
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+@click.option(
+    "--deployment-id",
+    default=None,
+    help="Deployment ID (reads from videosdk.yaml if not provided)",
+)
+@click.option(
+    "--env-secret", default=None, help="ID of the environment secret set to use"
+)
+@click.option(
+    "--image-pull-secret",
+    default=None,
+    help="Name of the image pull secret for private registries",
+)
+@click.option(
+    "--region", default=None, help="Deployment region (e.g., us-east, eu-west)"
 )
 @click.option(
-    "--maxReplica",
-    default=5,
-    type=click.IntRange(min=0, max=50),
-    help="Maximum replicas (0–50)",
+    "--build-id",
+    default=None,
+    help="Build ID from build logs (reads from videosdk.yaml if logs were enabled)",
 )
-@click.option("--profile", default="cpu-small", help='Profile (cpu-small, cpu-medium, cpu-large)')
-@click.option("--agent-id", help='Agent ID')
-@click.option("--env-secret", help='Environment Secret')
-@click.option("--image-pull-secret", help='Image Pull Secret')
-def deploy(tag, minreplica, maxreplica, profile, agent_id,env_secret,image_pull_secret):
-    """Deploy an agent."""
+def deploy(
+    name,
+    image,
+    version_tag,
+    min_replica,
+    max_replica,
+    profile,
+    agent_id,
+    deployment_id,
+    env_secret,
+    image_pull_secret,
+    region,
+    build_id,
+):
+    """
+    Deploy a new version of your agent to VideoSDK cloud.
 
-    if minreplica > maxreplica:
-        raise click.BadParameter(
-            "--minReplica cannot be greater than --maxReplica"
-        )
+    Creates a new version with the specified configuration. The agent
+    will be scaled between min-replica and max-replica based on demand.
+
+    \b
+    Examples:
+      $ videosdk agent deploy --image myrepo/myagent:v1
+      $ videosdk agent deploy my-version --image myrepo/myagent:v1 --version-tag main/0.0.1
+      $ videosdk agent deploy --image myrepo/myagent:v1 --env-secret my-secrets --profile cpu-medium
+      $ videosdk agent deploy --build-id b_abc123  # link to build logs
+    """
 
-    # Resolve Tag/Image URL
-    tag = get_config_option(
-        tag, 
-        ['agent', 'image'], 
-        required=True, 
-        fail_message="--tag not provided and 'agent.image' not found in videosdk.yaml"
+    # Resolve image: CLI > build.image > agent.image (legacy)
+    image = get_config_option(
+        image,
+        ["build", "image"],
+        required=False,
     )
-    # The image URL is essentially the tag
-    ref = Reference.parse_normalized_named(tag)
-    hostname,name =ref.split_hostname()
-    image_url = tag
+    if image is None:
+        image = get_config_option(
+            None,
+            ["agent", "image"],
+            required=True,
+            fail_message="--image not provided and 'build.image' or 'agent.image' not found in videosdk.yaml",
+        )
+    ref = Reference.parse_normalized_named(image)
+    hostname, img_name = ref.split_hostname()
+    image_url = image
 
+    # Resolve agent_id
     agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
+    )
+
+    # Resolve deployment_id
+    deployment_id = get_config_option(
+        deployment_id,
+        ["deploy", "id"],
+        required=True,
+        fail_message="--deployment-id not provided and 'deploy.id' not found in videosdk.yaml",
+    )
+
+    # Resolve build_id: CLI > build.logs.id (if logs were enabled)
+    build_id = get_config_option(
+        build_id,
+        ["build", "logs", "id"],
+        required=False,
     )
-    
-    console.print(f"[bold blue]Deploying Agent...[/bold blue]")
-    console.print(f"Agent ID: [green]{agent_id}[/green]")
-    console.print(f"Image: [green]{image_url}[/green]")
-    console.print(f"Replicas: [green]{minreplica}-{maxreplica}[/green]")
-    console.print(f"Profile: [green]{profile}[/green]")
 
+    agent_name = get_config_option(
+        None,
+        ["agent", "name"],
+        required=False,
+    )
+
+    name = get_config_option(
+        name,
+        ["deploy", "name"],
+        required=False,
+        default=f"{agent_name}'s version",
+    )
+
+    min_replica = get_config_option(
+        min_replica, ["deploy", "replicas", "min"], required=False, default=1
+    )
+    max_replica = get_config_option(
+        max_replica, ["deploy", "replicas", "max"], required=False, default=3
+    )
+    if max_replica < min_replica:
+        print_error(
+            f"Max replicas({max_replica}) cannot be less than min replicas({min_replica})"
+        )
+        sys.exit(1)
+
+    profile = get_config_option(profile, ["deploy", "profile"], required=False)
+
+    region = get_config_option(region, ["deploy", "region"], required=False)
+
+    env_secret = get_config_option(env_secret, ["secrets", "env"], required=False)
+
+    image_pull_secret = get_config_option(
+        image_pull_secret, ["secrets", "image-pull"], required=False
+    )
+    print_header("Creating Version")
+    if name:
+        print_key_value("Version Name", name)
+    if version_tag:
+        print_key_value("Version Tag", version_tag)
+    print_key_value("Agent ID", agent_id)
+    print_key_value("Deployment ID", deployment_id)
+    print_key_value("Image", image_url)
+    if min_replica:
+        print_key_value("Min Replicas", min_replica)
+    if max_replica:
+        print_key_value("Max Replicas", max_replica)
+    if profile:
+        print_key_value("Profile", profile)
+    if region:
+        print_key_value("Region", region)
+    if env_secret:
+        print_key_value("Env Secret", env_secret)
+    if image_pull_secret:
+        print_key_value("Image Pull Secret", image_pull_secret)
+    if build_id:
+        print_key_value("Build ID", build_id)
+    print_divider()
     client = DeploymentClient()
     try:
-        asyncio.run(run_with_progress(
-            client.agent_deployment(
-                agent_id=agent_id,
-                image_url=image_url,
-                min_replica=minreplica,
-                max_replica=maxreplica,
-                profile=profile,
-                image_cr=hostname,
-                image_pull_secret=image_pull_secret,
-                env_secret=env_secret
-            ),
-            console=console,
-            title="Deploying Agent",
-            duration=5.0,
-        ))
-        console.print(f"[bold green]Deployment triggered successfully for agent: {agent_id}[/bold green]")
+        response = asyncio.run(
+            run_with_progress(
+                client.create_version(
+                    name=name,
+                    agent_id=agent_id,
+                    deployment_id=deployment_id,
+                    version_tag=version_tag,
+                    image_url=image_url,
+                    min_replica=min_replica,
+                    max_replica=max_replica,
+                    profile=profile,
+                    image_cr=hostname,
+                    image_pull_secret=image_pull_secret,
+                    env_secret=env_secret,
+                    region=region,
+                    build_id=build_id,
+                ),
+                console=console,
+                title="Creating Version",
+                duration=5.0,
+            )
+        )
+        version_id = response.get("id") if response else None
+        print_success(f"Version created successfully for agent: {agent_id} and versionId: {version_id}")
+        if version_id:
+            print_key_value("Version ID", version_id)
+            print_info("Next step: Check version status")
+            console.print(
+                f"  [bold]videosdk agent version status -v {version_id}[/bold]"
+            )
     except KeyboardInterrupt:
-        console.print("\n[yellow]Deployment cancelled by user.[/yellow]")
+        print_warning("Version creation cancelled by user")
         raise click.Abort()
     except Exception as e:
-        console.print(f"[bold red]Deployment failed:[/bold red] {e}")
+        print_error(f"Version creation failed: {e}")
 
 
-@agent_cli.command(name="deploy-update")
-@click.option("--deployment-id","-d",required=True,help="deployment id you want to update")
+@agent_cli.command(name="logs")
 @click.option(
-    "--minReplica",
-    type=click.IntRange(min=0),
-    help="Minimum replicas (>= 0)",
-)
-@click.option(
-    "--maxReplica",
-    type=click.IntRange(min=0, max=50),
-    help="Maximum replicas (0–50)",
-)
-@click.option("--profile", help='Profile (cpu-small, cpu-medium, cpu-large)')
-@click.option("--agent-id", help='Agent ID')
-@click.option("--env-secret", help='Environment Secret')
-@click.option("--image-pull-secret", help='Image Pull Secret')
-def deploy_update(deployment_id,minreplica,maxreplica,profile,agent_id,env_secret,image_pull_secret):
-    console.print(f"[bold blue]Updating Deployment...[/bold blue]")
-    console.print(f"Min Replicas: [green]{minreplica}[/green]")
-    console.print(f"Max Replicas: [green]{maxreplica}[/green]")
-    console.print(f"Profile: [green]{profile}[/green]")
-    # Resolve Tag/Image URL
-   
-    image_url = None
-    hostname = None
+    "--version-id",
+    "-v",
+    default=None,
+    help="Version ID (uses latest if not provided)",
+)
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+@click.option(
+    "--limit",
+    "-n",
+    default=50,
+    type=click.IntRange(min=1, max=1000),
+    help="Number of log entries to show (default: 50)",
+)
+def logs(version_id, agent_id, limit):
+    """
+    View console logs for a version.
+
+    Shows the latest console output from your agent version.
+    Useful for debugging and monitoring agent behavior.
+
+    \b
+    Examples:
+      $ videosdk agent logs
+      $ videosdk agent logs --agent-id abc123 --version-id ver123
+      $ videosdk agent logs --limit 100
+    """
+    print_header("Agent Deployment Logs")
 
     agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
     )
-    
-    client = DeploymentClient()
+
+    deployment_id = get_config_option(
+        None,
+        ["deploy", "id"],
+        required=True,
+        fail_message="'deploy.id' not found in videosdk.yaml",
+    )
+
+    print_key_value("Agent ID", agent_id)
+    if version_id:
+        print_key_value("Version ID", version_id)
+    print_key_value("Limit", str(limit))
+    print_divider()
+
     try:
-        asyncio.run(run_with_progress(
-            client.agent_deployment_update(
-                deployment_id=deployment_id,
+        asyncio.run(
+            version_logs_manager(
                 agent_id=agent_id,
-                image_cr=hostname,
-                image_url=image_url,
-                env_secret=env_secret,
-                image_pull_secret=image_pull_secret,
-                min_replica=minreplica,
-                max_replica=maxreplica,
-                profile=profile
-            ),
-            console=console,
-            title="Updating Deployment",
-            duration=5.0,
-        ))
-        console.print(f"[bold green]Deployment updated successfully[/bold green]")
-    except KeyboardInterrupt:
-        console.print("\n[yellow]Deployment update cancelled by user.[/yellow]")
-        raise click.Abort()
+                deployment_id=deployment_id,
+                version_id=version_id,
+                limit=limit,
+            )
+        )
     except Exception as e:
-        console.print(f"[bold red]Deployment update failed:[/bold red] {e}")
-
-# @agent_cli.command(name="deploy list")
-# @click.option("--deployment-id", default=None, help='Deployment ID')
-# def deploy_list(deployment_id):
-@agent_cli.command(name="deploy-deactivate")
-@click.option("--deployment-id", default=None,required=True,help='Deployment ID')
-@click.option("--force",default=False,help='Force deactivate')
-@click.option("--agent-id",help='Agent ID')
-def deploy_deactivate(deployment_id,force,agent_id):
-    """Deactivate a deployment."""
-    console.print("[bold blue]Deactivating Deployment...[/bold blue]")
+        print_error(str(e))
+
+
+# =============================================================================
+# VERSION SUBGROUP
+# =============================================================================
+@click.group()
+def version_cli():
+    """
+    Manage agent versions.
+
+    View, update, and control the lifecycle of your agent versions.
+
+    \b
+    Commands:
+      list        List all versions for an agent deployment
+      update      Update version configuration
+      activate    Activate a version
+      deactivate  Deactivate a version
+      status      Get version status
+      describe    Get detailed version info
+    """
+    pass
+
+
+@version_cli.command(name="list")
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+@click.option(
+    "--deployment-id",
+    default=None,
+    help="Deployment ID (reads from videosdk.yaml if not provided)",
+)
+@click.option(
+    "--page",
+    default=1,
+    type=click.IntRange(min=1),
+    help="Page number (default: 1)",
+)
+@click.option(
+    "--per-page",
+    default=10,
+    type=click.IntRange(min=1, max=100),
+    help="Items per page (default: 10)",
+)
+@click.option(
+    "--sort",
+    default="-1",
+    type=click.Choice(["1", "-1"]),
+    help="Sort order: 1 (oldest first) or -1 (newest first, default)",
+)
+def version_list(agent_id, deployment_id, page, per_page, sort):
+    """
+    List all versions for an agent.
+
+    Shows a table of all versions with their status, region, and profile.
+
+    \b
+    Examples:
+      $ videosdk agent version list
+      $ videosdk agent version list --agent-id abc123
+      $ videosdk agent version list --page 2 --per-page 20
+      $ videosdk agent version list --sort 1  # oldest first
+    """
+    print_header("Listing Versions")
     agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
     )
-    client = DeploymentClient()
+
+    deployment_id = get_config_option(
+        deployment_id,
+        ["deploy", "id"],
+        required=True,
+        fail_message="--deployment-id not provided and 'deploy.id' not found in videosdk.yaml",
+    )
+    print_key_value("Agent ID", agent_id)
+    print_key_value("Deployment ID", deployment_id)
+
     try:
-        asyncio.run(run_with_progress(
-            client.agent_deactivate(deployment_id=deployment_id,agent_id=agent_id,force=force),
-            console=console,
-            title="Deactivating Deployment",
-            duration=2.0,
-        ))
-        console.print("[bold green]Deployment deactivated successfully.[/bold green]")
+        asyncio.run(
+            list_versions_manager(agent_id, deployment_id, page, per_page, int(sort))
+        )
     except Exception as e:
-        console.print(f"[bold red]Failed to deactivate deployment:[/bold red] {e}")
-
-@agent_cli.command(name="deploy-activate")
-@click.option("--deployment-id", default=None,required=True,help='Deployment ID')
-@click.option("--agent-id",help='Agent ID')
-def deploy_activate(deployment_id,agent_id):
-    """Activate a deployment."""
-    console.print("[bold blue]Activating Deployment...[/bold blue]")
+        print_error(str(e))
+
+
+@version_cli.command(name="update")
+@click.option("--version-id", "-v", required=True, help="Version ID to update")
+@click.option("--min-replica", type=click.IntRange(min=0), help="New minimum replicas")
+@click.option(
+    "--max-replica", type=click.IntRange(min=0, max=50), help="New maximum replicas"
+)
+@click.option("--profile", help="New compute profile: cpu-small, cpu-medium, cpu-large")
+@click.option("--image-pull-secret", help="New image pull secret name")
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+@click.option("--env-secret", help="New environment secret name")
+def version_update(
+    version_id,
+    min_replica,
+    max_replica,
+    profile,
+    image_pull_secret,
+    agent_id,
+    env_secret,
+):
+    """
+    Update an existing version configuration.
+
+    Modify replica counts, profile, or secrets for a running version.
+
+    \b
+    Examples:
+      $ videosdk agent version update -v ver123 --min-replica 2 --max-replica 10
+      $ videosdk agent version update -v ver123 --profile cpu-large
+      $ videosdk agent version update -v ver123 --env-secret new-secrets
+    """
+    print_header("Updating Version")
+
     agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
     )
+
+    if min_replica is not None:
+        print_key_value("Min Replicas", str(min_replica))
+    if max_replica is not None:
+        print_key_value("Max Replicas", str(max_replica))
+    if profile:
+        print_key_value("Profile", profile)
+    if env_secret:
+        print_key_value("Env Secret", env_secret)
+    if image_pull_secret:
+        print_key_value("Image Pull Secret", image_pull_secret)
+
     client = DeploymentClient()
     try:
-        asyncio.run(run_with_progress(
-            client.agent_activate(deployment_id=deployment_id,agent_id=agent_id),
-            console=console,
-            title="Activating Deployment",
-            duration=2.0,
-        ))
-        console.print("[bold green]Deployment activated successfully.[/bold green]")
+        asyncio.run(
+            run_with_progress(
+                client.update_version(
+                    version_id=version_id,
+                    image_cr=None,
+                    image_url=None,
+                    env_secret=env_secret,
+                    image_pull_secret=image_pull_secret,
+                    min_replica=min_replica,
+                    max_replica=max_replica,
+                    profile=profile,
+                ),
+                console=console,
+                title="Updating Version",
+                duration=5.0,
+            )
+        )
+        print_success("Version updated successfully")
+    except KeyboardInterrupt:
+        print_warning("Version update cancelled by user")
+        raise click.Abort()
     except Exception as e:
-        console.print(f"[bold red]Failed to deactivate deployment:[/bold red] {e}")
-    
-@agent_cli.command(name="start")
-@click.option("--deployment-id","-d",default=None,help='Deployment ID')
-@click.option("--agent-id","-a",default=None,help='Agent ID')
-@click.option("--meeting-id","-m",default=None,help='Meeting ID')
-def start(deployment_id,agent_id,meeting_id):
-    console.print("[bold blue]Starting Deployment...[/bold blue]")
+        print_error(f"Version update failed: {e}")
+
+
+@version_cli.command(name="activate")
+@click.option("--version-id", "-v", required=True, help="Version ID to activate")
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+def version_activate(version_id, agent_id):
+    """
+    Activate a version.
+
+    Enables a previously deactivated version to start receiving traffic.
+
+    \b
+    Example:
+      $ videosdk agent version activate -v ver123
+    """
+    print_header("Activating Version")
+
     agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
     )
+
     client = DeploymentClient()
     try:
-        asyncio.run(run_with_progress(
-            client.agent_start(deployment_id=deployment_id,agent_id=agent_id,meeting_id=meeting_id),
-            console=console,
-            title="Starting Deployment",
-            duration=2.0,
-        ))
-        console.print("[bold green]Deployment started successfully.[/bold green]")
+        asyncio.run(
+            run_with_progress(
+                client.activate_version(version_id=version_id),
+                console=console,
+                title="Activating Version",
+                duration=2.0,
+            )
+        )
+        print_success("Version activated successfully")
     except Exception as e:
-        console.print(f"[bold red]Failed to start deployment:[/bold red] {e}")
+        print_error(f"Failed to activate version: {e}")
+
+
+@version_cli.command(name="deactivate")
+@click.option("--version-id", "-v", required=True, help="Version ID to deactivate")
+@click.option(
+    "--force",
+    is_flag=True,
+    default=False,
+    help="Force deactivate even with active sessions",
+)
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+def version_deactivate(version_id, force, agent_id):
+    """
+    Deactivate a version.
 
-@agent_cli.command(name="stop")
-@click.option("--meeting-id","-m",default=None,help='Meeting ID')
-def stop(meeting_id):
-    console.print("[bold blue]Stopping Deployment...[/bold blue]")
+    Stops a version from receiving new traffic. Use --force to
+    deactivate even if there are active sessions.
+
+    \b
+    Examples:
+      $ videosdk agent version deactivate -v ver123
+      $ videosdk agent version deactivate -v ver123 --force
+    """
+    print_header("Deactivating Version")
+
+    agent_id = get_config_option(
+        agent_id,
+        ["agent", "id"],
+        required=True,
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
+    )
 
     client = DeploymentClient()
     try:
-        asyncio.run(run_with_progress(
-            client.agent_stop(meeting_id=meeting_id),
-            console=console,
-            title="Stopping Deployment",
-            duration=2.0,
-        ))
-        console.print("[bold green]Deployment stopped successfully.[/bold green]")
+        response = asyncio.run(
+            run_with_progress(
+                client.deactivate_version(version_id=version_id, force=force),
+                console=console,
+                title="Deactivating Version",
+                duration=2.0,
+            )
+        )
+        print_success(response["message"])
     except Exception as e:
-        console.print(f"[bold red]Failed to stop deployment:[/bold red] {e}")
-
-@agent_cli.command(name="list")
-@click.option("--agent-id", default=None, help='Agent ID')
-@click.option("--head", default=None,type=click.IntRange(min=0, max=500),help='Number of agents to list')
-@click.option("--tail",default=None,type=click.IntRange(min=0, max=500),help='Number of agents to list')
-def list_agents(agent_id,head,tail):
-    """List all agents."""
-    console.print(f"[bold blue]Listing Agents...[/bold blue]")
-    console.print(f"Agent ID: [green]{agent_id}[/green]")
-    agent_id=get_config_option(
+        print_error(f"Failed to deactivate version: {e}")
+
+
+@version_cli.command(name="status")
+@click.option("--version-id", "-v", required=True, help="Version ID to check")
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+def version_status(version_id, agent_id):
+    """
+    Get the current status of a version.
+
+    Shows whether the version is active, replica counts, and health status.
+
+    \b
+    Example:
+      $ videosdk agent version status -v ver123
+    """
+    print_header("Getting Version Status")
+
+    agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
     )
+
     try:
-        asyncio.run(
-            list_agents_manager(agent_id,head,tail)
-        )
-        console.print(f"[bold green]Agents listed successfully.[/bold green]")
+        asyncio.run(describe_version_manager(agent_id, version_id))
+        print_info("Next step: Start a session")
+        console.print(f"  [bold]videosdk agent session start -v {version_id}[/bold]")
     except Exception as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
-
-@agent_cli.command(name="describe")
-@click.option("--agent-id", default=None, help='Agent ID')
-@click.option("--deployment-id", default=None, help='Deployment ID')
-def describe_agent(agent_id,deployment_id):
-    console.print(f"[bold blue]Describing Agent...[/bold blue]")
-    console.print(f"Agent ID: [green]{agent_id}[/green]")
-    agent_id=get_config_option(
+        print_error(str(e))
+
+
+@version_cli.command(name="describe")
+@click.option("--version-id", "-v", required=True, help="Version ID to describe")
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+def version_describe(version_id, agent_id):
+    """
+    Get detailed information about a version.
+
+    Shows complete version configuration including image, replicas,
+    profile, secrets, and creation time.
+
+    \b
+    Example:
+      $ videosdk agent version describe -v ver123
+    """
+    print_header("Describing Version")
+
+    agent_id = get_config_option(
         agent_id,
-        ['agent', 'id'],
+        ["agent", "id"],
         required=True,
-        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml"
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
     )
-    deployment_id=get_config_option(
-        deployment_id,
-        ['agent', 'deploymentId'],
-        required=False,
-        fail_message="--deployment-id not provided and 'agent.deploymentId' not found in videosdk.yaml"
+
+    try:
+        asyncio.run(describe_version_manager(agent_id, version_id))
+    except Exception as e:
+        print_error(str(e))
+
+
+# Add version subgroup to agent
+agent_cli.add_command(version_cli, name="version")
+
+
+# =============================================================================
+# SESSIONS SUBGROUP
+# =============================================================================
+@click.group()
+def sessions_cli():
+    """
+    Manage agent sessions.
+
+    View and filter sessions for your agents.
+
+    \b
+    Commands:
+      list        List all sessions for an agent
+    """
+    pass
+
+
+@sessions_cli.command(name="list")
+@click.option(
+    "--agent-id",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+@click.option("--version-id", "-v", help="Filter by Version ID")
+@click.option("--room-id", help="Filter by Room ID")
+@click.option("--session-id", help="Filter by Session ID")
+@click.option(
+    "--page",
+    default=1,
+    type=click.IntRange(min=1),
+    help="Page number (default: 1)",
+)
+@click.option(
+    "--per-page",
+    default=10,
+    type=click.IntRange(min=1, max=100),
+    help="Items per page (default: 10)",
+)
+@click.option(
+    "--sort",
+    default=-1,
+    type=click.Choice(["1", "-1"]),
+    help="Sort order: 1 (oldest first) or -1 (newest first, default)",
+)
+def sessions_list(agent_id, version_id, room_id, session_id, page, per_page, sort):
+    """
+    List all sessions for an agent.
+
+    Shows a table of sessions with their status, room, and version info.
+    Supports filtering by version, room, and session IDs.
+
+    \b
+    Examples:
+      $ videosdk agent sessions list
+      $ videosdk agent sessions list --agent-id abc123
+      $ videosdk agent sessions list --version-id ver123
+      $ videosdk agent sessions list --page 2 --per-page 20
+      $ videosdk agent sessions list --sort 1  # oldest first
+    """
+    print_header("Listing Sessions")
+
+    agent_id = get_config_option(
+        agent_id,
+        ["agent", "id"],
+        required=True,
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
+    )
+    deployment_id = get_config_option(
+        None,
+        ["deploy", "id"],
+        required=True,
+        fail_message="'deploy.id' not found in videosdk.yaml",
     )
+    print_key_value("Agent ID", agent_id)
+    print_key_value("Deployment ID", deployment_id)
     try:
         asyncio.run(
-            describe_agent_manager(agent_id,deployment_id)
+            list_sessions_manager(
+                agent_id=agent_id,
+                deployment_id=deployment_id,
+                version_id=version_id,
+                room_id=room_id,
+                session_id=session_id,
+                page=page,
+                per_page=per_page,
+                sort=int(sort),
+            )
         )
     except Exception as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
+        print_error(str(e))
+
+
+# Add sessions subgroup to agent
+agent_cli.add_command(sessions_cli, name="sessions")
+
+
+# =============================================================================
+# SECRETS SUBGROUP
+# =============================================================================
+@click.group(invoke_without_command=True)
+# @click.argument("name", required=False, default=None)
+@click.pass_context
+# def secrets_cli(ctx, name):
+def secrets_cli(ctx):
+    """
+    Manage agent secrets.
+
+    Create, update, and manage secret sets for your agents.
+    Secrets are securely stored and injected as environment variables.
 
+    \b
+    Usage:
+      videosdk agent secrets list                          List all secrets
+      videosdk agent secrets create <name> [--file .env]   Create a secret
+      videosdk agent secrets add <name>                    Add keys to secret
+      videosdk agent secrets remove <name>                 Remove keys from secret
+      videosdk agent secrets describe <name>               Show secret details
+      videosdk agent secrets delete <name>                 Delete a secret
+    """
+    ctx.ensure_object(dict)
 
+    # # Handle "videosdk agent secrets list" - when "list" is passed as name
+    # if name == "list" and ctx.invoked_subcommand is None:
+    #     try:
+    #         print_header("Listing Secrets")
+    #         asyncio.run(list_secret_manager())
+    #     except Exception as e:
+    #         print_error(str(e))
+    #     ctx.exit(0)
+
+    # # If name is provided and subcommand is "list", show error
+    # if name and ctx.invoked_subcommand == "list":
+    #     print_error(
+    #         "The 'list' command does not take a secret name. Use 'videosdk agent secrets list'"
+    #     )
+    #     ctx.exit(1)
+
+    # # If name is provided but no subcommand, show error
+    # if name and ctx.invoked_subcommand is None:
+    #     print_error(
+    #         f"Missing subcommand for secret '{name}'. "
+    #         "Use one of: create, add, remove, describe, delete"
+    #     )
+    #     console.print()
+    #     console.print("Examples:")
+    #     console.print(f"  videosdk agent secrets create {name} ")
+    #     console.print(f"  videosdk agent secrets describe {name} ")
+    #     console.print(f"  videosdk agent secrets delete {name} ")
+    #     ctx.exit(1)
+
+    # ctx.obj["secret_name"] = name
+
+
+@secrets_cli.command(name="list")
+@click.pass_context
+def secrets_list(ctx):
+    """
+    List all secret sets.
+
+    Shows a table of all secrets with their names, IDs, and types.
+
+    \b
+    Example:
+      $ videosdk agent secrets list
+    """
+    # Check if a name was provided (should not be)
+    if ctx.obj.get("secret_name"):
+        print_error(
+            "The 'list' command does not take a secret name. Use 'videosdk agent secrets list'"
+        )
+        ctx.exit(1)
+
+    try:
+        print_header("Listing Secrets")
+        asyncio.run(list_secret_manager())
+    except Exception as e:
+        print_error(str(e))
+
+
+@secrets_cli.command(name="create")
+@click.argument("name")
+@click.option(
+    "--file",
+    "-f",
+    "file_path",
+    default=None,
+    help="Path to .env file with key=value pairs",
+)
+@click.option("--region", default=None, help="Region for storing secrets")
+@click.pass_context
+def secrets_create(ctx, name, file_path, region):
+    """
+    Create a new secret set.
+
+    Creates a new secret set with the given name. Provide secrets via
+    a .env file or enter them interactively.
+
+    \b
+    Examples:
+      $ videosdk agent secrets create my-secrets --file .env
+      $ videosdk agent secrets create my-secrets  # interactive mode
+    """
+    # name = ctx.obj.get("secret_name")
+    if not name:
+        print_error("Secret name is required")
+        return
+    try:
+        print_header("Creating Secret")
+        response = asyncio.run(secret_set_manager(name, file_path))
+        print_success(f"Secret '{name}' created successfully")
+
+        # Extract secret ID from response
+        secret_id = None
+        if response:
+            # Try different possible response formats
+            secret_id = (
+                response.get("secretId")
+                or response.get("id")
+                or response.get("data", {}).get("secretId")
+                or response.get("data", {}).get("id")
+            )
+
+        if secret_id:
+            # Save secret ID to videosdk.yaml
+            from videosdk_cli.utils.videosdk_yaml_helper import (
+                update_agent_config,
+                SecretsConfig,
+            )
+
+            secrets_config = SecretsConfig(env=secret_id)
+            update_agent_config(
+                app_dir=Path(os.getcwd()),
+                secrets_config=secrets_config,
+            )
+            print_success(f"Secret ID saved to videosdk.yaml: {secret_id}")
+        else:
+            print_warning(
+                "Could not extract secret ID from response. Secret created but not saved to yaml."
+            )
+    except click.Abort:
+        print_warning("Cancelled. No secrets were saved.")
+    except Exception as e:
+        print_error(str(e))
+
+
+@secrets_cli.command(name="add")
+@click.argument("name")
+@click.pass_context
+def secrets_add(ctx, name):
+    """
+    Add keys to an existing secret set.
+
+    Interactively add new key-value pairs to an existing secret.
+
+    \b
+    Example:
+      $ videosdk agent secrets add my-secrets
+    """
+    # name = ctx.obj.get("secret_name")
+    if not name:
+        print_error("Secret name is required")
+        return
+    try:
+        print_header("Adding to Secret")
+        asyncio.run(add_secret_set(name))
+        print_success(f"Keys added to secret '{name}' successfully")
+    except Exception as e:
+        print_error(str(e))
+
+
+@secrets_cli.command(name="remove")
+@click.argument("name")
+@click.pass_context
+def secrets_remove(ctx, name):
+    """
+    Remove keys from a secret set.
+
+    Interactively select and remove specific keys from a secret.
+
+    \b
+    Example:
+      $ videosdk agent secrets remove my-secrets
+    """
+    # name = ctx.obj.get("secret_name")
+    if not name:
+        print_error("Secret name is required")
+        return
+    try:
+        print_header("Removing Keys from Secret")
+        asyncio.run(remove_secret_set_key(name))
+    except Exception as e:
+        print_error(str(e))
+
+
+@secrets_cli.command(name="describe")
+@click.argument("name")
+@click.pass_context
+def secrets_describe(ctx, name):
+    """
+    Show details of a secret set.
+
+    Displays the secret name, ID, type, and list of keys (values hidden).
+
+    \b
+    Example:
+      $ videosdk agent secrets describe my-secrets
+    """
+    # name = ctx.obj.get("secret_name")
+    if not name:
+        print_error("Secret name is required")
+        return
+    try:
+        print_header("Describing Secret")
+        asyncio.run(describe_secret_set(name))
+    except Exception as e:
+        print_error(str(e))
+
+
+@secrets_cli.command(name="delete")
+@click.argument("name")
+@click.pass_context
+def secrets_delete(ctx, name):
+    """
+    Delete a secret set.
+
+    Permanently deletes the secret set and all its keys.
+    This action cannot be undone.
+
+    \b
+    Example:
+      $ videosdk agent secrets delete my-secrets
+    """
+    # name = ctx.obj.get("secret_name")
+    if not name:
+        print_error("Secret name is required")
+        return
+    try:
+        print_header("Deleting Secret")
+        asyncio.run(remove_secret_set(name))
+        print_success(f"Secret '{name}' deleted successfully")
+    except Exception as e:
+        print_error(str(e))
+
+
+# Add secrets subgroup to agent
+agent_cli.add_command(secrets_cli, name="secrets")
+
+
+# =============================================================================
+# IMAGE PULL SECRET
+# =============================================================================
 @agent_cli.command(name="image-pull-secret")
-@click.option("--name",required=True, help='Secret set name')
-def image_pull_secret(name):
+@click.argument("name")
+@click.option("--region", default=None, help="Region for storing the secret")
+def image_pull_secret(name, region):
+    """
+    Create an image pull secret for private container registries.
+
+    Stores registry credentials securely for pulling private Docker images.
+    You will be prompted for server, username, and password.
+
+    \b
+    Examples:
+      $ videosdk agent image-pull-secret my-registry-creds
+      $ videosdk agent image-pull-secret ghcr-secret --region us-east
+    """
+    try:
+        print_header("Creating Image Pull Secret")
+        asyncio.run(image_pull_secret_manager(name))
+        print_success(f"Image pull secret '{name}' created successfully")
+    except Exception as e:
+        print_error(str(e))
+
+
+# =============================================================================
+# SESSION SUBGROUP
+# =============================================================================
+@click.group()
+def session_cli():
+    """
+    Manage agent sessions.
+
+    Start and stop individual agent sessions in rooms.
+
+    \b
+    Commands:
+      start  Start an agent in a room
+      stop   Stop an agent session
+    """
+    pass
+
+
+@session_cli.command(name="start")
+@click.option("--version-id", "-v", default=None, help="Version ID to use")
+@click.option(
+    "--room-id",
+    "-r",
+    default=None,
+    help="Room ID to join (creates new room if not provided)",
+)
+@click.option(
+    "--agent-id",
+    "-a",
+    default=None,
+    help="Agent ID (reads from videosdk.yaml if not provided)",
+)
+def session_start(version_id, room_id, agent_id):
+    """
+    Start an agent session in a room.
+
+    Dispatches an agent to join the specified room. If no room-id is
+    provided, a new room will be created automatically.
+
+    \b
+    Examples:
+      $ videosdk agent session start -r room-abc # uses latest version of agent if not provided
+      $ videosdk agent session start -v ver123  # creates new room
+      $ videosdk agent session start -v ver123 -r room-abc
+      $ videosdk agent session start  # uses latest version
+    """
+    print_header("Starting Session")
+
+    agent_id = get_config_option(
+        agent_id,
+        ["agent", "id"],
+        required=True,
+        fail_message="--agent-id not provided and 'agent.id' not found in videosdk.yaml",
+    )
+
+    client = DeploymentClient()
+    try:
+        result = asyncio.run(
+            run_with_progress(
+                client.agent_start(
+                    version_id=version_id, agent_id=agent_id, meeting_id=room_id
+                ),
+                console=console,
+                title="Starting Session",
+                duration=30.0,
+            )
+        )
+        print_success("Session started successfully")
+
+        # Extract room_id from result
+        started_room_id = result.get("roomId") if result else room_id
+        if started_room_id:
+            print_key_value("Room ID", started_room_id)
+            print_info("Useful commands:")
+            console.print(f"  [bold]View logs:[/bold] videosdk agent version logs")
+            console.print(
+                f"  [bold]Stop session:[/bold] videosdk agent session stop -r {started_room_id}"
+            )
+    except Exception as e:
+        print_error(f"Failed to start session: {e}")
+
+
+@session_cli.command(name="stop")
+@click.option("--room-id", "-r", default=None, help="Room ID of the session")
+@click.option("--session-id", "-s", default=None, help="Session ID to stop")
+def session_stop(room_id, session_id):
+    """
+    Stop an agent session.
+    \b
+    Examples:
+      $ videosdk agent session stop -r room-abc
+      $ videosdk agent session stop -s session-123
+    """
+    print_header("Stopping Session")
+
+    if not room_id and not session_id:
+        print_error("Either --room-id or --session-id is required")
+        sys.exit(1)
+
+    client = DeploymentClient()
     try:
         asyncio.run(
-            image_pull_secret_manager(name)
+            run_with_progress(
+                client.agent_stop(meeting_id=room_id, session_id=session_id),
+                console=console,
+                title="Ending Session",
+                duration=2.0,
+            )
         )
+        print_success("Session ended successfully")
     except Exception as e:
-        console.print(f"[bold red]Error:[/bold red] {e}")
+        print_error(f"Failed to stop session: {e}")
+
 
-agent_cli.add_command(secret_set)
+# Add session subgroup to agent
+agent_cli.add_command(session_cli, name="session")