evo-cli 0.11.4__tar.gz → 0.12.1__tar.gz

{evo_cli-0.11.4 → evo_cli-0.12.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evo_cli
-Version: 0.11.4
+Version: 0.12.1
 Summary: Evolution CLI - a developer toolbox for setting up dev machines
 Author: maycuatroi
 Project-URL: Homepage, https://github.com/maycuatroi/evo-cli
@@ -114,6 +114,38 @@ Options:
 - `-f, --force` - Apply the fix even if the version is not in the affected range
 - `--unpin` - Undo the fix: re-enable the auto-updater and install the latest build
 
+#### Credentials
+
+`evo` owns the omelet credential store. The source of truth is a folder of one JSON file per service
+(`~/.omelet.d/credentials/`), which compiles into a flat `~/.omelet.json` that older consumers read
+directly.
+
+```bash
+evo cred doctor                       # health + expiry of every credential, exit 1 if any expired
+evo cred get openai_api_key           # print one value by dotted path, nothing else on stdout
+evo cred add openai_api_key           # prompt with no echo, write the folder file, recompile
+evo cred refresh --all                # refresh Google OAuth access tokens
+evo cred compile                      # rebuild ~/.omelet.json from the folder
+evo cred sync push                    # push the folder to a private GitHub repo via gh
+```
+
+Read a value into the environment without it reaching your shell history:
+
+```bash
+eval "$(evo cred get --export OPENAI_API_KEY openai_api_key)"
+```
+
+Configuration is env-driven, with no personal defaults baked in:
+
+- `OMELET_DIR` - store root (default `~/.omelet.d`; the folder is `$OMELET_DIR/credentials`)
+- `OMELET_CONFIG` - compiled flat file (default `~/.omelet.json`)
+- `OMELET_SYNC_REPO` - required for `sync`; a **private** GitHub repo as `owner/repo`
+- `OMELET_SYNC_DIR` - folder name inside the sync repo (default `credentials`)
+- `RCLONE_DRIVE_CLIENT_ID` / `RCLONE_DRIVE_CLIENT_SECRET` - OAuth client for the rclone refresh
+
+`evo cred sync push` refuses to push to a repo whose visibility is not `PRIVATE`. Never echo a value
+into a shared terminal or a log; `doctor` and `list` only ever print a masked preview.
+
 #### Harness Repositories
 
 Fast-forward every available repository declared in a harness manifest:

{evo_cli-0.11.4 → evo_cli-0.12.1}/README.md

@@ -86,6 +86,38 @@ Options:
 - `-f, --force` - Apply the fix even if the version is not in the affected range
 - `--unpin` - Undo the fix: re-enable the auto-updater and install the latest build
 
+#### Credentials
+
+`evo` owns the omelet credential store. The source of truth is a folder of one JSON file per service
+(`~/.omelet.d/credentials/`), which compiles into a flat `~/.omelet.json` that older consumers read
+directly.
+
+```bash
+evo cred doctor                       # health + expiry of every credential, exit 1 if any expired
+evo cred get openai_api_key           # print one value by dotted path, nothing else on stdout
+evo cred add openai_api_key           # prompt with no echo, write the folder file, recompile
+evo cred refresh --all                # refresh Google OAuth access tokens
+evo cred compile                      # rebuild ~/.omelet.json from the folder
+evo cred sync push                    # push the folder to a private GitHub repo via gh
+```
+
+Read a value into the environment without it reaching your shell history:
+
+```bash
+eval "$(evo cred get --export OPENAI_API_KEY openai_api_key)"
+```
+
+Configuration is env-driven, with no personal defaults baked in:
+
+- `OMELET_DIR` - store root (default `~/.omelet.d`; the folder is `$OMELET_DIR/credentials`)
+- `OMELET_CONFIG` - compiled flat file (default `~/.omelet.json`)
+- `OMELET_SYNC_REPO` - required for `sync`; a **private** GitHub repo as `owner/repo`
+- `OMELET_SYNC_DIR` - folder name inside the sync repo (default `credentials`)
+- `RCLONE_DRIVE_CLIENT_ID` / `RCLONE_DRIVE_CLIENT_SECRET` - OAuth client for the rclone refresh
+
+`evo cred sync push` refuses to push to a repo whose visibility is not `PRIVATE`. Never echo a value
+into a shared terminal or a log; `doctor` and `list` only ever print a masked preview.
+
 #### Harness Repositories
 
 Fast-forward every available repository declared in a harness manifest:

evo_cli-0.12.1/evo_cli/VERSION

@@ -0,0 +1 @@
+0.12.1

{evo_cli-0.11.4 → evo_cli-0.12.1}/evo_cli/cli.py

@@ -3,6 +3,7 @@ import rich_click as click
 from evo_cli import __version__
 from evo_cli.commands.claude_code import setup_claude
 from evo_cli.commands.cloudflare import cfssh
+from evo_cli.commands.cred import cred_group
 from evo_cli.commands.download import download
 from evo_cli.commands.fix_claude import f_claude
 from evo_cli.commands.gdrive import gdrive
@@ -19,6 +20,7 @@ from evo_cli.commands.plantuml import plantuml
 from evo_cli.commands.site2s import site2s
 from evo_cli.commands.ssh import setupssh
 from evo_cli.commands.sysmon import sysmon
+from evo_cli.commands.update import update
 from evo_cli.commands.wifi import wifi
 
 
@@ -56,6 +58,7 @@ setup_group.add_command(setupssh)
 
 cli.add_command(setup_group)
 cli.add_command(cfssh)
+cli.add_command(cred_group)
 cli.add_command(download)
 cli.add_command(f_claude)
 cli.add_command(gdrive)
@@ -68,6 +71,7 @@ cli.add_command(mcp_group)
 cli.add_command(netcheck)
 cli.add_command(plantuml)
 cli.add_command(sysmon)
+cli.add_command(update)
 cli.add_command(wifi)
 
 

evo_cli-0.12.1/evo_cli/commands/cred.py

@@ -0,0 +1,279 @@
+import getpass
+import json
+import os
+import sys
+
+import rich_click as click
+from rich.table import Table
+
+from evo_cli.console import console, info, success, warning
+from evo_cli.credentials import doctor as doctor_module
+from evo_cli.credentials import google_oauth, migrate, sync
+from evo_cli.credentials.registry import config_path, credentials_dir
+from evo_cli.credentials.store import (
+    CredentialError,
+    compile_flat,
+    get_value,
+    read_flat,
+    relative_to_store,
+    require_folder,
+    set_value,
+)
+
+HEALTH_STYLE = {
+    "ok": "green",
+    "expiring": "yellow",
+    "EXPIRED": "bold red",
+    "deprecated": "dim",
+}
+
+
+def _guard(func, *args, **kwargs):
+    try:
+        return func(*args, **kwargs)
+    except CredentialError as exc:
+        raise click.ClickException(str(exc)) from exc
+    except ValueError as exc:
+        raise click.ClickException(str(exc)) from exc
+
+
+def _render(rows):
+    table = Table(show_header=True, header_style="accent", box=None, pad_edge=False)
+    for column in ("FILE", "SERVICE", "TYPE", "HEALTH", "SECRET", "EXPIRY"):
+        table.add_column(column, overflow="fold")
+    for row in rows:
+        table.add_row(
+            row["file"],
+            row["service"],
+            row["type"],
+            f"[{HEALTH_STYLE.get(row['health'], 'white')}]{row['health']}[/]",
+            row["secret"],
+            row["expiry"],
+        )
+    console.print(table)
+
+
+@click.group("cred", help="Read, refresh, and sync the omelet credential store.")
+def cred_group():
+    pass
+
+
+@cred_group.command("get", help="Print one credential by dotted key path.")
+@click.argument("key_path")
+@click.option("--export", "export_var", metavar="VAR", help="Print a shell export statement instead of the raw value.")
+def get(key_path, export_var):
+    value = _guard(get_value, key_path)
+
+    if isinstance(value, (dict, list)):
+        sys.stdout.write(json.dumps(value, ensure_ascii=False) + "\n")
+        return
+
+    text = str(value)
+    if export_var:
+        escaped = text.replace("'", "'\\''")
+        sys.stdout.write(f"export {export_var}='{escaped}'\n")
+        return
+
+    sys.stdout.write(text)
+    if sys.stdout.isatty():
+        sys.stdout.write("\n")
+
+
+@cred_group.command("list", help="List every credential in the store with its health.")
+def list_credentials():
+    _guard(require_folder)
+    rows = _guard(doctor_module.scan)
+    _render(rows)
+    console.print(f"\n{len(rows)} entries in {credentials_dir()}")
+
+
+@cred_group.command("doctor", help="Report health and expiry; exit 1 if anything is expired.")
+def doctor():
+    _guard(require_folder)
+    rows = _guard(doctor_module.scan)
+    _render(rows)
+    expired = [row for row in rows if row["health"] == "EXPIRED"]
+    console.print(f"\n{len(rows)} entries in {credentials_dir()}")
+    if expired:
+        warning(f"{len(expired)} EXPIRED - run: evo cred refresh --all")
+        raise click.exceptions.Exit(1)
+    success("all credentials healthy")
+
+
+@cred_group.command("compile", help="Rebuild the flat config from the credentials folder.")
+@click.option("--include-legacy", is_flag=True, help="Also merge entries marked deprecated.")
+def compile_command(include_legacy):
+    count, skipped, target = _guard(compile_flat, include_legacy=include_legacy)
+    message = f"compiled {count} entries -> {target}"
+    if skipped:
+        message += f" (skipped {len(skipped)} deprecated: {', '.join(skipped)})"
+    success(message)
+
+
+@cred_group.command("add", help="Add or update a credential, then recompile the flat config.")
+@click.argument("key_path")
+@click.option("--from-stdin", is_flag=True, help="Read the value from stdin.")
+@click.option("--from-env", metavar="VAR", help="Read the value from an environment variable.")
+@click.option("--value", "inline_value", help="Inline value. Avoid: leaks to shell history.")
+@click.option("--json", "parse_json", is_flag=True, help="Parse the value as JSON (bool/number/object/array).")
+def add(key_path, from_stdin, from_env, inline_value, parse_json):
+    sources = [bool(from_stdin), bool(from_env), inline_value is not None]
+    if sum(sources) > 1:
+        raise click.UsageError("Use only one of --from-stdin, --from-env, --value.")
+
+    if from_stdin:
+        value = sys.stdin.read().rstrip("\n")
+    elif from_env:
+        if from_env not in os.environ:
+            raise click.ClickException(f"env var {from_env} not set")
+        value = os.environ[from_env]
+    elif inline_value is not None:
+        value = inline_value
+    else:
+        value = getpass.getpass(f"value for {key_path} (no echo): ")
+        if not value:
+            raise click.ClickException("empty value, aborting")
+
+    if parse_json:
+        try:
+            value = json.loads(value)
+        except json.JSONDecodeError as exc:
+            raise click.ClickException(f"--json: failed to parse value: {exc}") from exc
+
+    path, existed = _guard(set_value, key_path, value)
+    count, _, target = _guard(compile_flat)
+    verb = "updated" if existed else "added"
+    success(f"{verb} {key_path} in {relative_to_store(path)}, recompiled {target} ({count} entries)")
+
+
+@cred_group.command("refresh", help="Refresh Google OAuth access tokens and recompile.")
+@click.option("--all", "refresh_all", is_flag=True, help="Refresh every refreshable OAuth entry.")
+@click.option(
+    "--service",
+    type=click.Choice(sorted(google_oauth.SERVICE_ALIASES)),
+    help="Refresh a single service.",
+)
+@click.option("--dry-run", is_flag=True, help="Show what would be refreshed without calling Google.")
+def refresh(refresh_all, service, dry_run):
+    if refresh_all == bool(service):
+        raise click.UsageError("Pass exactly one of --all or --service.")
+
+    _guard(require_folder)
+    target = "*" if refresh_all else google_oauth.SERVICE_ALIASES[service]
+    entries = _guard(google_oauth.select_entries, target)
+    if not entries:
+        raise click.ClickException("no matching refreshable oauth entries")
+
+    failures = 0
+    refreshed = 0
+    for path, entry in entries:
+        name = entry.get("id", path.name)
+        creds, err = google_oauth.resolve_creds(entry)
+        if err:
+            warning(f"{name}: skip ({err})")
+            failures += 1
+            continue
+
+        if dry_run:
+            info(
+                f"{name}: would POST {google_oauth.TOKEN_URL} "
+                f"refresh_token={creds['refresh_token'][:10]}... client_id={creds['client_id'][:12]}..."
+            )
+            continue
+
+        try:
+            expiry = google_oauth.refresh_entry(path, entry, creds)
+        except Exception as exc:
+            warning(f"{name}: {google_oauth.describe_error(exc)}")
+            failures += 1
+            continue
+
+        refreshed += 1
+        success(f"{name}: refreshed, valid until {expiry}")
+
+    if refreshed:
+        count, _, target_path = _guard(compile_flat)
+        info(f"recompiled {target_path} ({count} entries)")
+
+    if failures:
+        raise click.exceptions.Exit(1)
+
+
+@cred_group.command("migrate", help="Split a flat omelet.json into the per-service credentials folder.")
+@click.option("--source", "source", type=click.Path(), help="Flat file to migrate. Defaults to the compiled config.")
+@click.option("--dry-run", is_flag=True, help="Show the plan, write nothing.")
+@click.option("--merge", is_flag=True, help="Migrate into an existing folder, adding only keys not already present.")
+@click.option("--strict", is_flag=True, help="Abort on keys not mapped in the registry instead of routing to misc/.")
+@click.option("--force", is_flag=True, help="Overwrite an existing non-empty folder.")
+def migrate_command(source, dry_run, merge, strict, force):
+    result = _guard(migrate.plan, source or config_path(), strict=strict, merge=merge)
+
+    console.print(f"source: {result['source_path']} ({result['source_keys']} top-level keys)")
+    console.print(f"target: {credentials_dir()}{'  [MERGE]' if merge else ''}\n")
+
+    for item in result["actions"]:
+        flags = " [unmapped->misc]" if item["misc"] else ""
+        if item["entry"].get("status") == "deprecated":
+            flags += " [DEPRECATED]"
+        if item["entry"].get("expiry"):
+            flags += f" expiry={item['entry']['expiry']}"
+        console.print(f"  {item['action']:6s} {item['rel']:40s} <- {', '.join(item['keys'])}{flags}")
+
+    if result["unmapped"]:
+        warning(f"{len(result['unmapped'])} unmapped key(s) routed to misc/: {', '.join(result['unmapped'])}")
+
+    if dry_run:
+        info(f"dry-run: would write {len(result['actions'])} file(s)")
+        return
+
+    if not result["actions"]:
+        info("nothing to do (folder already up to date)")
+        return
+
+    if migrate.folder_has_files() and not (merge or force):
+        raise click.ClickException(
+            f"refusing: {credentials_dir()} already has files.\n"
+            "Use --merge (add missing keys) or --force (overwrite), or point OMELET_DIR elsewhere."
+        )
+
+    backup = _guard(migrate.apply, result)
+    info(f"backed up source -> {backup}")
+    success(f"wrote {len(result['actions'])} file(s) to {credentials_dir()}")
+
+    count, _, target_path = _guard(compile_flat)
+    success(f"compiled {count} entries -> {target_path}")
+
+
+@cred_group.group("sync", help="Sync the credentials folder with a private GitHub repo.")
+def sync_group():
+    pass
+
+
+@sync_group.command("push", help="Push the local credentials folder to the sync repo.")
+def sync_push():
+    host = _guard(sync.push)
+    if host is None:
+        info("no changes to push")
+        return
+    success(f"pushed {sync.dir_in_repo()}/ to {sync.sync_repo()} (from {host})")
+
+
+@sync_group.command("pull", help="Pull the credentials folder from the sync repo, then recompile.")
+def sync_pull():
+    backup = _guard(sync.pull)
+    if backup:
+        info(f"backed up existing folder -> {backup}")
+    success(f"pulled {sync.sync_repo()}:{sync.dir_in_repo()}/ -> {credentials_dir()}")
+    count, _, target_path = _guard(compile_flat)
+    success(f"compiled {count} entries -> {target_path}")
+
+
+@cred_group.command("path", help="Print the store locations this machine resolves to.")
+def show_path():
+    console.print(f"folder: {credentials_dir()}")
+    console.print(f"flat:   {config_path()}")
+    try:
+        keys = [key for key in read_flat() if not key.startswith("_")]
+    except CredentialError:
+        keys = []
+    console.print(f"keys:   {len(keys)}")

evo_cli-0.12.1/evo_cli/commands/update.py

@@ -0,0 +1,291 @@
+import json
+import re
+import shutil
+import subprocess
+import sys
+import urllib.error
+import urllib.request
+from importlib import metadata
+from pathlib import Path
+from urllib.parse import urlparse
+from urllib.request import url2pathname
+
+import rich_click as click
+from rich.table import Table
+from rich.text import Text
+
+from evo_cli import __version__
+from evo_cli.console import CommandError, console, info, run_command, step, success, warning
+
+PACKAGE = "evo_cli"
+PYPI_JSON = "https://pypi.org/pypi/{package}/json"
+
+VERSION_RE = re.compile(r"^v?(\d+(?:\.\d+)*)(?:[-_.]?(dev|alpha|a|beta|b|rc|c|pre)[-_.]?(\d*))?")
+PRE_RANK = {"dev": -4, "alpha": -3, "a": -3, "beta": -2, "b": -2, "pre": -1, "rc": -1, "c": -1}
+
+EPILOG = Text.from_markup(
+    "[bold]Examples[/bold]\n\n"
+    "  [cyan]evo update[/cyan]              update to the newest release\n"
+    "  [cyan]evo update --check[/cyan]      only report whether an update exists\n"
+    "  [cyan]evo update --pre[/cyan]        include pre-release versions\n"
+    "  [cyan]evo update --dry-run[/cyan]    print the commands without running them\n"
+    "  [cyan]evo update --force[/cyan]      reinstall even when already current\n\n"
+    "[dim]An editable checkout is updated with git (fast-forward only, refusing to touch a\n"
+    "dirty tree); a pipx, uv or pip install is upgraded with its own installer.[/dim]"
+)
+
+
+def parse_version(value):
+    match = VERSION_RE.match(str(value).strip().lower())
+    if not match:
+        return ((0,), 0, 0)
+    release = tuple(int(part) for part in match.group(1).split("."))
+    label = match.group(2)
+    if label is None:
+        return (release, 0, 0)
+    return (release, PRE_RANK.get(label, -1), int(match.group(3) or 0))
+
+
+def is_prerelease(value):
+    return VERSION_RE.match(str(value).strip().lower()) is not None and parse_version(value)[1] < 0
+
+
+def fetch_pypi(package, timeout):
+    request = urllib.request.Request(PYPI_JSON.format(package=package), headers={"User-Agent": "evo-cli"})
+    with urllib.request.urlopen(request, timeout=timeout) as response:
+        return json.loads(response.read().decode("utf-8"))
+
+
+def latest_version(data, allow_pre):
+    candidates = []
+    for version, files in (data.get("releases") or {}).items():
+        if not files or all(item.get("yanked") for item in files):
+            continue
+        if not allow_pre and is_prerelease(version):
+            continue
+        candidates.append(version)
+    if candidates:
+        return max(candidates, key=parse_version)
+    return (data.get("info") or {}).get("version")
+
+
+def read_direct_url():
+    try:
+        dist = metadata.distribution(PACKAGE)
+    except metadata.PackageNotFoundError:
+        return {}
+    try:
+        raw = dist.read_text("direct_url.json")
+    except OSError:
+        return {}
+    if not raw:
+        return {}
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return {}
+
+
+def editable_source():
+    data = read_direct_url()
+    if not (data.get("dir_info") or {}).get("editable"):
+        return None
+    url = data.get("url") or ""
+    if not url.startswith("file:"):
+        return None
+    path = Path(url2pathname(urlparse(url).path))
+    return path if path.is_dir() else None
+
+
+def detect_install():
+    source = editable_source()
+    if source is not None:
+        return {"mode": "editable", "location": source}
+    prefix = Path(sys.prefix).resolve()
+    parts = [part.lower() for part in prefix.parts]
+    if "pipx" in parts:
+        return {"mode": "pipx", "location": prefix}
+    if "uv" in parts and "tools" in parts:
+        return {"mode": "uv", "location": prefix}
+    return {"mode": "pip", "location": prefix}
+
+
+def git(path, *args):
+    return subprocess.run(
+        ["git", "-C", str(path), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        check=False,
+    )
+
+
+def git_detail(result, fallback):
+    lines = ((result.stderr or "") + (result.stdout or "")).strip().splitlines()
+    return lines[-1] if lines else fallback
+
+
+def report(install, current, latest):
+    table = Table(show_header=False, box=None, expand=False)
+    table.add_column(style="info", no_wrap=True)
+    table.add_column()
+    table.add_row("Installed", f"[accent]{current}[/accent]")
+    table.add_row("Latest on PyPI", f"[accent]{latest}[/accent]" if latest else "[dim]unknown[/dim]")
+    table.add_row("Install mode", install["mode"])
+    table.add_row("Location", f"[dim]{install['location']}[/dim]")
+    console.print(table)
+    console.print()
+
+
+def build_commands(mode, allow_pre):
+    target = f"{PACKAGE}"
+    if mode == "pipx":
+        if shutil.which("pipx") is None:
+            raise click.ClickException("This looks like a pipx install but pipx is not on PATH.")
+        cmd = ["pipx", "upgrade", target]
+        if allow_pre:
+            cmd.append("--pip-args=--pre")
+        return [cmd]
+    if mode == "uv":
+        if shutil.which("uv") is None:
+            raise click.ClickException("This looks like a uv tool install but uv is not on PATH.")
+        cmd = ["uv", "tool", "upgrade", target]
+        if allow_pre:
+            cmd.append("--prerelease=allow")
+        return [cmd]
+    probe = subprocess.run([sys.executable, "-m", "pip", "--version"], capture_output=True)
+    if probe.returncode != 0:
+        raise click.ClickException(f"pip is not available for {sys.executable}. Install pip or use pipx/uv.")
+    cmd = [sys.executable, "-m", "pip", "install", "--upgrade", target]
+    if allow_pre:
+        cmd.append("--pre")
+    return [cmd]
+
+
+def execute(commands, dry_run):
+    for cmd in commands:
+        if dry_run:
+            console.print(f"[cmd]$ {' '.join(str(part) for part in cmd)}[/cmd]")
+            continue
+        try:
+            run_command(cmd)
+        except CommandError as exc:
+            raise click.ClickException(str(exc)) from exc
+
+
+def update_editable(path, check, force, dry_run):
+    if shutil.which("git") is None:
+        raise click.ClickException("git is not installed or is not on PATH")
+
+    status = git(path, "status", "--porcelain")
+    if status.returncode != 0:
+        raise click.ClickException(f"{path} is not a git repository")
+
+    info(f"Editable checkout at [accent]{path}[/accent]")
+    if not dry_run:
+        fetched = git(path, "fetch", "--prune")
+        if fetched.returncode != 0:
+            warning(f"git fetch failed: {git_detail(fetched, 'unknown error')}")
+
+    upstream = git(path, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}")
+    if upstream.returncode != 0:
+        raise click.ClickException("The checkout has no upstream branch to update from.")
+    tracking = upstream.stdout.strip()
+
+    counts = git(path, "rev-list", "--left-right", "--count", "HEAD...@{u}")
+    ahead, behind = 0, 0
+    if counts.returncode == 0 and counts.stdout.split():
+        numbers = counts.stdout.split()
+        ahead, behind = int(numbers[0]), int(numbers[1])
+
+    if behind == 0 and not force:
+        success(f"Already up to date with [accent]{tracking}[/accent].")
+        if ahead:
+            info(f"{ahead} local commit(s) not pushed yet.")
+        return
+
+    info(f"{behind} new commit(s) on [accent]{tracking}[/accent].")
+    if check:
+        info("Run [accent]evo update[/accent] to apply them.")
+        return
+    if status.stdout.strip():
+        if dry_run:
+            warning("The checkout has uncommitted changes, so the update would stop here.")
+            return
+        raise click.ClickException("The checkout has uncommitted changes. Commit or stash them first.")
+
+    before = git(path, "rev-parse", "HEAD").stdout.strip()
+    if dry_run:
+        console.print(f"[cmd]$ git -C {path} pull --ff-only --prune[/cmd]")
+        return
+
+    pulled = git(path, "pull", "--ff-only", "--prune")
+    if pulled.returncode != 0:
+        raise click.ClickException(f"git pull failed: {git_detail(pulled, 'unknown error')}")
+
+    after = git(path, "rev-parse", "HEAD").stdout.strip()
+    head = git(path, "log", "-1", "--oneline").stdout.strip()
+    success(f"Updated to {head or after}")
+
+    changed = git(path, "diff", "--name-only", before, after).stdout.split()
+    if force or any(name in ("pyproject.toml", "setup.py", "setup.cfg") for name in changed):
+        info("Dependency metadata changed, reinstalling the package.")
+        execute([[sys.executable, "-m", "pip", "install", "-e", str(path), "--quiet"]], dry_run)
+
+    version_file = path / "evo_cli" / "VERSION"
+    if version_file.is_file():
+        success(f"evo is now at [accent]{version_file.read_text(encoding='utf-8').strip()}[/accent]")
+
+
+def update_package(mode, current, latest, check, allow_pre, force, dry_run):
+    if latest is None:
+        if check:
+            raise click.ClickException("Cannot determine the latest version from PyPI.")
+        warning("Skipping the version check and upgrading anyway.")
+    elif parse_version(latest) <= parse_version(current) and not force:
+        success(f"evo [accent]{current}[/accent] is already the latest release.")
+        return
+    elif latest:
+        info(f"Update available: [accent]{current}[/accent] -> [accent]{latest}[/accent]")
+
+    if check:
+        info("Run [accent]evo update[/accent] to install it.")
+        return
+
+    execute(build_commands(mode, allow_pre), dry_run)
+    if not dry_run:
+        success(f"evo updated to [accent]{latest or 'the latest release'}[/accent].")
+        info("Open a new shell if the `evo` command still reports the old version.")
+
+
+@click.command("update", epilog=EPILOG, context_settings={"help_option_names": ["-h", "--help"]})
+@click.option("-c", "--check", is_flag=True, help="Only report whether a newer version is available.")
+@click.option("--pre", "allow_pre", is_flag=True, help="Consider pre-release versions.")
+@click.option("-f", "--force", is_flag=True, help="Reinstall even when already up to date.")
+@click.option("-n", "--dry-run", is_flag=True, help="Print the commands instead of running them.")
+@click.option("--timeout", type=float, default=15.0, show_default=True, help="PyPI request timeout in seconds.")
+def update(check, allow_pre, force, dry_run, timeout):
+    """Update **evo** itself to the latest version.
+
+    Detects how `evo` was installed and uses the matching updater: a git
+    fast-forward for an editable checkout, otherwise `pipx upgrade`,
+    `uv tool upgrade` or `pip install --upgrade`.
+
+    Use `--check` to see what is available without changing anything.
+    """
+    step("evo update")
+    install = detect_install()
+
+    latest = None
+    try:
+        latest = latest_version(fetch_pypi(PACKAGE, timeout), allow_pre)
+    except (urllib.error.URLError, OSError, ValueError) as exc:
+        warning(f"Cannot reach PyPI ({exc})")
+
+    report(install, __version__, latest)
+
+    if install["mode"] == "editable":
+        update_editable(install["location"], check, force, dry_run)
+        return
+    update_package(install["mode"], __version__, latest, check, allow_pre, force, dry_run)