kctl-op 0.5.0__tar.gz

kctl_op-0.5.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local

kctl_op-0.5.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: kctl-op
+Version: 0.5.0
+Summary: Kodemeio 1Password CLI — secret management and .env sync
+Requires-Python: >=3.12
+Requires-Dist: kctl-lib>=0.5.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.15.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.35.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'

kctl_op-0.5.0/README.md

@@ -0,0 +1,74 @@
+# kctl-op
+
+Kodemeio 1Password CLI — secret management and .env sync across all projects.
+
+## Installation
+
+```bash
+uv tool install .
+```
+
+## Quick Start
+
+```bash
+kctl-op config init
+kctl-op health
+kctl-op vault list
+kctl-op sync pull
+```
+
+## Command Groups
+
+| Group | Description |
+|-------|-------------|
+| `config` | Manage CLI configuration and profiles |
+| `health` | Health checks and diagnostics |
+| `vault` | Vault management operations |
+| `projects` | Project discovery and status |
+| `push` | Push .env files to 1Password |
+| `pull` | Pull secrets from 1Password to .env |
+| `diff` | Show differences between local and 1Password |
+| `discover` | Discover .env files in project directories |
+| `backup` | Backup management for .env files |
+| `status` | Check sync status |
+
+Top-level commands: `list` (list all vault items)
+
+## Configuration
+
+Config lives in `~/.config/kodemeio/config.yaml` under the `op` service key.
+
+```bash
+# Initialize a profile
+kctl-op config init
+
+# Add a named profile
+kctl-op config add prod --vault MyVault --token $OP_SERVICE_ACCOUNT_TOKEN
+
+# Switch active profile
+kctl-op config use prod
+
+# Show current profile (token masked)
+kctl-op config show
+```
+
+## Global Options
+
+| Option | Short | Description |
+|--------|-------|-------------|
+| `--json` | | Output as JSON |
+| `--quiet` | `-q` | Suppress non-essential output |
+| `--format` | `-f` | Output format: pretty, json, csv, yaml |
+| `--no-header` | | Omit header row in CSV output |
+| `--profile` | `-p` | Config profile to use |
+| `--vault` | | Override vault name |
+| `--token` | | Override service account token |
+| `--version` | `-V` | Show version and exit |
+
+## Development
+
+```bash
+uv run pytest tests/ -v
+uv run ruff check src/
+uv run mypy src/
+```

kctl_op-0.5.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-op"
+version = "0.5.0"
+description = "Kodemeio 1Password CLI — secret management and .env sync"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.5.0",
+    "typer>=0.15.0",
+    "rich>=13.9.0",
+    "pydantic>=2.10.0",
+    "pyyaml>=6.0.2",
+    "python-dotenv>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.3.0",
+    "pytest-httpx>=0.35.0",
+    "ruff>=0.9.0",
+    "mypy>=1.14.0",
+    "types-PyYAML>=6.0.0",
+]
+
+[project.scripts]
+kctl-op = "kctl_op.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+
+[project.entry-points."kctl_op.plugins"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_op"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+
+[tool.mypy]
+python_version = "3.12"
+strict = true

kctl_op-0.5.0/skills/1password-admin/SKILL.md

@@ -0,0 +1,141 @@
+---
+name: 1password-admin
+description: >
+  1Password secret management via kctl-op CLI (12 groups, ~27 commands).
+  MUST use for ANY kctl-op operation.
+  Triggers on: "backup", "check", "clean", "config", "current", "dashboard", "diff", "discover", "envs", "generate", "health", "info", "init", "items", "kctl-op", "list", "migrate", "profile", "profiles", "projects", "pull", "push", "remove", "restore", "skill", "status", "test", "vault".
+  Auto-generated: 2026-04-05
+  registry_hash: d1005426c491
+---
+
+# 1password-admin — kctl-op CLI Reference
+
+> Auto-generated from `kctl-op` command registry. Do not edit manually.
+> To regenerate: `kctl-op skill generate`
+> To add custom content: edit `SKILL.extra.md` in the same directory.
+
+## Overview
+
+**CLI:** `kctl-op`
+**Command groups:** 12
+**Total commands:** ~27
+**Install:** `cd cli && uv tool install --editable .`
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `--json` | JSON output |
+| `--quiet`, `-q` | Suppress info messages |
+| `--format`, `-f` | Output format: pretty/json/csv/yaml |
+| `--no-header` | Omit CSV header row |
+| `--profile`, `-p` | Config profile name |
+| `--version`, `-V` | Show version |
+
+## Command Reference
+
+### `kctl-op backup`
+
+Backup management for .env files.
+
+| Command | Description |
+|---------|-------------|
+| `backup clean [--keep] [--force]` | Clean old backups, keeping the N most recent per file. |
+| `backup list [--project]` | List available backups. |
+| `backup restore <project> <environment> [--timestamp] [--force]` | Restore a .env file from backup. |
+
+### `kctl-op config`
+
+Manage CLI configuration and profiles.
+
+| Command | Description |
+|---------|-------------|
+| `config add <name> [--vault] [--token] [--scan_root]` | Add a new profile. |
+| `config current` | Show current active profile. |
+| `config init [--vault] [--token] [--name] [--scan_root]` | Initialize CLI configuration (interactive if no flags given). |
+| `config migrate` | Migrate legacy configuration to service-scoped format. |
+| `config profiles` | List all profiles. |
+| `config remove <name> [--force]` | Remove a profile's 1Password configuration. |
+| `config set <key> <value>` | Set a configuration value in the current profile. |
+| `config show` | Show full configuration (tokens masked). |
+| `config test` | Test current profile's 1Password connection. |
+| `config use <name>` | Set the default profile. |
+
+### `kctl-op diff`
+
+Show differences between local and 1Password.
+
+### `kctl-op discover`
+
+Discover .env files.
+
+### `kctl-op health`
+
+Health checks and diagnostics.
+
+| Command | Description |
+|---------|-------------|
+| `health dashboard` | Overview: projects, files, sync status, last sync times. |
+
+### `kctl-op list`
+
+List all items in the 1Password vault.
+
+### `kctl-op projects`
+
+Project discovery and status.
+
+| Command | Description |
+|---------|-------------|
+| `projects envs <project>` | List all .env files for a project. |
+| `projects list` | List all projects found across scan roots. |
+| `projects status <project>` | Show sync status for all environments in a project. |
+
+### `kctl-op pull`
+
+Pull .env files from 1Password.
+
+### `kctl-op push`
+
+Push .env files to 1Password.
+
+### `kctl-op skill`
+
+Claude Code skill management.
+
+| Command | Description |
+|---------|-------------|
+| `skill generate [--output] [--install] [--check]` | Auto-generate SKILL.md from CLI command registry. |
+
+**Examples:**
+```bash
+kctl-op skill generate
+kctl-op skill generate --install
+kctl-op skill generate --check
+```
+
+### `kctl-op status`
+
+Check sync status.
+
+### `kctl-op vault`
+
+Vault management operations.
+
+| Command | Description |
+|---------|-------------|
+| `vault create [--name] [--description]` | Create a new 1Password vault. |
+| `vault info` | Show vault details. |
+| `vault items` | List all items in the vault with metadata. |
+
+## Configuration
+
+Shared config: `~/.config/kodemeio/config.yaml`
+
+```bash
+kctl-op config init       # Interactive setup
+kctl-op config show       # Show current config
+kctl-op config profiles   # List profiles
+kctl-op config current    # Show active profile
+kctl-op config validate   # Verify config
+```

kctl_op-0.5.0/src/kctl_op/__init__.py

@@ -0,0 +1,3 @@
+"""kctl-op: 1Password secret management CLI."""
+
+__version__ = "0.5.0"

kctl_op-0.5.0/src/kctl_op/__main__.py

@@ -0,0 +1,3 @@
+from kctl_op.cli import _run
+
+_run()

kctl_op-0.5.0/src/kctl_op/cli.py

@@ -0,0 +1,196 @@
+"""Main Typer application for kctl-op."""
+
+from __future__ import annotations
+
+
+import sys
+from typing import Annotated
+
+import typer
+
+from kctl_op import __version__
+from kctl_op.commands.backup import app as backup_app
+
+# Command group imports
+from kctl_op.commands.config_cmd import app as config_app
+from kctl_op.commands.diff_cmd import app as diff_app
+from kctl_op.commands.discover import app as discover_app
+from kctl_op.commands.health import app as health_app
+from kctl_op.commands.projects import app as projects_app
+from kctl_op.commands.status import app as status_app
+from kctl_op.commands.sync_cmd import pull_app, push_app
+from kctl_op.commands.vault import app as vault_app
+from kctl_op.core.callbacks import AppContext
+from kctl_lib import handle_cli_error
+from kctl_op.commands.skill_cmd import app as skill_app
+from kctl_op.commands.doctor_cmd import app as doctor_app
+from kctl_op.core.exceptions import (
+    KctlError,
+)
+from kctl_lib.self_update import notify_if_outdated
+from kctl_lib.tui import add_tui_command
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        print(f"kctl-op {__version__}")
+        raise typer.Exit()
+
+
+app = typer.Typer(
+    name="kctl-op",
+    help="Kodemeio 1Password CLI - manage secrets across all projects via 1Password.",
+    no_args_is_help=True,
+    rich_markup_mode="rich",
+    pretty_exceptions_enable=False,
+)
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Output in JSON format.")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress non-essential output.")] = False,
+    profile: Annotated[str | None, typer.Option("--profile", "-p", help="Config profile to use.")] = None,
+    format: Annotated[str, typer.Option("--format", "-f", help="Output format: pretty, json, csv, yaml.")] = "pretty",
+    no_header: Annotated[bool, typer.Option("--no-header", help="Omit header row in CSV output.")] = False,
+    vault: Annotated[str | None, typer.Option("--vault", help="Override vault name.")] = None,
+    token: Annotated[str | None, typer.Option("--token", help="Override service account token.")] = None,
+    version: Annotated[
+        bool,
+        typer.Option(
+            "--version",
+            "-V",
+            callback=_version_callback,
+            is_eager=True,
+            help="Show version and exit.",
+        ),
+    ] = False,
+) -> None:
+    """Global options applied to all commands."""
+    ctx.ensure_object(dict)
+    ctx.obj = AppContext(
+        json_mode=json_output,
+        quiet=quiet,
+        profile=profile,
+        format=format,
+        no_header=no_header,
+        vault_override=vault,
+        token_override=token,
+    )
+    notify_if_outdated(ctx.obj.output, "kctl-op", __version__)
+
+
+# Register command groups
+app.add_typer(config_app, name="config")
+app.add_typer(health_app, name="health")
+app.add_typer(discover_app, name="discover")
+app.add_typer(status_app, name="status")
+app.add_typer(push_app, name="push")
+app.add_typer(pull_app, name="pull")
+app.add_typer(diff_app, name="diff")
+app.add_typer(vault_app, name="vault")
+app.add_typer(projects_app, name="projects")
+app.add_typer(backup_app, name="backup")
+app.add_typer(skill_app, name="skill", hidden=True)
+app.add_typer(doctor_app, name="doctor")
+add_tui_command(app, service_key="op", version=__version__)
+
+
+# Top-level convenience commands
+@app.command(name="list")
+def list_items(ctx: typer.Context) -> None:
+    """List all items in the 1Password vault."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    client = actx.client
+
+    try:
+        items = client.list_items()
+    except Exception as e:
+        out.error(f"Cannot list items: {e}")
+        raise typer.Exit(code=1) from e
+
+    if not items:
+        out.info("No items in vault.")
+        return
+
+    rows = []
+    json_data = []
+    for item in items:
+        title = item.get("title", "untitled")
+        tags = ", ".join(item.get("tags", []))
+        updated = item.get("updated_at", "unknown")
+        rows.append([title, tags, updated])
+        json_data.append(
+            {
+                "title": title,
+                "id": item.get("id", ""),
+                "tags": item.get("tags", []),
+                "updated_at": updated,
+            }
+        )
+
+    out.table(
+        title=f"Vault Items ({len(items)})",
+        columns=[
+            ("Title", "green"),
+            ("Tags", "cyan"),
+            ("Updated", "dim"),
+        ],
+        rows=rows,
+        data_for_json=json_data,
+    )
+
+
+@app.command("self-update")
+def self_update_cmd(ctx: typer.Context) -> None:
+    """Check for updates and upgrade kctl-op."""
+    actx = ctx.obj
+    out = actx.output
+
+    from kctl_lib.self_update import check_update
+    from kctl_lib.self_update import update as do_update
+
+    latest = check_update("kctl-op", __version__)
+    if latest:
+        out.info(f"Updating to {latest}...")
+        do_update("kctl-op")
+        out.success(f"Updated to {latest}")
+    else:
+        out.success("Already up to date")
+
+
+@app.command()
+def completions(
+    shell: Annotated[str, typer.Argument(help="Shell type: zsh, bash, fish")] = "zsh",
+    install: Annotated[bool, typer.Option("--install", help="Install completions")] = False,
+) -> None:
+    """Generate or install shell completions."""
+    from kctl_lib.completions import get_completion_script, install_completions
+
+    if install:
+        path = install_completions("kctl-op", shell)
+        if path:
+            typer.echo(f"Completions installed to {path}")
+        else:
+            typer.echo(f"Could not install completions for {shell}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        script = get_completion_script("kctl-op", shell)
+        typer.echo(script)
+
+
+def _run() -> None:
+    """Entry point with error handling."""
+    try:
+        app()
+    except KctlError as e:
+        handle_cli_error(e)
+    except KeyboardInterrupt:
+        print("\nAborted.", file=sys.stderr)
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    _run()

kctl_op-0.5.0/src/kctl_op/commands/backup.py

@@ -0,0 +1,178 @@
+"""Backup management commands."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from kctl_op.core.callbacks import AppContext
+
+BACKUP_DIR = Path.home() / ".kodemeio-op" / "backups"
+
+app = typer.Typer(help="Backup management for .env files.")
+
+
+@app.command(name="list")
+def list_backups(
+    ctx: typer.Context,
+    project: Annotated[str | None, typer.Argument(help="Filter by project name.")] = None,
+) -> None:
+    """List available backups."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    if not BACKUP_DIR.exists():
+        out.info("No backups found.")
+        return
+
+    rows = []
+    json_data = []
+
+    for project_dir in sorted(BACKUP_DIR.iterdir()):
+        if not project_dir.is_dir():
+            continue
+        if project and project_dir.name != project:
+            continue
+
+        for env_dir in sorted(project_dir.iterdir()):
+            if not env_dir.is_dir():
+                continue
+
+            backups = sorted(env_dir.glob("*.bak"), reverse=True)
+            for bak in backups:
+                size = bak.stat().st_size
+                rows.append(
+                    [
+                        project_dir.name,
+                        env_dir.name,
+                        bak.name,
+                        f"{size:,} bytes",
+                    ]
+                )
+                json_data.append(
+                    {
+                        "project": project_dir.name,
+                        "environment": env_dir.name,
+                        "filename": bak.name,
+                        "size": size,
+                        "path": str(bak),
+                    }
+                )
+
+    if not rows:
+        out.info("No backups found." + (f" (project: {project})" if project else ""))
+        return
+
+    out.table(
+        title=f"Backups ({len(rows)})",
+        columns=[
+            ("Project", "green"),
+            ("Environment", "cyan"),
+            ("Filename", ""),
+            ("Size", "dim"),
+        ],
+        rows=rows,
+        data_for_json=json_data,
+    )
+
+
+@app.command()
+def restore(
+    ctx: typer.Context,
+    project: Annotated[str, typer.Argument(help="Project name.")],
+    environment: Annotated[str, typer.Argument(help="Environment name.")],
+    timestamp: Annotated[
+        str | None, typer.Argument(help="Backup timestamp (from filename). Latest if omitted.")
+    ] = None,
+    force: Annotated[bool, typer.Option("--force", help="Skip confirmation.")] = False,
+) -> None:
+    """Restore a .env file from backup."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    env_backup_dir = BACKUP_DIR / project / environment
+    if not env_backup_dir.exists():
+        out.error(f"No backups found for {project}/{environment}")
+        raise typer.Exit(code=1)
+
+    backups = sorted(env_backup_dir.glob("*.bak"), reverse=True)
+    if not backups:
+        out.error(f"No backup files in {env_backup_dir}")
+        raise typer.Exit(code=1)
+
+    if timestamp:
+        selected = [b for b in backups if timestamp in b.name]
+        if not selected:
+            out.error(f"No backup matching timestamp '{timestamp}'")
+            raise typer.Exit(code=1)
+        backup_file = selected[0]
+    else:
+        backup_file = backups[0]
+
+    out.info(f"Restoring from: {backup_file.name}")
+
+    # Find the target .env file
+    cfg = actx.service_config
+    client = actx.client
+    files = client.discover_files(
+        cfg.scan_roots,
+        cfg.exclude_patterns,
+        cfg.env_mappings,
+        cfg.custom_env_pattern,
+    )
+    matches = [f for f in files if f.project == project and f.environment == environment]
+
+    if not matches:
+        out.error(f"Cannot find target .env file for {project}/{environment}")
+        raise typer.Exit(code=1)
+
+    target = matches[0].path
+
+    if not force and not typer.confirm(f"Restore {backup_file.name} to {target}?"):
+        raise typer.Exit()
+
+    # Read backup and write to target
+    content = backup_file.read_text()
+    target.write_text(content)
+    out.success(f"Restored {backup_file.name} -> {target}")
+
+
+@app.command()
+def clean(
+    ctx: typer.Context,
+    keep: Annotated[int, typer.Option("--keep", "-k", help="Number of backups to keep per file.")] = 10,
+    force: Annotated[bool, typer.Option("--force", help="Skip confirmation.")] = False,
+) -> None:
+    """Clean old backups, keeping the N most recent per file."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+
+    if not BACKUP_DIR.exists():
+        out.info("No backups to clean.")
+        return
+
+    to_delete: list[Path] = []
+    for project_dir in BACKUP_DIR.iterdir():
+        if not project_dir.is_dir():
+            continue
+        for env_dir in project_dir.iterdir():
+            if not env_dir.is_dir():
+                continue
+            backups = sorted(env_dir.glob("*.bak"), reverse=True)
+            if len(backups) > keep:
+                to_delete.extend(backups[keep:])
+
+    if not to_delete:
+        out.info(f"Nothing to clean (keeping {keep} per file).")
+        return
+
+    out.info(f"Will delete {len(to_delete)} old backup(s).")
+
+    if not force and not typer.confirm("Proceed?"):
+        raise typer.Exit()
+
+    for f in to_delete:
+        f.unlink()
+    out.success(f"Deleted {len(to_delete)} old backup(s).")