ptctools 0.1.1__py3-none-any.whl → 0.2.0__py3-none-any.whl

ptctools/cli.py

@@ -3,11 +3,8 @@
 import click
 
 from ptctools import __version__
-from ptctools import stack
-from ptctools import volume
-from ptctools import db
+from ptctools import docker
 from ptctools import utils
-from ptctools import config
 
 
 @click.group()
@@ -17,11 +14,11 @@ def main():
     pass
 
 
-main.add_command(stack.cli, name="stack")
-main.add_command(volume.cli, name="volume")
-main.add_command(db.cli, name="db")
+# Docker commands (via Portainer Docker proxy)
+main.add_command(docker.cli, name="docker")
+
+# Local utility commands (no Portainer needed)
 main.add_command(utils.cli, name="utils")
-main.add_command(config.cli, name="config")
 
 
 if __name__ == "__main__":

ptctools/config.py

@@ -19,6 +19,7 @@ logger = logging.getLogger(__name__)
 
 class ConfigError(PortainerError):
     """Exception for Docker config operations."""
+
     pass
 
 
@@ -29,7 +30,13 @@ def cli():
 
 
 @cli.command("set")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--name", "-n", required=True, help="Config name")
 @click.option("--data", "-d", default=None, help="Config data (string content)")
 @click.option(
@@ -41,9 +48,7 @@ def cli():
     help="Read config data from file",
 )
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
-@click.option(
-    "--force", is_flag=True, help="Replace existing config if it exists"
-)
+@click.option("--force", is_flag=True, help="Replace existing config if it exists")
 def set_config(
     url: str,
     name: str,
@@ -57,13 +62,13 @@ def set_config(
     Examples:
 
         # Create from inline data
-        ptctools config set -u https://portainer.example.com -n my-config -d "config content"
+        ptctools docker config set -u https://portainer.example.com -n my-config -d "config content"
 
         # Create from file
-        ptctools config set -u https://portainer.example.com -n nginx.conf -f ./nginx.conf
+        ptctools docker config set -u https://portainer.example.com -n nginx.conf -f ./nginx.conf
 
         # Replace existing config
-        ptctools config set -u https://portainer.example.com -n my-config -d "new content" --force
+        ptctools docker config set -u https://portainer.example.com -n my-config -d "new content" --force
     """
     # Validate that exactly one of --data or --file is provided
     if data is None and file_path is None:
@@ -88,7 +93,7 @@ def set_config(
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         # Check if config already exists
         existing = None
         for config in client.configs.list():
@@ -119,7 +124,13 @@ def set_config(
 
 
 @cli.command("get")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--name", "-n", required=True, help="Config name")
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
 def get_config_cmd(url: str, name: str, endpoint_id: int):
@@ -138,7 +149,7 @@ def get_config_cmd(url: str, name: str, endpoint_id: int):
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         config = None
         for c in client.configs.list():
             if c.name == name:
@@ -158,7 +169,13 @@ def get_config_cmd(url: str, name: str, endpoint_id: int):
 
 
 @cli.command("list")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
 def list_configs_cmd(url: str, endpoint_id: int):
     """List all Docker Swarm configs."""
@@ -195,7 +212,13 @@ def list_configs_cmd(url: str, endpoint_id: int):
 
 
 @cli.command("delete")
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--name", "-n", required=True, help="Config name")
 @click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
 def delete_config_cmd(url: str, name: str, endpoint_id: int):
@@ -211,7 +234,7 @@ def delete_config_cmd(url: str, name: str, endpoint_id: int):
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         config = None
         for c in client.configs.list():
             if c.name == name:

ptctools/db.py

@@ -10,7 +10,11 @@ import traceback
 import click
 import docker
 
-from ptctools._portainer import get_portainer_docker_client, run_container, PortainerError
+from ptctools._portainer import (
+    get_portainer_docker_client,
+    run_container,
+    PortainerError,
+)
 from ptctools._s3 import parse_s3_uri, is_s3_uri, get_s3_endpoint, get_s3_credentials
 
 logger = logging.getLogger(__name__)
@@ -18,6 +22,7 @@ logger = logging.getLogger(__name__)
 
 class DatabaseError(PortainerError):
     """Exception for database operations."""
+
     pass
 
 
@@ -42,7 +47,7 @@ def run_mc_command(
     """Run minio/mc command in ephemeral container.
 
     The volume is mounted at /data in the container.
-    
+
     Raises:
         DatabaseError: If Docker operation fails
     """
@@ -54,7 +59,7 @@ def run_mc_command(
 
     try:
         client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
-        
+
         return run_container(
             client=client,
             image="minio/mc:latest",
@@ -82,7 +87,7 @@ def backup_database(
     s3_secret_key: str | None,
 ) -> None:
     """Backup database using pg_dump via exec, then optionally upload to S3 with mc.
-    
+
     Raises:
         DatabaseError: If backup fails
     """
@@ -101,13 +106,15 @@ def backup_database(
     # Step 1: Run pg_dump inside the database container
     click.echo("  Running pg_dump...")
     cmd = f"pg_dump -U {db_user} {db_name} | gzip > {backup_file} && stat -c %s {backup_file}"
-    
+
     try:
         exit_code, output_stream = container.exec_run(
             ["sh", "-c", cmd],
             demux=False,
         )
-        output_text = output_stream.decode("utf-8", errors="replace") if output_stream else ""
+        output_text = (
+            output_stream.decode("utf-8", errors="replace") if output_stream else ""
+        )
     except docker.errors.APIError as e:
         click.echo(f"  ✗ pg_dump failed: {e}")
         raise DatabaseError(f"pg_dump failed: {e}") from e
@@ -142,7 +149,9 @@ def backup_database(
 
         if not s3_access_key or not s3_secret_key:
             click.echo("  ✗ S3 credentials required (S3_ACCESS_KEY, S3_SECRET_KEY)")
-            raise DatabaseError("S3 credentials required (S3_ACCESS_KEY, S3_SECRET_KEY)")
+            raise DatabaseError(
+                "S3 credentials required (S3_ACCESS_KEY, S3_SECRET_KEY)"
+            )
 
         click.echo(f"  Uploading to S3: s3://{bucket}/{s3_path}...")
 
@@ -179,14 +188,18 @@ def backup_database(
                 ["sh", "-c", f"base64 {backup_file}"],
                 demux=False,
             )
-            b64_content = b64_output.decode("utf-8", errors="replace") if b64_output else ""
+            b64_content = (
+                b64_output.decode("utf-8", errors="replace") if b64_output else ""
+            )
         except docker.errors.APIError as e:
             click.echo("  ✗ Failed to read backup file from container")
             raise DatabaseError("Failed to read backup file from container") from e
 
         if read_exit_code != 0:
             click.echo(f"  ✗ Failed to read backup file: exit code {read_exit_code}")
-            raise DatabaseError(f"Failed to read backup file: exit code {read_exit_code}")
+            raise DatabaseError(
+                f"Failed to read backup file: exit code {read_exit_code}"
+            )
 
         # Decode and save to output file
         import base64
@@ -227,7 +240,7 @@ def restore_database(
     s3_secret_key: str | None,
 ) -> None:
     """Restore database from local file or S3.
-    
+
     Raises:
         DatabaseError: If restore fails
     """
@@ -260,7 +273,9 @@ def restore_database(
 
         if not s3_access_key or not s3_secret_key:
             click.echo("  ✗ S3 credentials required (S3_ACCESS_KEY, S3_SECRET_KEY)")
-            raise DatabaseError("S3 credentials required (S3_ACCESS_KEY, S3_SECRET_KEY)")
+            raise DatabaseError(
+                "S3 credentials required (S3_ACCESS_KEY, S3_SECRET_KEY)"
+            )
 
         click.echo(f"  Downloading from S3: s3://{bucket}/{s3_path}...")
 
@@ -322,7 +337,9 @@ def restore_database(
 
         if write_exit_code != 0:
             click.echo(f"  ✗ Failed to write backup file: exit code {write_exit_code}")
-            raise DatabaseError(f"Failed to write backup file: exit code {write_exit_code}")
+            raise DatabaseError(
+                f"Failed to write backup file: exit code {write_exit_code}"
+            )
 
         # Append remaining chunks
         for chunk in chunks[1:]:
@@ -350,7 +367,9 @@ def restore_database(
             ["sh", "-c", psql_cmd],
             demux=False,
         )
-        output = output_stream.decode("utf-8", errors="replace") if output_stream else ""
+        output = (
+            output_stream.decode("utf-8", errors="replace") if output_stream else ""
+        )
     except docker.errors.APIError as e:
         click.echo(f"  ✗ Restore failed: {e}")
         raise DatabaseError(f"Restore failed: {e}") from e
@@ -381,7 +400,13 @@ def cli():
 
 
 @cli.command()
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--container-id", "-c", required=True, help="Database container ID")
 @click.option(
     "--volume-name", "-v", required=True, help="Volume name where database stores data"
@@ -417,9 +442,9 @@ def backup(
     """Backup PostgreSQL database to local file or S3.
 
     Examples:
-        ptctools db backup -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -o /tmp/backup.sql.gz
+        ptctools docker db backup -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -o /tmp/backup.sql.gz
 
-        ptctools db backup -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -o s3://mybucket/backups/backup.sql.gz --s3-endpoint https://s3.<region>.amazonaws.com
+        ptctools docker db backup -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -o s3://mybucket/backups/backup.sql.gz --s3-endpoint https://s3.<region>.amazonaws.com
     """
     access_token = os.environ.get("PORTAINER_ACCESS_TOKEN")
     if not access_token:
@@ -477,7 +502,13 @@ def backup(
 
 
 @cli.command()
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--container-id", "-c", required=True, help="Database container ID")
 @click.option(
     "--volume-name", "-v", required=True, help="Volume name where database stores data"
@@ -514,9 +545,9 @@ def restore(
     """Restore PostgreSQL database from local file or S3.
 
     Examples:
-        ptctools db restore -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -i /tmp/backup.sql.gz
+        ptctools docker db restore -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -i /tmp/backup.sql.gz
 
-        ptctools db restore -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -i s3://mybucket/backups/backup.sql.gz --s3-endpoint https://s3.<region>.amazonaws.com
+        ptctools docker db restore -u https://portainer.example.com -c abc123 -v db_data --db-user postgres --db-name mydb -i s3://mybucket/backups/backup.sql.gz --s3-endpoint https://s3.<region>.amazonaws.com
     """
     access_token = os.environ.get("PORTAINER_ACCESS_TOKEN")
     if not access_token:

ptctools/docker.py

@@ -0,0 +1,29 @@
+"""Docker management commands (via Portainer Docker proxy)."""
+
+import click
+
+from ptctools import stack
+from ptctools import secret
+from ptctools import config
+from ptctools import volume
+from ptctools import db
+
+
+@click.group()
+def cli():
+    """Docker management commands.
+
+    These commands work with Docker environments via Portainer.
+    Some commands (stack, secret, config) require Docker Swarm.
+    """
+    pass
+
+
+# Swarm-only commands
+cli.add_command(stack.cli, name="stack")
+cli.add_command(secret.cli, name="secret")
+cli.add_command(config.cli, name="config")
+
+# Any Docker commands
+cli.add_command(volume.cli, name="volume")
+cli.add_command(db.cli, name="db")

ptctools/secret.py

@@ -0,0 +1,146 @@
+"""Secret management commands."""
+
+from __future__ import annotations
+
+import base64
+import os
+import sys
+from pathlib import Path
+
+import click
+import docker.errors
+
+from ptctools._portainer import (
+    get_portainer_docker_client,
+    PortainerError,
+)
+
+
+class SecretError(PortainerError):
+    """Exception for secret operations."""
+
+    pass
+
+
+@click.group()
+def cli():
+    """Secret management commands."""
+    pass
+
+
+@cli.command()
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
+@click.option("--endpoint-id", "-e", type=int, default=1, help="Portainer endpoint ID")
+@click.option(
+    "--file",
+    "-f",
+    "file_path",
+    type=click.Path(exists=True, path_type=Path),
+    help="Read secret from file",
+)
+@click.option(
+    "--value", "-v", help="Secret value (use stdin or --file for sensitive data)"
+)
+@click.argument("name")
+def create(
+    url: str,
+    endpoint_id: int,
+    file_path: Path | None,
+    value: str | None,
+    name: str,
+):
+    """Create a Docker Swarm secret.
+
+    NAME is the name of the secret to create.
+
+    The secret value can be provided via:
+    - stdin: echo "secret" | ptctools docker secret create -u URL my_secret
+    - file: ptctools docker secret create -u URL -f /path/to/file my_secret
+    - value: ptctools docker secret create -u URL -v "secret" my_secret
+
+    Example:
+        echo "postgresql://user:pass@db:5432/mydb" | ptctools docker secret create -u https://portainer.example.com litellm_db_dsn
+    """
+    access_token = os.environ.get("PORTAINER_ACCESS_TOKEN")
+    if not access_token:
+        click.echo(
+            "Error: Missing PORTAINER_ACCESS_TOKEN environment variable", err=True
+        )
+        sys.exit(1)
+
+    # Determine secret data source
+    secret_data: bytes | None = None
+
+    if file_path:
+        # Read from file
+        secret_data = file_path.read_bytes()
+    elif value:
+        # Use provided value
+        secret_data = value.encode("utf-8")
+    elif not sys.stdin.isatty():
+        # Read from stdin
+        secret_data = sys.stdin.read().encode("utf-8")
+    else:
+        click.echo(
+            "Error: Secret value required. Use --file, --value, or pipe via stdin.",
+            err=True,
+        )
+        sys.exit(1)
+
+    # Strip trailing newline if present (common when piping from echo)
+    if secret_data.endswith(b"\n"):
+        secret_data = secret_data.rstrip(b"\n")
+
+    portainer_url = url.rstrip("/")
+
+    click.echo(f"Portainer URL: {portainer_url}")
+    click.echo(f"Endpoint ID: {endpoint_id}")
+    click.echo(f"Secret Name: {name}")
+    click.echo()
+
+    try:
+        docker_client = get_portainer_docker_client(
+            portainer_url, access_token, endpoint_id
+        )
+
+        # Check if secret already exists
+        try:
+            existing = docker_client.secrets.get(name)
+            click.echo(
+                f"Error: Secret '{name}' already exists (ID: {existing.id[:12]})",
+                err=True,
+            )
+            click.echo(
+                "Use 'docker secret rm' to remove it first, or choose a different name.",
+                err=True,
+            )
+            sys.exit(1)
+        except docker.errors.NotFound:
+            pass  # Good, secret doesn't exist
+
+        # Create the secret
+        click.echo(f"Creating secret '{name}'...")
+        secret = docker_client.secrets.create(name=name, data=secret_data)
+        click.echo(f"Secret created successfully!")
+        click.echo(f"  ID: {secret.id}")
+        click.echo(f"  Name: {name}")
+        click.echo()
+        click.echo("Done!")
+        sys.exit(0)
+
+    except docker.errors.APIError as e:
+        click.echo(f"Error: {e.explanation or str(e)}", err=True)
+        click.echo()
+        click.echo("Failed!")
+        sys.exit(1)
+    except SecretError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo()
+        click.echo("Failed!")
+        sys.exit(1)

ptctools/stack.py

@@ -19,12 +19,24 @@ from ptctools._portainer import (
 )
 from ptctools.portainer_client.openapi_client.api.stacks_api import StacksApi
 from ptctools.portainer_client.openapi_client.api.users_api import UsersApi
-from ptctools.portainer_client.openapi_client.api.resource_controls_api import ResourceControlsApi
-from ptctools.portainer_client.openapi_client.models.stacks_swarm_stack_from_file_content_payload import StacksSwarmStackFromFileContentPayload
-from ptctools.portainer_client.openapi_client.models.stacks_update_swarm_stack_payload import StacksUpdateSwarmStackPayload
-from ptctools.portainer_client.openapi_client.models.resourcecontrols_resource_control_create_payload import ResourcecontrolsResourceControlCreatePayload
-from ptctools.portainer_client.openapi_client.models.resourcecontrols_resource_control_update_payload import ResourcecontrolsResourceControlUpdatePayload
-from ptctools.portainer_client.openapi_client.models.portainer_resource_control_type import PortainerResourceControlType
+from ptctools.portainer_client.openapi_client.api.resource_controls_api import (
+    ResourceControlsApi,
+)
+from ptctools.portainer_client.openapi_client.models.stacks_swarm_stack_from_file_content_payload import (
+    StacksSwarmStackFromFileContentPayload,
+)
+from ptctools.portainer_client.openapi_client.models.stacks_update_swarm_stack_payload import (
+    StacksUpdateSwarmStackPayload,
+)
+from ptctools.portainer_client.openapi_client.models.resourcecontrols_resource_control_create_payload import (
+    ResourcecontrolsResourceControlCreatePayload,
+)
+from ptctools.portainer_client.openapi_client.models.resourcecontrols_resource_control_update_payload import (
+    ResourcecontrolsResourceControlUpdatePayload,
+)
+from ptctools.portainer_client.openapi_client.models.portainer_resource_control_type import (
+    PortainerResourceControlType,
+)
 from ptctools.portainer_client.openapi_client.exceptions import ApiException
 
 logger = logging.getLogger(__name__)
@@ -32,6 +44,7 @@ logger = logging.getLogger(__name__)
 
 class StackError(PortainerError):
     """Exception for stack operations."""
+
     pass
 
 
@@ -63,7 +76,13 @@ def cli():
 
 
 @cli.command()
-@click.option("--url", "-u", required=True, help="Portainer base URL")
+@click.option(
+    "--url",
+    "-u",
+    envvar="PORTAINER_URL",
+    required=True,
+    help="Portainer base URL (or PORTAINER_URL env var)",
+)
 @click.option("--stack-name", "-n", required=True, help="Stack name")
 @click.option(
     "--stack-file",
@@ -113,11 +132,15 @@ def deploy(
                 user_teams = []
                 for m in memberships:
                     if m.team_id:
-                        user_teams.append({"Id": m.team_id, "Name": f"Team {m.team_id}"})
-                
+                        user_teams.append(
+                            {"Id": m.team_id, "Name": f"Team {m.team_id}"}
+                        )
+
                 if user_teams:
                     team_id = user_teams[0]["Id"]
-                    click.echo(f"Auto-detected team: {user_teams[0]['Name']} (ID: {team_id})")
+                    click.echo(
+                        f"Auto-detected team: {user_teams[0]['Name']} (ID: {team_id})"
+                    )
                 else:
                     click.echo(
                         "Error: ownership=team but no team found and --team-id not specified",
@@ -160,7 +183,9 @@ def deploy(
 
             if existing_stack_id is not None:
                 # Update existing stack
-                click.echo(f"Updating existing stack: {stack_name} (ID: {existing_stack_id})...")
+                click.echo(
+                    f"Updating existing stack: {stack_name} (ID: {existing_stack_id})..."
+                )
                 payload = StacksUpdateSwarmStackPayload(
                     stack_file_content=stack_content,
                     env=env_vars,
@@ -168,14 +193,18 @@ def deploy(
                     pull_image=True,
                 )
                 response = stacks_api.stack_update(
-                    id=existing_stack_id, endpoint_id=endpoint_id, body=payload.to_dict()
+                    id=existing_stack_id,
+                    endpoint_id=endpoint_id,
+                    body=payload.to_dict(),
                 )
                 click.echo("Stack updated successfully!")
                 click.echo(json.dumps(response.to_dict(), indent=2))
             else:
                 # Create new stack - need swarm ID first
                 click.echo("Getting swarm ID...")
-                docker_client = get_portainer_docker_client(portainer_url, access_token, endpoint_id)
+                docker_client = get_portainer_docker_client(
+                    portainer_url, access_token, endpoint_id
+                )
                 swarm_info = docker_client.swarm.attrs
                 swarm_id = swarm_info.get("ID") if swarm_info else None
                 if not swarm_id:
@@ -198,7 +227,7 @@ def deploy(
             # Apply access control
             if ownership:
                 click.echo()
-                
+
                 # Get final stack ID
                 final_stack_id = None
                 stacks = stacks_api.stack_list()
@@ -221,7 +250,9 @@ def deploy(
                                 teams=[],
                                 users=[user_id],
                             )
-                            rc_api.resource_control_update(id=rc.id, body=rc_payload.to_dict())
+                            rc_api.resource_control_update(
+                                id=rc.id, body=rc_payload.to_dict()
+                            )
                             click.echo("✓ Access control set to private")
 
                     elif ownership == "team" and team_id:
@@ -232,7 +263,9 @@ def deploy(
                                 teams=[team_id],
                                 users=[],
                             )
-                            rc_api.resource_control_update(id=rc.id, body=rc_payload.to_dict())
+                            rc_api.resource_control_update(
+                                id=rc.id, body=rc_payload.to_dict()
+                            )
                             click.echo(f"✓ Access control set to team {team_id}")
                         else:
                             rc_payload = ResourcecontrolsResourceControlCreatePayload(
@@ -253,7 +286,9 @@ def deploy(
                                 teams=[],
                                 users=[],
                             )
-                            rc_api.resource_control_update(id=rc.id, body=rc_payload.to_dict())
+                            rc_api.resource_control_update(
+                                id=rc.id, body=rc_payload.to_dict()
+                            )
                             click.echo("✓ Access control set to public")
                         else:
                             rc_payload = ResourcecontrolsResourceControlCreatePayload(
@@ -272,7 +307,9 @@ def deploy(
 
     except ApiException as e:
         error_msg = str(e.body) if e.body else str(e.reason)
-        logger.error("Stack operation failed: %s\n%s", error_msg, traceback.format_exc())
+        logger.error(
+            "Stack operation failed: %s\n%s", error_msg, traceback.format_exc()
+        )
         click.echo(f"Error: {error_msg}", err=True)
         click.echo()
         click.echo("Failed!")