secretctl-cli 0.1.0__py3-none-any.whl

secretctl/__init__.py

@@ -0,0 +1,3 @@
+"""secretctl - Cross-platform secret storage CLI for AI agents."""
+
+__version__ = "0.1.0"

secretctl/backend.py

@@ -0,0 +1,176 @@
+"""Backend implementations for secret storage."""
+
+import platform
+import subprocess
+from abc import ABC, abstractmethod
+
+
+class SecretBackend(ABC):
+    """Abstract base class for secret storage backends."""
+
+    def __init__(self, account: str):
+        self.account = account
+
+    @abstractmethod
+    def get(self, name: str) -> str | None:
+        """Get a secret value."""
+        pass
+
+    @abstractmethod
+    def set(self, name: str, value: str) -> None:
+        """Set a secret value."""
+        pass
+
+    @abstractmethod
+    def delete(self, name: str) -> None:
+        """Delete a secret."""
+        pass
+
+    @abstractmethod
+    def list(self) -> list[str]:
+        """List all secret names."""
+        pass
+
+
+class MacOSKeychain(SecretBackend):
+    """macOS Keychain backend using security command."""
+
+    def get(self, name: str) -> str | None:
+        """Get a secret from macOS Keychain."""
+        try:
+            result = subprocess.run(
+                [
+                    "security",
+                    "find-generic-password",
+                    "-a", self.account,
+                    "-s", name,
+                    "-w",
+                ],
+                capture_output=True,
+                text=True,
+            )
+            if result.returncode == 0:
+                return result.stdout.strip()
+            return None
+        except Exception:
+            return None
+
+    def set(self, name: str, value: str) -> None:
+        """Set a secret in macOS Keychain."""
+        # Delete existing first (security doesn't update in place)
+        subprocess.run(
+            [
+                "security",
+                "delete-generic-password",
+                "-a", self.account,
+                "-s", name,
+            ],
+            capture_output=True,
+        )
+        # Add new
+        result = subprocess.run(
+            [
+                "security",
+                "add-generic-password",
+                "-a", self.account,
+                "-s", name,
+                "-w", value,
+                "-U",  # Update if exists
+            ],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"Failed to store secret: {result.stderr}")
+
+    def delete(self, name: str) -> None:
+        """Delete a secret from macOS Keychain."""
+        result = subprocess.run(
+            [
+                "security",
+                "delete-generic-password",
+                "-a", self.account,
+                "-s", name,
+            ],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0 and "could not be found" not in result.stderr:
+            raise RuntimeError(f"Failed to delete secret: {result.stderr}")
+
+    def list(self) -> list[str]:
+        """List all secrets for this account in macOS Keychain."""
+        result = subprocess.run(
+            ["security", "dump-keychain"],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode != 0:
+            return []
+
+        secrets = []
+        current_account = None
+        current_service = None
+
+        for line in result.stdout.splitlines():
+            line = line.strip()
+            if '"acct"' in line and f'"{self.account}"' in line:
+                current_account = self.account
+            elif '"svce"' in line and current_account:
+                # Extract service name
+                # Format: "svce"<blob>="service_name"
+                if '="' in line:
+                    current_service = line.split('="')[1].rstrip('"')
+                    secrets.append(current_service)
+                    current_account = None
+                    current_service = None
+
+        return list(set(secrets))  # Deduplicate
+
+
+class LinuxKeyring(SecretBackend):
+    """Linux keyring backend using the keyring library."""
+
+    def __init__(self, account: str):
+        super().__init__(account)
+        try:
+            import keyring
+            self.keyring = keyring
+        except ImportError:
+            raise RuntimeError(
+                "keyring library required on Linux. "
+                "Install with: pip install secretctl[linux]"
+            )
+
+    def get(self, name: str) -> str | None:
+        """Get a secret from Linux keyring."""
+        return self.keyring.get_password(self.account, name)
+
+    def set(self, name: str, value: str) -> None:
+        """Set a secret in Linux keyring."""
+        self.keyring.set_password(self.account, name, value)
+
+    def delete(self, name: str) -> None:
+        """Delete a secret from Linux keyring."""
+        try:
+            self.keyring.delete_password(self.account, name)
+        except self.keyring.errors.PasswordDeleteError:
+            pass  # Already deleted or doesn't exist
+
+    def list(self) -> list[str]:
+        """List all secrets (not easily supported on Linux keyring)."""
+        # Linux keyring doesn't have a native list function
+        # This is a limitation - users need to track their own keys
+        return []
+
+
+def get_backend(account: str) -> SecretBackend:
+    """Get the appropriate backend for the current platform."""
+    system = platform.system()
+    
+    if system == "Darwin":
+        return MacOSKeychain(account)
+    elif system == "Linux":
+        return LinuxKeyring(account)
+    else:
+        raise RuntimeError(f"Unsupported platform: {system}")

secretctl/cli.py

@@ -0,0 +1,230 @@
+"""Main CLI entry point for secretctl."""
+
+import json
+import sys
+import click
+
+from . import __version__
+from .backend import get_backend
+
+
+class Context:
+    """Shared context for all commands."""
+
+    def __init__(self, json_output: bool = False, account: str = "secretctl"):
+        self.json_output = json_output
+        self.account = account
+        self.backend = get_backend(account)
+
+    def output(self, data: dict | list | str, success: bool = True):
+        """Output data in the appropriate format."""
+        if self.json_output:
+            if isinstance(data, str):
+                data = {"message": data, "success": success}
+            elif isinstance(data, dict) and "success" not in data:
+                data = {**data, "success": success}
+            click.echo(json.dumps(data, indent=2))
+        else:
+            if isinstance(data, dict):
+                for key, value in data.items():
+                    if key != "success":
+                        click.echo(f"{key}: {value}")
+            elif isinstance(data, list):
+                for item in data:
+                    click.echo(item)
+            else:
+                click.echo(data)
+
+    def error(self, message: str, exit_code: int = 1):
+        """Output an error message and exit."""
+        if self.json_output:
+            click.echo(json.dumps({"error": message, "success": False}))
+        else:
+            click.echo(f"Error: {message}", err=True)
+        sys.exit(exit_code)
+
+
+pass_context = click.make_pass_decorator(Context, ensure=True)
+
+
+@click.group()
+@click.option("--json", "json_output", is_flag=True, help="Output in JSON format")
+@click.option("--account", "-a", default="secretctl", help="Account/namespace for secrets")
+@click.version_option(version=__version__, prog_name="secretctl")
+@click.pass_context
+def main(ctx, json_output: bool, account: str):
+    """Cross-platform secret storage CLI for AI agents.
+
+    Store and retrieve secrets from the OS keychain without cloud sync
+    or biometrics. Designed for automation and AI agent workflows.
+
+    Examples:
+        secretctl set API_KEY sk-xxx
+        secretctl get API_KEY
+        secretctl list
+    """
+    ctx.obj = Context(json_output=json_output, account=account)
+
+
+@main.command()
+@click.argument("name")
+@click.argument("value")
+@pass_context
+def set(ctx, name: str, value: str):
+    """Store a secret.
+
+    Example:
+        secretctl set API_KEY sk-xxx123
+        secretctl set DATABASE_URL "postgres://user:pass@host/db"
+    """
+    try:
+        ctx.backend.set(name, value)
+        ctx.output({"name": name, "stored": True, "account": ctx.account})
+    except Exception as e:
+        ctx.error(f"Failed to store secret: {e}")
+
+
+@main.command()
+@click.argument("name")
+@pass_context
+def get(ctx, name: str):
+    """Retrieve a secret.
+
+    Example:
+        secretctl get API_KEY
+    """
+    try:
+        value = ctx.backend.get(name)
+        if value is None:
+            ctx.error(f"Secret not found: {name}")
+        ctx.output({"name": name, "value": value})
+    except Exception as e:
+        ctx.error(f"Failed to retrieve secret: {e}")
+
+
+@main.command()
+@click.argument("name")
+@pass_context
+def delete(ctx, name: str):
+    """Delete a secret.
+
+    Example:
+        secretctl delete API_KEY
+    """
+    try:
+        ctx.backend.delete(name)
+        ctx.output({"name": name, "deleted": True})
+    except Exception as e:
+        ctx.error(f"Failed to delete secret: {e}")
+
+
+@main.command("list")
+@pass_context
+def list_secrets(ctx):
+    """List all secret names (values hidden).
+
+    Example:
+        secretctl list
+    """
+    try:
+        secrets = ctx.backend.list()
+        ctx.output({"secrets": secrets, "count": len(secrets), "account": ctx.account})
+    except Exception as e:
+        ctx.error(f"Failed to list secrets: {e}")
+
+
+@main.command()
+@click.argument("name")
+@pass_context
+def exists(ctx, name: str):
+    """Check if a secret exists.
+
+    Example:
+        secretctl exists API_KEY
+    """
+    try:
+        value = ctx.backend.get(name)
+        exists = value is not None
+        ctx.output({"name": name, "exists": exists})
+    except Exception as e:
+        ctx.error(f"Failed to check secret: {e}")
+
+
+@main.command()
+@click.option("--file", "-f", "output_file", help="Output file (default: stdout)")
+@click.option("--format", "fmt", type=click.Choice(["env", "json"]), default="env", help="Export format")
+@pass_context
+def export(ctx, output_file: str | None, fmt: str):
+    """Export all secrets.
+
+    Example:
+        secretctl export > secrets.env
+        secretctl export --format json > secrets.json
+    """
+    try:
+        secrets = ctx.backend.list()
+        data = {}
+        for name in secrets:
+            value = ctx.backend.get(name)
+            if value:
+                data[name] = value
+
+        if fmt == "json":
+            output = json.dumps(data, indent=2)
+        else:  # env format
+            output = "\n".join(f'{k}="{v}"' for k, v in data.items())
+
+        if output_file:
+            with open(output_file, "w") as f:
+                f.write(output)
+            ctx.output({"exported": len(data), "file": output_file, "format": fmt})
+        else:
+            click.echo(output)
+    except Exception as e:
+        ctx.error(f"Failed to export secrets: {e}")
+
+
+@main.command("import")
+@click.argument("input_file", type=click.Path(exists=True))
+@click.option("--format", "fmt", type=click.Choice(["env", "json"]), default="env", help="Import format")
+@click.option("--overwrite", is_flag=True, help="Overwrite existing secrets")
+@pass_context
+def import_secrets(ctx, input_file: str, fmt: str, overwrite: bool):
+    """Import secrets from file.
+
+    Example:
+        secretctl import secrets.env
+        secretctl import secrets.json --format json --overwrite
+    """
+    try:
+        with open(input_file, "r") as f:
+            content = f.read()
+
+        if fmt == "json":
+            data = json.loads(content)
+        else:  # env format
+            data = {}
+            for line in content.splitlines():
+                line = line.strip()
+                if line and not line.startswith("#") and "=" in line:
+                    key, value = line.split("=", 1)
+                    # Strip quotes if present
+                    value = value.strip().strip('"').strip("'")
+                    data[key.strip()] = value
+
+        imported = 0
+        skipped = 0
+        for name, value in data.items():
+            if not overwrite and ctx.backend.get(name) is not None:
+                skipped += 1
+                continue
+            ctx.backend.set(name, value)
+            imported += 1
+
+        ctx.output({"imported": imported, "skipped": skipped, "file": input_file})
+    except Exception as e:
+        ctx.error(f"Failed to import secrets: {e}")
+
+
+if __name__ == "__main__":
+    main()

secretctl_cli-0.1.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: secretctl-cli
+Version: 0.1.0
+Summary: Cross-platform secret storage CLI for AI agents
+Project-URL: Homepage, https://github.com/marcusbuildsthings-droid/secretctl
+Project-URL: Repository, https://github.com/marcusbuildsthings-droid/secretctl
+Author-email: Marcus <marcus.builds.things@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,cli,credentials,keychain,secrets
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+Provides-Extra: linux
+Requires-Dist: keyring>=24.0; extra == 'linux'
+Description-Content-Type: text/markdown
+
+# secretctl
+
+Cross-platform secret storage CLI for AI agents and developers. Store secrets in the OS keychain without cloud sync or biometrics.
+
+## Installation
+
+```bash
+pip install secretctl
+```
+
+On Linux, install with keyring support:
+```bash
+pip install secretctl[linux]
+```
+
+## Quick Start
+
+```bash
+# Store a secret
+secretctl set API_KEY sk-xxx123
+
+# Retrieve a secret
+secretctl get API_KEY
+
+# List all secrets
+secretctl list
+
+# Delete a secret
+secretctl delete API_KEY
+```
+
+## Commands
+
+### Basic Operations
+
+```bash
+secretctl set <name> <value>     # Store a secret
+secretctl get <name>             # Retrieve a secret
+secretctl delete <name>          # Delete a secret
+secretctl list                   # List all secret names
+secretctl exists <name>          # Check if secret exists
+```
+
+### Import/Export
+
+```bash
+# Export to env file
+secretctl export > secrets.env
+secretctl export --format json > secrets.json
+
+# Import from file
+secretctl import secrets.env
+secretctl import secrets.json --format json
+secretctl import secrets.env --overwrite  # Replace existing
+```
+
+### Namespaces
+
+Use different accounts/namespaces to organize secrets:
+
+```bash
+secretctl --account myapp set DB_URL "postgres://..."
+secretctl --account myapp list
+```
+
+## JSON Output
+
+All commands support `--json` for machine-readable output:
+
+```bash
+secretctl --json get API_KEY
+```
+
+```json
+{
+  "name": "API_KEY",
+  "value": "sk-xxx123",
+  "success": true
+}
+```
+
+## Platform Support
+
+| Platform | Backend | Notes |
+|----------|---------|-------|
+| macOS | Keychain | Uses `security` command |
+| Linux | keyring | Requires `secretctl[linux]` |
+
+## For AI Agents
+
+See [SKILL.md](SKILL.md) for agent-optimized documentation.
+
+## Why secretctl?
+
+- **No cloud sync** - Secrets stay local
+- **No biometrics** - Works in automation/CI
+- **Simple CLI** - Easy for agents to use
+- **JSON output** - Machine-readable
+- **Namespaced** - Multiple accounts/apps
+
+## License
+
+MIT

secretctl_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+secretctl/__init__.py,sha256=tk1IHS0BHdVrKCQFraLrU7t8Av-rGOfG3JMneM1KAp4,90
+secretctl/backend.py,sha256=Sz4O_wrK-GrEgoIpH5cz9LaWKlbJf9wSk-bYmCyKdLs,5409
+secretctl/cli.py,sha256=N5Rc8HYnfnyV-TmnJGlezWitFJtTlMvdJvcbZ8mWe4A,6833
+secretctl_cli-0.1.0.dist-info/METADATA,sha256=ysNLdte-0x5NUrbNbK3Pk21YOXCt75GLIn7DfzjLCKg,3019
+secretctl_cli-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+secretctl_cli-0.1.0.dist-info/entry_points.txt,sha256=piuuz-chGYfMG9c1FhvDPP4dVZ_d2doAPcq_e7O6i5U,49
+secretctl_cli-0.1.0.dist-info/licenses/LICENSE,sha256=9tNBpWq8KGbuJqmeComp40OiNnbvpvsKn1YP26PUtck,1063
+secretctl_cli-0.1.0.dist-info/RECORD,,

secretctl_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

secretctl_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+secretctl = secretctl.cli:main

secretctl_cli-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.