recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/reads.py

@@ -0,0 +1,320 @@
+"""Authors (the people who sign), the publication calendar and the authority report."""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import click
+
+from recala_cli.client import RecalaClient
+from recala_cli.ids import resolve_person_id
+from recala_cli.endpoints import AUTHORITY_SCORE, CALENDAR, PUBLICATION_PLAN, PEOPLE_LIST, PERSON_CREATE, PERSON_UPDATE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.labels import resource_label
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, optional_read, accepted_yes_option, dry_run_option
+from recala_cli.views import calendar_view, company_timezone, planned_calendar
+
+
+def _describe_people(result: dict[str, Any]) -> str:
+    people = result.get("people") or []
+    return "\n".join(f"{p.get('display_name', '')}  {p.get('job_title') or ''}  [{str(p['id'])[:8]}]".rstrip()
+                     for p in people) or "No authors yet. Add one: recala authors add --name \"...\" --title \"...\""
+
+
+def person_body(name: str, title: str, links: tuple[str, ...], linkedin: str, bio: str,
+                expertise: tuple[str, ...]) -> dict[str, Any]:
+    """POST /api/v1/people's body. The slug is a suggestion; the server folds it to ASCII."""
+    slug = re.sub(r"[^\w]+", "-", name.strip().lower()).strip("-") or "author"
+    linkedin = linkedin or next((link for link in links if "linkedin.com/" in link), "")
+    return {"display_name": name.strip(), "slug": slug, "job_title": title.strip(), "bio": bio.strip(),
+            "linkedin_url": linkedin, "same_as": list(dict.fromkeys(links)), "knows_about": list(expertise)}
+
+
+def add_person(ctx: click.Context, client: RecalaClient, body: dict[str, Any]) -> dict[str, Any]:
+    confirm(ctx, client, f"Add {body['display_name']} ({body['job_title'] or 'no title'}) as an author who signs "
+            "articles?")
+    created: dict[str, Any] = client.call(PERSON_CREATE, json=body)
+    return created
+
+
+@click.group()
+def authors() -> None:
+    """The named people who sign the company's articles."""
+
+
+@authors.command("list")
+@common_options
+@command_runner(human=_describe_people)
+def list_authors(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Every author of the company."""
+    people: dict[str, Any] = open_client(ctx, org_flag).call(PEOPLE_LIST)
+    return people
+
+
+@authors.command("add")
+@common_options
+@command_runner(human=lambda r: f"Added {(r.get('person') or {}).get('display_name')} "
+                                f"({(r.get('person') or {}).get('id')}).")
+@click.option("--name", required=True, help="Full name as it appears on the byline.")
+@click.option("--title", "--role", default="", help="Job title, e.g. \"Founder\".")
+@click.option("--link", "--bio-link", "links", multiple=True, help="A public profile or bio link. Repeat for each.")
+@click.option("--linkedin", default="", help="The LinkedIn profile (else the first --link on linkedin.com).")
+@click.option("--bio", default="", help="One or two sentences.")
+@click.option("--expertise", multiple=True, help="A topic this person knows. Repeat for each.")
+@accepted_yes_option
+@dry_run_option
+def add_author(ctx: click.Context, org_flag: str | None, name: str, title: str, links: tuple[str, ...], linkedin: str,
+               bio: str, expertise: tuple[str, ...]) -> dict[str, Any]:
+    """Add a person who signs articles (owners)."""
+    client = open_client(ctx, org_flag)
+    return add_person(ctx, client, person_body(name, title, links, linkedin, bio, expertise))
+
+
+def person_changes(name: str | None, title: str | None, links: tuple[str, ...], linkedin: str | None,
+                   bio: str | None, expertise: tuple[str, ...]) -> dict[str, Any]:
+    """PATCH /api/v1/people/{id}'s body: only the fields the caller gave."""
+    given = {"display_name": name.strip() if name else None, "job_title": title.strip() if title is not None else None,
+             "bio": bio.strip() if bio is not None else None, "linkedin_url": linkedin,
+             "same_as": list(dict.fromkeys(links)) or None, "knows_about": list(expertise) or None}
+    return {field: value for field, value in given.items() if value is not None}
+
+
+@authors.command("edit")
+@common_options
+@command_runner(human=lambda r: f"Updated {(r.get('person') or {}).get('display_name')} "
+                                f"({(r.get('person') or {}).get('id')}).")
+@click.argument("person_id")
+@click.option("--name", default=None, help="Full name as it appears on the byline.")
+@click.option("--title", "--role", default=None, help="Job title, e.g. \"Founder\".")
+@click.option("--link", "--bio-link", "links", multiple=True, help="A public profile or bio link. Replaces the links.")
+@click.option("--linkedin", default=None, help="The LinkedIn profile.")
+@click.option("--bio", default=None, help="One or two sentences.")
+@click.option("--expertise", multiple=True, help="A topic this person knows. Replaces the topics.")
+@accepted_yes_option
+@dry_run_option
+def edit_author(ctx: click.Context, org_flag: str | None, person_id: str, name: str | None, title: str | None,
+                links: tuple[str, ...], linkedin: str | None, bio: str | None,
+                expertise: tuple[str, ...]) -> dict[str, Any]:
+    """Change an author's profile (owners). Only the fields you pass change."""
+    body = person_changes(name, title, links, linkedin, bio, expertise)
+    if not body:
+        raise CliError(ExitCode.USAGE, "nothing_to_change",
+                       "Pass at least one of --name, --role, --bio-link, --linkedin, --bio, --expertise.")
+    client = open_client(ctx, org_flag)
+    person_id = resolve_person_id(client, person_id)
+    author_label = resource_label(ctx, client, "person", person_id, result_subject=False)
+    confirm(ctx, client, f"Change {author_label}: {', '.join(body)}?")
+    updated: dict[str, Any] = client.call(PERSON_UPDATE, path={"person_id": person_id}, json=body)
+    return updated
+
+
+def _day(value: datetime | None, default: datetime) -> str:
+    return (value.replace(tzinfo=UTC) if value else default).isoformat()
+
+
+def calendar_window(start: datetime | None = None, end: datetime | None = None) -> dict[str, str]:
+    today = datetime.now(UTC).replace(hour=0, minute=0, second=0, microsecond=0)
+    return {"from": _day(start, today), "to": _day(end, today + timedelta(days=30))}
+
+
+def in_calendar_window(value: str | None, window: dict[str, str]) -> bool:
+    if not value:
+        return False
+    try:
+        moment = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    except ValueError:
+        return False
+    if moment.tzinfo is None:
+        moment = moment.replace(tzinfo=UTC)
+    return datetime.fromisoformat(window["from"]) <= moment < datetime.fromisoformat(window["to"])
+
+
+_SLOT_STATES = {
+    "bound": "planned",
+    "would_assign": "planned",
+    "generating": "being written",
+    "scheduled": "scheduled",
+    "published": "published",
+    "cancelled": "cancelled",
+    "needs_attention": "needs attention",
+    "write_ahead_window_missed": "needs attention",
+    "dispatching": "publishing",
+    "unknown": "publication outcome unknown",
+    "blocked": "needs attention: publication is blocked",
+    "not_entitled": "needs attention: the plan or article allowance does not allow writing",
+    "empty_up_next": "waiting for a topic. Add one: recala topics up-next add <title>",
+    "would_schedule": "ready to schedule",
+    "would_approve_and_schedule": "ready for automatic approval and scheduling",
+}
+_SLOT_REASONS = {
+    "write_ahead_window_missed": "it was not written in time",
+    "article_held": "the draft was held by the checks",
+    "generation_failed": "writing failed",
+    "generation_outcome_unknown": "the writing outcome is unknown",
+    "slot_missed": "the publication time has passed",
+    "auto_approval_disabled": "automatic approval is off",
+    "appointment_moved": "the publication appointment was moved",
+    "calendar_slot_taken": "the publication time is already taken",
+    "booking_unconfirmed": "the publication appointment was not confirmed",
+    "no_ready_topic": (
+        "no topic in your queue has enough of your own material yet. "
+        "Answer the material questions or add sources"
+    ),
+    "publication_destination_missing": "no publishing site is connected. Connect one: recala cms connect",
+}
+_WRITING_ACTIONS = {
+    "would_generate": "ready to write",
+    "daily_cap_reached": "waiting for the daily writing allowance to reset",
+    "billing_inactive": "billing is inactive",
+    "plan_inactive": "the plan is inactive",
+    "managed_monthly_cap_reached": "the monthly article allowance is used up",
+    "no_article_credit": "no article credit is available",
+    "entitlement_unavailable": "the article allowance could not be checked",
+    "publication_destination_missing": "no publishing site is connected. Connect one: recala cms connect",
+}
+
+# The actions that are refusals, not progress: what a not_entitled slot may name as its cause.
+_WRITING_REFUSALS = _WRITING_ACTIONS.keys() - {"would_generate", "daily_cap_reached"}
+
+
+def _needs_attention(slot: dict[str, Any]) -> bool:
+    return (slot.get("state") in ("needs_attention", "write_ahead_window_missed")
+            or slot.get("next_state") == "needs_attention")
+
+
+def _split_missed_window(reason: Any) -> tuple[Any, str]:
+    code, _, cause = str(reason or "").partition(":")
+    if code.strip() == "write_ahead_window_missed" and cause.strip():
+        return code.strip(), cause.strip()
+    return reason, ""
+
+
+def describe_slot_state(slot: dict[str, Any], cadence: dict[str, Any]) -> str:
+    """One human description shared by the calendar and read-only plan."""
+    state = slot.get("state")
+    reason = slot.get("reason") or slot.get("last_error")
+    if state == "write_ahead_window_missed":
+        reason = state
+    # The deadline keeps the refusal that blocked the slot: "write_ahead_window_missed: monthly_budget_reached".
+    reason, cause = _split_missed_window(reason)
+    if _needs_attention(slot):
+        detail = _SLOT_REASONS.get(reason, f"reason: {str(reason).replace('_', ' ')}" if reason else "check this slot")
+        if cause:
+            detail += f" ({cause.replace('_', ' ')})"
+        prefix = "" if state in _SLOT_STATES else f"state: {str(state).replace('_', ' ')}; "
+        description = f"{prefix}needs attention: {detail}."
+        if slot.get("article_id"):
+            return description + f" See: recala article show {str(slot['article_id'])[:8]}"
+        if reason == "write_ahead_window_missed" and slot.get("topic_id"):
+            return description + f" Write it now: recala article create --topic {str(slot['topic_id'])[:8]}"
+        if slot.get("escalated_at") and "generation_outcome_unknown" not in str(reason):
+            return description + f" Replace its topic: recala topics replace-slot {str(slot['id'])[:8]} <topic>"
+        return description
+
+    if state == "not_entitled" and slot.get("generation_action") in _WRITING_REFUSALS:
+        return f"needs attention: {_WRITING_ACTIONS[slot['generation_action']]}"  # the refusal, not a generic "plan"
+    description = _SLOT_STATES.get(state, f"state: {str(state or 'not recorded').replace('_', ' ')}")
+    next_state = slot.get("next_state")
+    if next_state and next_state != state:
+        return description + "; " + _SLOT_STATES.get(next_state, f"state: {str(next_state).replace('_', ' ')}")
+    if state in ("bound", "would_assign") and not slot.get("article_id"):
+        action = slot.get("generation_action")
+        if action in (None, "wait_write_ahead"):
+            hours = cadence.get("write_ahead_hours") or 48
+            ahead = "about two days" if hours == 48 else f"{hours} hours"
+            return f"{description} (written {ahead} ahead)"
+        return description + "; " + _WRITING_ACTIONS.get(action, f"reason: {str(action).replace('_', ' ')}")
+    return description
+
+
+def _before_window_end(value: str | None, window: dict[str, str]) -> bool:
+    return in_calendar_window(value, {"from": "0001-01-01T00:00:00+00:00", "to": window["to"]})
+
+
+def _calendar_candidates(result: dict[str, Any]) -> list[dict[str, Any]]:
+    """Appointments retain their title/byline even outside the candidate page."""
+    by_article = {row.get("article_id"): row for row in result.get("candidates") or []}
+    topics = {
+        row["article_id"]: row.get("topic") or row.get("title")
+        for row in result.get("slots") or [] if row.get("article_id")
+    }
+    for appointment in result.get("appointments") or []:
+        article_id = appointment.get("article_id")
+        candidate = by_article.get(article_id) or {}
+        by_article[article_id] = {
+            **candidate,
+            "article_id": article_id,
+            "title": candidate.get("title") or appointment.get("title")
+            or topics.get(article_id) or "(untitled article)",
+            "author_name": candidate.get("author_name") or appointment.get("author_name"),
+        }
+    return list(by_article.values())
+
+
+def describe_calendar(ctx: click.Context, result: dict[str, Any]) -> str:
+    """Adapt only display rows; JSON retains the plan's original rows and fields."""
+    cadence = ctx.meta["calendar_cadence"]
+    window = ctx.meta["calendar_window"]
+    # A stopped or waiting date is not history: it stays until a person acts, as it does in `recala plan`.
+    keep_stopped = ctx.meta.get("calendar_default_start", False)
+    slots = [slot
+        for slot in result["slots"]
+        if in_calendar_window(slot.get("scheduled_at"), window)
+        or (keep_stopped and _needs_attention(slot) and _before_window_end(slot.get("scheduled_at"), window))
+    ]
+    zone = company_timezone(ctx, {**result, "cadence": cadence})
+    return calendar_view({**result, "slots": slots, "timezone": zone}, cadence=cadence)
+
+
+@click.command()
+@common_options
+@command_runner(contextual_human=describe_calendar)
+@click.option("--from", "start", type=click.DateTime(["%Y-%m-%d"]), default=None, help="First day (default today).")
+@click.option("--to", "end", type=click.DateTime(["%Y-%m-%d"]), default=None, help="Last day (default in 30 days; 93 at most).")
+def calendar(ctx: click.Context, org_flag: str | None, start: datetime | None, end: datetime | None) -> dict[str, Any]:
+    """What publishes when, and what is ready to book.
+
+    Scheduled publications by day, and what is ready to schedule."""
+    client = open_client(ctx, org_flag)
+    window = calendar_window(start, end)
+    scheduled = client.call(CALENDAR, params=window)
+    plan = optional_read(client, PUBLICATION_PLAN, params={"weeks": 2}) or {}
+    ctx.meta["calendar_window"] = window
+    ctx.meta["calendar_default_start"] = start is None
+    ctx.meta["calendar_cadence"] = plan.get("cadence") or {}
+    return planned_calendar(scheduled, plan)
+
+
+#: The authority score's parts, in the order a person weighs them, under plain names.
+_AUTHORITY_PARTS = (
+    ("geo16", "Content quality (GEO)"), ("aeo", "Answer-engine readiness"), ("seo", "Search (SEO)"),
+    ("cluster", "Topic clusters"), ("freshness", "Freshness"), ("aeo_citation", "Citations in AI answers"),
+)
+
+
+def _score(value: Any) -> str:
+    return f"{round(float(value), 1):g}"
+
+
+def describe_authority(result: dict[str, Any]) -> str:
+    total = result.get("total_score")
+    lines = [f"Authority score: {_score(total) if total is not None else 'not scored yet'}"]
+    lines += [f"  {name}: {_score(result[key])}" for key, name in _AUTHORITY_PARTS
+              if isinstance(result.get(key), (int, float))]
+    return "\n".join(lines)
+
+
+@click.group()
+def report() -> None:
+    """Reports on the company's authority."""
+
+
+@report.command("authority")
+@common_options
+@command_runner(human=lambda r: describe_authority(r))
+def authority(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """The authority score and its parts."""
+    score: dict[str, Any] = open_client(ctx, org_flag).call(AUTHORITY_SCORE)
+    return score

recala_cli/commands/refresh.py

@@ -0,0 +1,138 @@
+"""`recala refresh`: the company's auto-refresh of published articles.
+
+The API has the company-level summary (read-only: the portal shows the toggles but no route
+changes them), a per-article pause and resume, and the status of one refresh run. There is no
+route that lists runs, so ``refresh runs`` takes the run's id.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.commands.refusals import refusals_in_words
+from recala_cli.display import display_name
+from recala_cli.endpoints import ARTICLE_AUTO_REFRESH, REFRESH_STATUS, REFRESH_SUMMARY
+from recala_cli.ids import resolve_article_id, validate_id
+from recala_cli.labels import resource_label
+from recala_cli.runtime import command_runner, common_options, confirm, ignored_yes_option, open_client
+from recala_cli.views import company_timezone, moment_in
+
+RUN_NOT_FOUND = "No refresh run has that id for this company. Runs are started by a refresh from an article page."
+NEXT_STEP = "Pause or resume one article: recala refresh pause|resume <article-id>"
+
+
+def euros(cents: Any) -> str:
+    return f"{int(cents or 0) / 100:.2f} EUR"
+
+
+def describe_summary(summary: dict[str, Any]) -> str:
+    state = "on" if summary.get("auto_refresh_enabled") else "off"
+    lines = [f"Auto-refresh is {state} for this company."]
+    if summary.get("auto_refresh_enabled"):
+        per_day = int(summary.get("auto_refresh_per_day") or 0)
+        lines.append(f"Each published article is checked every {summary.get('auto_refresh_interval_days')} days, "
+                     f"up to {per_day} article{'' if per_day == 1 else 's'} a day, "
+                     f"within {euros(summary.get('monthly_cap_cents'))} a month.")
+    lines.append(f"{summary.get('articles_eligible_now', 0)} of {summary.get('articles_total', 0)} published "
+                 f"articles are due a refresh now.")
+    lines.append(f"This month: {summary.get('refreshes_this_month', 0)} refreshes, "
+                 f"{euros(summary.get('spent_this_month_cents'))} spent.")
+    lines.append(NEXT_STEP)
+    return "\n".join(lines)
+
+
+@click.group()
+def refresh() -> None:
+    """Auto-refresh of published articles.
+
+    The company-level switch is changed in the portal; here you read it and pause or resume single articles."""
+
+
+@refresh.command("show")
+@common_options
+@command_runner(human=describe_summary)
+def show(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Auto-refresh setting, what is due, spend.
+
+    Whether it is on, how often it runs, what is due now and what it cost this month."""
+    summary: dict[str, Any] = open_client(ctx, org_flag).call(REFRESH_SUMMARY)
+    return summary
+
+
+def describe_toggle(ctx: click.Context, result: dict[str, Any]) -> str:
+    verb = "paused" if result.get("auto_refresh_paused") else "on"
+    prefix = "Dry run — would set" if result.get("dry_run") else "Auto-refresh set to"
+    return f"{prefix} {verb} for {ctx.meta['result_subject']}." + (
+        " Manual refreshes still work." if result.get("auto_refresh_paused") else "")
+
+
+def set_paused(ctx: click.Context, org_flag: str | None, article_id: str, *, paused: bool, dry_run: bool) -> dict[str, Any]:
+    validate_id(article_id, "article")
+    client = open_client(ctx, org_flag)
+    full_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", full_id)
+    if dry_run:
+        return {"dry_run": True, "article_id": full_id, "auto_refresh_paused": paused}
+    confirm(ctx, client, f"{'Pause' if paused else 'Resume'} auto-refresh for {label}?")
+    with refusals_in_words(not_found="No article with that id in this company. Find it with: recala article list"):
+        changed: dict[str, Any] = client.call(ARTICLE_AUTO_REFRESH, path={"article_id": full_id},
+                                              json={"auto_refresh_paused": paused})
+    return changed
+
+
+@refresh.command("resume")
+@common_options
+@command_runner(contextual_human=describe_toggle)
+@ignored_yes_option
+@click.argument("article_id")
+@click.option("--dry-run", is_flag=True, help="Say what would change without changing it.")
+def resume(ctx: click.Context, org_flag: str | None, yes: bool, article_id: str, dry_run: bool) -> dict[str, Any]:
+    """Resume auto-refresh for one article."""
+    return set_paused(ctx, org_flag, article_id, paused=False, dry_run=dry_run)
+
+
+@refresh.command("pause")
+@common_options
+@command_runner(contextual_human=describe_toggle)
+@ignored_yes_option
+@click.argument("article_id")
+@click.option("--dry-run", is_flag=True, help="Say what would change without changing it.")
+def pause(ctx: click.Context, org_flag: str | None, yes: bool, article_id: str, dry_run: bool) -> dict[str, Any]:
+    """Pause auto-refresh for one article.
+
+    You can still refresh it by hand."""
+    return set_paused(ctx, org_flag, article_id, paused=True, dry_run=dry_run)
+
+
+def describe_run(ctx: click.Context, run: dict[str, Any]) -> str:
+    zone = company_timezone(ctx, run)
+    status = str(run.get("pipeline_status") or "unknown").replace("_", " ")
+    kind = "automatic" if run.get("trigger_type") == "auto" else "manual"
+    lines = [f"Refresh {str(run['refresh_id'])[:8]} ({kind}): {status}"
+             + (f", {run['progress_pct']}% done" if not run.get("is_terminal") and run.get("progress_pct") is not None else "")]
+    lines.append(f"Started {moment_in(run.get('started_at'), zone)}"
+                 + (f"; finished {moment_in(run['completed_at'], zone)}" if run.get("completed_at") else ""))
+    if run.get("is_terminal"):
+        lines.append(f"{run.get('sections_updated') or 0} of {run.get('sections_audited') or 0} sections updated"
+                     + (f"; new grade {run['new_evaluation_grade']}" if run.get("new_evaluation_grade") else ""))
+    elif run.get("estimated_seconds_remaining") is not None:
+        lines.append(f"About {max(1, round(int(run['estimated_seconds_remaining']) / 60))} minute(s) left.")
+    if run.get("error_message"):
+        lines.append(f"It failed: {display_name(run['error_message'])}")
+    return "\n".join(lines)
+
+
+@refresh.command("runs")
+@common_options
+@command_runner(contextual_human=describe_run)
+@click.argument("refresh_id")
+def runs(ctx: click.Context, org_flag: str | None, refresh_id: str) -> dict[str, Any]:
+    """Status of one refresh run.
+
+    Progress, sections updated and the new grade. The API has no list of runs, so give the run's id."""
+    client = open_client(ctx, org_flag)
+    with refusals_in_words(not_found=RUN_NOT_FOUND):
+        run: dict[str, Any] = client.call(REFRESH_STATUS, path={"refresh_id": refresh_id})
+    return run

recala_cli/commands/refusals.py

@@ -0,0 +1,20 @@
+"""Say a refusal in words: the API's bare "Not Found" or 409 becomes the sentence a person can act on."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+from recala_cli.errors import CliError
+
+
+@contextmanager
+def refusals_in_words(*, not_found: str | None = None, conflict: str | None = None) -> Iterator[None]:
+    """Re-raise a 404 or 409 from the API with our sentence; every other failure passes through unchanged."""
+    try:
+        yield
+    except CliError as error:
+        sentence = {404: not_found, 409: conflict}.get(error.status or 0)
+        if not sentence:
+            raise
+        raise CliError(error.exit_code, error.code, sentence, status=error.status, details=error.details) from error

recala_cli/commands/schema.py

@@ -0,0 +1,47 @@
+"""`recala schema`: the command tree and the exit codes, as data, for agents to read before acting."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli import __version__
+from recala_cli.errors import ExitCode
+from recala_cli.runtime import command_runner, json_option
+
+
+def _walk(group: click.Group, prefix: str = "") -> list[dict[str, Any]]:
+    commands = []
+    for name, command in sorted(group.commands.items()):
+        full = f"{prefix}{name}"
+        if isinstance(command, click.Group):
+            commands.extend(_walk(command, f"{full} "))
+            continue
+        commands.append({
+            "name": full,
+            "help": (command.help or "").strip().splitlines()[0] if command.help else "",
+            "arguments": [p.name for p in command.params if isinstance(p, click.Argument)],
+            "options": [
+                {"flags": list(p.opts), "required": p.required, "help": getattr(p, "help", "") or ""}
+                for p in command.params if isinstance(p, click.Option) and not p.hidden
+            ],
+        })
+    return commands
+
+
+@click.command()
+@json_option
+@command_runner(human=lambda s: "\n".join([c["name"] for c in s["commands"]] + ["", "Add --json for every flag and exit code."]))
+def schema(ctx: click.Context) -> dict[str, Any]:
+    """Every command, flag and exit code.
+
+    Add --json: it prints each command with its arguments and flags, and what each exit code means.
+    Without it, only the command names."""
+    root = ctx.find_root().command
+    assert isinstance(root, click.Group)
+    return {
+        "version": __version__,
+        "exit_codes": {str(int(code)): code.name for code in ExitCode},
+        "commands": _walk(root),
+    }

recala_cli/commands/shell.py

@@ -0,0 +1,81 @@
+"""`recala completion` and `recala update`: the two commands about the program itself, not a company."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from collections.abc import Callable
+
+import click
+from click.shell_completion import get_completion_class
+
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, json_option
+
+SHELLS = ("bash", "zsh", "fish")
+UV_UPGRADE = ["uv", "tool", "install", "--force", "recala-cli"]
+PIPX_UPGRADE = ["pipx", "install", "--force", "recala-cli"]
+
+
+@click.command()
+@click.argument("shell", type=click.Choice(SHELLS))
+@click.pass_context
+def completion(ctx: click.Context, shell: str) -> None:
+    """Print the tab-completion script for your shell.
+
+    \b
+    Bash: add this line to ~/.bashrc
+        eval "$(recala completion bash)"
+    Zsh: add this line to ~/.zshrc
+        eval "$(recala completion zsh)"
+    Fish: save the script once
+        recala completion fish > ~/.config/fish/completions/recala.fish
+
+    Open a new terminal afterwards. Completion needs no sign-in and makes no request.
+    """
+    root = ctx.find_root().command
+    script = get_completion_class(shell)(root, {}, "recala", "_RECALA_COMPLETE").source()
+    click.echo(script)
+
+
+def installed_by(prefix: str) -> str | None:
+    """"uv" or "pipx" when this program lives in the private environment of that tool; else None."""
+    parts = prefix.replace("\\", "/").split("/")
+    if "tools" in parts and "uv" in parts:
+        return "uv"
+    if "venvs" in parts and "pipx" in parts:
+        return "pipx"
+    return None
+
+
+def _run_command(command: list[str]) -> int:
+    try:
+        # The installer's own summary goes to stderr: stdout carries only Recala's answer (one JSON document with --json).
+        return subprocess.run(command, check=False, stdout=sys.stderr.fileno()).returncode
+    except FileNotFoundError:
+        return 127
+
+
+@click.command()
+@json_option
+@click.option("--dry-run", is_flag=True, help="Only print the command that would run.")
+@command_runner(human=lambda result: result["message"])
+def update(ctx: click.Context, dry_run: bool) -> dict[str, object]:
+    """Install the newest CLI with uv or pipx.
+
+    Uses the tool that installed Recala. When the installer cannot be recognised, it prints the exact command instead of guessing."""
+    seams = ctx.find_root().obj
+    manager = installed_by(seams.get("install_prefix") or sys.prefix)
+    command = {"uv": UV_UPGRADE, "pipx": PIPX_UPGRADE}.get(manager or "")
+    if command is None:
+        return {"updated": False, "command": None, "message":
+                f"Recala was not installed with uv or pipx, so it will not guess. Run one of:\n"
+                f"  {' '.join(UV_UPGRADE)}\n  {' '.join(PIPX_UPGRADE)}"}
+    text = " ".join(command)
+    if dry_run:
+        return {"updated": False, "command": text, "message": f"Would run: {text}"}
+    run: Callable[[list[str]], int] = seams.get("run_command") or _run_command
+    click.echo(f"Running: {text}", err=True)
+    if run(command) != 0:
+        raise CliError(ExitCode.ERROR, "update_failed", f"The update did not finish. Run it yourself: {text}")
+    return {"updated": True, "command": text, "message": "Recala is up to date. Run `recala --version` to see which."}