recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/languages.py

@@ -0,0 +1,119 @@
+"""`recala company languages`: the languages a company publishes in besides its main one.
+
+The extra languages are the setting that starts translations (organizations.extra_languages):
+a new article is translated into each of them. The route is the portal's Settings > Languages.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.commands.refusals import refusals_in_words
+from recala_cli.endpoints import LANGUAGES_SET, LANGUAGES_SHOW
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, common_options, confirm, ignored_yes_option, open_client
+
+NOT_ENABLED = "Languages are not switched on for this company yet, so there is nothing to change."
+CHANGED = "The languages changed while you were editing them. Run `recala company languages show` and try again."
+
+
+def _name(code: str, languages: dict[str, Any]) -> str:
+    names = {item["code"]: item["name"] for item in languages.get("supported") or []}
+    return f"{names.get(code, code)} ({code})"
+
+
+def describe_languages(languages: dict[str, Any]) -> str:
+    extras = languages.get("extras") or []
+    prefix = "Dry run — nothing saved\n" if languages.get("dry_run") else ""
+    lines = [f"{prefix}Main language: {_name(languages['main'], languages)}"]
+    if extras:
+        lines.append("Also translated into: " + ", ".join(_name(code, languages) for code in extras))
+        lines.append("New articles are translated into these languages.")
+    else:
+        lines.append("No extra languages. Add one with: recala company languages add <code>")
+    if languages.get("max_extra") is not None:
+        left = max(0, int(languages["max_extra"]) - len(extras))
+        lines.append(f"{left} more extra language{'' if left == 1 else 's'} allowed.")
+    site = [code for code in languages.get("site_languages") or [] if code not in extras]
+    if site:
+        lines.append("Found on your website: " + ", ".join(_name(code, languages) for code in site))
+    return "\n".join(lines)
+
+
+@click.group()
+def languages() -> None:
+    """The languages your articles are translated into.
+
+    Adding a language translates new articles into it. Changing it needs an owner session."""
+
+
+@languages.command("show")
+@common_options
+@command_runner(human=describe_languages)
+def show(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Show the main language and the extra languages."""
+    with refusals_in_words(not_found=NOT_ENABLED):
+        current: dict[str, Any] = open_client(ctx, org_flag).call(LANGUAGES_SHOW)
+    return current
+
+
+def change_extras(ctx: click.Context, org_flag: str | None, code: str, *, adding: bool, dry_run: bool) -> dict[str, Any]:
+    code = code.strip().lower()
+    client = open_client(ctx, org_flag)
+    with refusals_in_words(not_found=NOT_ENABLED):
+        current: dict[str, Any] = client.call(LANGUAGES_SHOW)
+    extras = list(current.get("extras") or [])
+    known = {item["code"] for item in current.get("supported") or []}
+    if adding and known and code not in known:
+        raise CliError(ExitCode.USAGE, "unsupported_language",
+                       f"{code} is not a supported language. Choose one of: {', '.join(sorted(known))}.")
+    if adding and code == current.get("main"):
+        raise CliError(ExitCode.CONFLICT, "main_language",
+                       f"{_name(code, current)} is already the main language; extra languages are other ones.")
+    if adding and code in extras:
+        raise CliError(ExitCode.CONFLICT, "language_unchanged",
+                       f"New articles are already translated into {_name(code, current)}.")
+    if adding and current.get("max_extra") is not None and len(extras) >= int(current["max_extra"]):
+        raise CliError(ExitCode.CONFLICT, "language_limit",
+                       f"This company already has {len(extras)} extra languages, the most it can have. "
+                       f"Remove one first: recala company languages remove <code>")
+    if not adding and code not in extras:
+        raise CliError(ExitCode.CONFLICT, "language_unchanged",
+                       f"{_name(code, current)} is not one of the extra languages "
+                       f"({', '.join(extras) or 'there are none'}).")
+    wanted = extras + [code] if adding else [item for item in extras if item != code]
+    if dry_run:
+        return {**current, "extras": wanted, "dry_run": True}
+    action = "Translate new articles into" if adding else "Stop translating new articles into"
+    confirm(ctx, client, f"{action} {_name(code, current)}?")
+    with refusals_in_words(not_found=NOT_ENABLED, conflict=CHANGED):
+        saved: dict[str, Any] = client.call(LANGUAGES_SET, json={"extras": wanted})
+    return saved
+
+
+@languages.command("add")
+@common_options
+@command_runner(human=describe_languages)
+@ignored_yes_option
+@click.argument("code")
+@click.option("--dry-run", is_flag=True, help="Show the resulting languages without saving.")
+def add(ctx: click.Context, org_flag: str | None, yes: bool, code: str, dry_run: bool) -> dict[str, Any]:
+    """Add an extra language: new articles are translated into it.
+
+    CODE is a language code such as en, es, pt, de or fr."""
+    return change_extras(ctx, org_flag, code, adding=True, dry_run=dry_run)
+
+
+@languages.command("remove")
+@common_options
+@command_runner(human=describe_languages)
+@ignored_yes_option
+@click.argument("code")
+@click.option("--dry-run", is_flag=True, help="Show the resulting languages without saving.")
+def remove(ctx: click.Context, org_flag: str | None, yes: bool, code: str, dry_run: bool) -> dict[str, Any]:
+    """Stop translating new articles into a language.
+
+    Translations already published stay as they are."""
+    return change_extras(ctx, org_flag, code, adding=False, dry_run=dry_run)

recala_cli/commands/monthly_report.py

@@ -0,0 +1,152 @@
+"""`recala report monthly`: the monthly client report, and a link to share it.
+
+``report monthly`` shows the month; ``report monthly share`` makes a link anyone can open
+(revocable in the portal), so it asks first and is created only on an explicit yes.
+"""
+
+from __future__ import annotations
+
+import calendar
+import re
+from datetime import datetime, timezone
+from typing import Any
+
+import click
+
+from recala_cli import config
+from recala_cli.commands.refusals import refusals_in_words
+from recala_cli.display import display_name
+from recala_cli.endpoints import REPORT_MONTHLY, REPORT_SHARE_CREATE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, yes_option
+from recala_cli.search_numbers import counted
+
+NOT_ENABLED = "Monthly reports are not switched on for this company yet."
+NO_SECTIONS = ("This month has nothing to report yet (no search, answer, publishing or authority data), "
+               "so there is nothing to share. Try a month with articles published.")
+_MONTH = re.compile(r"(\d{4})-(0[1-9]|1[0-2])")
+
+
+def this_month() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m")
+
+
+def valid_month(value: str | None) -> str:
+    month = value or this_month()
+    if not _MONTH.fullmatch(month):
+        raise click.BadParameter("Use YYYY-MM, for example 2026-10.", param_hint="--month")
+    return month
+
+
+def month_title(month: str) -> str:
+    return f"{calendar.month_name[int(month[5:7])]} {month[:4]}"
+
+
+def _value(node: Any) -> Any:
+    return node.get("value") if isinstance(node, dict) else None
+
+
+def _change(node: Any) -> str:
+    change = _value((node or {}).get("change")) if isinstance(node, dict) else None
+    return f" ({change:+g} on the month before)" if isinstance(change, (int, float)) else ""
+
+
+def _search_lines(search: dict[str, Any]) -> list[str]:
+    lines = []
+    for key, noun in (("clicks", "click"), ("impressions", "impression")):
+        current = _value((search.get(key) or {}).get("current"))
+        if current is not None:
+            lines.append(f"  Google Search: {counted(current, noun)}{_change(search.get(key))}")
+    return lines
+
+
+def _answer_lines(answers: dict[str, Any]) -> list[str]:
+    lines = []
+    for engine in (answers.get("engines") or {}).values():
+        owned = _value(engine.get("owned"))
+        if owned is not None:
+            lines.append(f"  {engine.get('display_name') or 'An answer engine'}: your site answers {owned} tracked "
+                         f"question{'' if owned == 1 else 's'}")
+    return lines
+
+
+def describe_report(result: dict[str, Any]) -> str:
+    report = result.get("report") or {}
+    month = str(report.get("month") or "")
+    lines = [f"Monthly report: {month_title(month) if _MONTH.fullmatch(month) else month}"]
+    headline = (report.get("headline") or {}).get("text")
+    if headline:
+        lines.append(display_name(headline))
+    delivered = report.get("work_delivered") or {}
+    published, scheduled = (_value((delivered.get(key) or {}).get("count")) for key in ("published", "scheduled_next"))
+    sections = _search_lines(report.get("search") or {}) + _answer_lines(report.get("ai_answers") or {})
+    if published is not None:
+        sections.append(f"  Articles published: {published}")
+    if scheduled:
+        sections.append(f"  Articles scheduled next: {scheduled}")
+    authority = report.get("authority") or {}
+    if _value(authority.get("latest")) is not None:
+        sections.append(f"  Authority score: {_value(authority['latest']):g}{_change(authority)}")
+    lines.extend(sections or ["Nothing to report for this month yet."])
+    lines.append(f"Share it: recala report monthly share --month {month} --yes" if month else "")
+    return "\n".join(line for line in lines if line)
+
+
+class MonthlyGroup(click.Group):
+    """`report monthly [--month M]` shows the report; `report monthly share` makes the link."""
+
+    def parse_args(self, ctx: click.Context, args: list[str]) -> list[str]:
+        if not args or (args[0] not in self.commands and args[0] not in ("--help", "-h")):
+            args = ["show", *args]
+        return super().parse_args(ctx, args)
+
+
+@click.group("monthly", cls=MonthlyGroup)
+def monthly() -> None:
+    """The monthly client report and its share link.
+
+    Search, answers, work delivered and authority. `recala report monthly --month 2026-10` shows it; `recala report monthly share` makes a link to send."""
+
+
+@monthly.command("show", hidden=True)
+@common_options
+@command_runner(human=describe_report)
+@click.option("--month", default=None, help="The month, YYYY-MM (default: this month).")
+def show(ctx: click.Context, org_flag: str | None, month: str | None) -> dict[str, Any]:
+    """Show the report for a month."""
+    chosen = valid_month(month)
+    with refusals_in_words(not_found=NOT_ENABLED):
+        report: dict[str, Any] = open_client(ctx, org_flag).call(REPORT_MONTHLY, params={"month": chosen})
+    return report
+
+
+def describe_share(result: dict[str, Any]) -> str:
+    if result.get("dry_run"):
+        return (f"Dry run — would create a link to the {month_title(result['month'])} report. "
+                "Anyone with the link could read it; nothing was created.")
+    return (f"Link to the {month_title(result['month'])} report (anyone who has it can read it):\n{result['url']}\n"
+            "Revoke it from the report page in the portal.")
+
+
+@monthly.command("share")
+@common_options
+@command_runner(human=describe_share)
+@yes_option
+@click.option("--month", default=None, help="The month, YYYY-MM (default: this month).")
+@click.option("--dry-run", is_flag=True, help="Check the report can be shared without creating a link.")
+def share(ctx: click.Context, org_flag: str | None, yes: bool, month: str | None, dry_run: bool) -> dict[str, Any]:
+    """Create a link to the monthly report.
+
+    Anyone with the link can read the report, so it is made only after you confirm (--yes with a publish key)."""
+    chosen = valid_month(month)
+    client = open_client(ctx, org_flag)
+    if dry_run:
+        with refusals_in_words(not_found=NOT_ENABLED):
+            report = client.call(REPORT_MONTHLY, params={"month": chosen})
+        if not any((report.get("report") or {}).get(name) for name in ("search", "ai_answers", "work_delivered", "authority")):
+            raise CliError(ExitCode.CONFLICT, "report_has_no_sections", NO_SECTIONS)
+        return {"dry_run": True, "month": chosen}
+    confirm(ctx, client, f"Create a link anyone can use to read the {month_title(chosen)} report?", publishes=True, yes=yes)
+    with refusals_in_words(not_found=NOT_ENABLED, conflict=NO_SECTIONS):
+        created: dict[str, Any] = client.call(REPORT_SHARE_CREATE, json={"month": chosen})
+    return {**created, "url": f"{config.web_url()}{created['path']}"}

recala_cli/commands/notifications.py

@@ -0,0 +1,106 @@
+"""`recala notifications`: what the portal's bell shows, and marking it read.
+
+The API lists the unread notifications of the company, newest first (at most 20).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.display import display_name
+from recala_cli.endpoints import NOTIFICATION_READ, NOTIFICATIONS_LIST, NOTIFICATIONS_READ_ALL
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.ids import is_short_id, matching_prefix
+from recala_cli.runtime import command_runner, common_options, confirm, ignored_yes_option, open_client
+from recala_cli.views import company_timezone, moment_in
+
+NEXT_STEP = "Mark them read with: recala notifications read --all"
+#: The API lists at most this many unread notifications and read-all marks every one, so a full list is no count.
+LISTED_AT_MOST = 20
+
+
+def describe_notifications(ctx: click.Context, result: dict[str, Any]) -> str:
+    rows = result.get("notifications") or []
+    if not rows:
+        return "No unread notifications."
+    zone = company_timezone(ctx, result)
+    lines = [f"{len(rows)} unread notification{'' if len(rows) == 1 else 's'}, newest first:"]
+    for row in rows:
+        title = display_name(row.get("title")) or "Notification"
+        message = display_name(row.get("message"))
+        when = moment_in(row.get("created_at"), zone)
+        lines.append(f"  {title}  [{str(row['id'])[:8]}]  {when}" + (f"\n    {message}" if message else ""))
+    lines.append(NEXT_STEP)
+    return "\n".join(lines)
+
+
+@click.group()
+def notifications() -> None:
+    """The company's notifications."""
+
+
+@notifications.command("list")
+@common_options
+@command_runner(contextual_human=describe_notifications)
+def list_notifications(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Unread notifications, newest first."""
+    unread: dict[str, Any] = open_client(ctx, org_flag).call(NOTIFICATIONS_LIST)
+    return unread
+
+
+def describe_read(result: dict[str, Any]) -> str:
+    if result.get("dry_run"):
+        return f"Dry run — would mark {_how_many(result['marked_read'])} as read."
+    return f"Marked {_how_many(result['marked_read'])} as read."
+
+
+def _how_many(count: int | None) -> str:
+    """None: the list was full, so the count is unknown (read-all marks every unread one)."""
+    if count is None:
+        return f"every unread notification ({LISTED_AT_MOST} or more)"
+    return f"{count} notification{'' if count == 1 else 's'}"
+
+
+def pick_unread(rows: list[dict[str, Any]], selector: str) -> str:
+    if not is_short_id(selector) and len(selector) != 36:
+        raise CliError(ExitCode.USAGE, "invalid_notification_id",
+                       f"{selector} is not a notification id. Use the 8-character id from recala notifications list.")
+    matches = matching_prefix(rows, selector)
+    if len(matches) != 1:
+        raise CliError(ExitCode.NOT_FOUND if not matches else ExitCode.USAGE,
+                       "notification_not_found" if not matches else "notification_ambiguous",
+                       f"No unread notification starts with {selector}. See: recala notifications list" if not matches
+                       else f"Several notifications start with {selector}; use more characters.")
+    return str(matches[0]["id"])
+
+
+@notifications.command("read")
+@common_options
+@command_runner(human=describe_read)
+@ignored_yes_option
+@click.argument("notification_id", required=False)
+@click.option("--all", "everything", is_flag=True, help="Mark every unread notification as read.")
+@click.option("--dry-run", is_flag=True, help="Say what would be marked without marking it.")
+def read(ctx: click.Context, org_flag: str | None, yes: bool, notification_id: str | None, everything: bool,
+         dry_run: bool) -> dict[str, Any]:
+    """Mark one notification (by its 8-character id) or all of them as read."""
+    if bool(notification_id) == everything:
+        raise click.UsageError("Give one notification id, or --all.")
+    client = open_client(ctx, org_flag)
+    rows = (client.call(NOTIFICATIONS_LIST) or {}).get("notifications") or []
+    chosen = rows if everything else [row for row in rows if row["id"] == pick_unread(rows, notification_id or "")]
+    outcome: dict[str, Any] = {"marked_read": len(chosen), "ids": [str(row["id"]) for row in chosen]}
+    if everything and len(chosen) >= LISTED_AT_MOST:
+        outcome = {"marked_read": None, "at_least": LISTED_AT_MOST, "all_unread": True}
+    if dry_run:
+        return {**outcome, "dry_run": True}
+    if not chosen:
+        return outcome
+    confirm(ctx, client, f"Mark {_how_many(outcome['marked_read'])} as read?")
+    if everything:
+        client.call(NOTIFICATIONS_READ_ALL)
+    else:
+        client.call(NOTIFICATION_READ, path={"notification_id": outcome["ids"][0]})
+    return outcome

recala_cli/commands/onboard.py

@@ -0,0 +1,237 @@
+"""Interactive company setup through topics. Non-interactive callers get a read-only checklist."""
+from __future__ import annotations
+
+import sys
+from typing import Any
+
+import click
+
+from recala_cli import auth, config, ui
+from recala_cli.client import RecalaClient
+from recala_cli.commands.auth import sign_in
+from recala_cli.commands.connect import connect_sanity, connect_wordpress
+from recala_cli.commands.org import create_or_fill, scan_website
+from recala_cli.commands.reads import add_person, person_body
+from recala_cli.commands.topics import scout_topics
+from recala_cli.confirm import is_interactive
+from recala_cli.display import display_name, human_data
+from recala_cli.endpoints import CREDITS_SUMMARY, ONBOARDING_COMPLETE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.onboarding import (
+    STEP_KEYS,
+    STEPS,
+    Facts,
+    auto_run_summary,
+    checklist_rows,
+    evaluate,
+    gather,
+    mark,
+    next_step,
+)
+from recala_cli.output import notify
+from recala_cli.prompts import ask, choose
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, accepted_yes_option, dry_run_option, selected_org
+from recala_cli.views import pay_link_step, credit_lines
+
+
+def _company(ctx: click.Context, client: RecalaClient, facts: Facts) -> None:
+    memberships = (facts.me or {}).get("memberships") or []
+    existing = [m for m in memberships if m.get("website_url")]
+    if existing:
+        options = [(m["org_id"], f"{m['name']} ({m['website_url']})") for m in existing]
+        picked = choose(ctx, [*options, ("new", "A new company")], label="Which company?", flag="--org", default="new")
+        if picked != "new":
+            config.set_active_org(picked)
+            client.org_id = picked
+            return
+    name = ask(ctx, None, label="Company name", flag="--name")
+    website = ask(ctx, None, label="Website (https://...)", flag="--website")
+    language = choose(ctx, [("es", "Español (es)"), ("en", "English (en)")],
+                      label="Article language", flag="--language", default="es")
+    market = ask(ctx, None, label="Country it sells in (ES, US, ...)", flag="--market").upper()
+    create_or_fill(ctx, client, name=name, website=website, language=language, market=market)
+
+
+def _scan(ctx: click.Context, client: RecalaClient, facts: Facts) -> None:
+    scan_website(ctx, client, website=None)
+
+
+def _authors(ctx: click.Context, client: RecalaClient, facts: Facts) -> None:
+    notify("  Every article is signed by a named person.")
+    name = ask(ctx, None, label="Author's full name", flag="--name")
+    role = ask(ctx, None, label="Role (e.g. Founder)", flag="--role")
+    link = ask(ctx, None, label="Public bio/profile link (https://...)", flag="--bio-link")
+    add_person(ctx, client, person_body(name, role, (link,), "", "", ()))
+
+
+def _cms(ctx: click.Context, client: RecalaClient, facts: Facts) -> None:
+    provider = choose(ctx, [("sanity", "Sanity"), ("wordpress", "WordPress")], label="CMS provider",
+                      flag="--provider", default="sanity")
+    if provider == "sanity":
+        connect_sanity(ctx, client)
+    else:
+        connect_wordpress(ctx, client, wordpress_com=click.confirm("  Is it hosted on WordPress.com?", default=False, err=True))
+
+
+def _plan(ctx: click.Context, client: RecalaClient, facts: Facts) -> None:
+    if client is None:
+        raise CliError(ExitCode.NOT_AUTHENTICATED, "not_authenticated", "Sign in first: recala login")
+    if not client.org_id:
+        raise CliError(ExitCode.CONFLICT, "org_not_selected", "Select a company with --org or recala company use <id>.")
+    if facts.summary is None or "plan" in facts.refusals:
+        try:
+            facts.summary = client.call(CREDITS_SUMMARY)
+        except CliError as error:
+            if error.exit_code == ExitCode.FORBIDDEN:
+                raise CliError(ExitCode.FORBIDDEN, error.code,
+                               "Cannot read the plan. This credential needs the billing:read scope.",
+                               status=error.status) from error
+            if error.exit_code == ExitCode.NOT_FOUND:
+                raise CliError(ExitCode.UNAVAILABLE, "plan_unavailable", "The plan could not be read. Try again shortly.") from error
+            raise
+    if not facts.summary or not facts.summary.get("plan"):
+        raise CliError(ExitCode.UNAVAILABLE, "plan_unavailable", "The plan could not be read. Try again shortly.")
+    if next(step for step in STEPS if step.key == "plan").check(facts)[0]:
+        summary = facts.summary or {}
+        name = summary.get("plan_name") or summary.get("plan_key") or summary.get("plan")
+        notify(f"  plan: {display_name(name)} active")
+        return
+    raise CliError(ExitCode.CONFLICT, "human_payment_required",
+                   f"Human payment required: {pay_link_step()}, then run recala onboard again. "
+                   "This command does not purchase a plan.")
+
+
+def _topics(ctx: click.Context, client: RecalaClient, facts: Facts) -> None:
+    result = scout_topics(ctx, client)
+    notify(f"  Scout complete: {result.get('found', 0)} topics found.")
+
+
+RUNNERS = {"company": _company, "scan": _scan, "authors": _authors, "cms": _cms, "plan": _plan, "topics": _topics}
+
+
+def _client(ctx: click.Context, org_flag: str | None) -> RecalaClient | None:
+    if auth.credential_kind() == "none":
+        return None
+    return open_client(ctx, org_flag, require_org=bool(selected_org(ctx, org_flag)))
+
+
+def _report(facts: Facts, *, agent: bool = False) -> dict[str, Any]:
+    rows = evaluate(facts, agent=agent)
+    return {"org_id": facts.org.get("id"), "company": facts.org.get("name"), "plan": facts.summary,
+            "onboarding_completed": bool(facts.org.get("onboarding_completed")),
+            "steps": rows, "missing": [row for row in rows if not row["done"]], "next": next_step(rows),
+            "done": sum(1 for row in rows if row["done"]), "total": len(rows),
+            **({"summary": auto_run_summary(facts)} if agent else {})}
+
+
+def _complete_setup(ctx: click.Context, client: RecalaClient, facts: Facts, *, refill: bool = False) -> None:
+    if facts.org.get("onboarding_completed") and not refill:
+        return
+    confirm(ctx, client, "Complete company setup and fill Up next from the topics?")
+    client.token = auth.bearer_token(client)
+    client.call(ONBOARDING_COMPLETE)
+
+
+def describe_onboarding(report: dict[str, Any]) -> str:
+    report = human_data(report)
+    lines = ["", *credit_lines(report.get("plan") or {}, None, None), "",
+             ui.checklist(checklist_rows(report["steps"]), style=ui.Style.for_stream(sys.stdout)), ""]
+    upcoming = report.get("next")
+    if upcoming:
+        lines.append(f"  Next: {upcoming['title']}  ->  {upcoming['command']}")
+        lines.append("  Run recala onboard in a terminal to continue. Agents can run each step's command.")
+    if not upcoming or (report.get("onboarding_completed") and all(row["key"] == "plan" for row in report["missing"])):
+        lines.append(f"  Company setup complete: {report.get('company')}. See: recala status")
+    return "\n".join(lines)
+
+
+def _run_journey(ctx: click.Context, org_flag: str | None, only: str | None) -> dict[str, Any]:
+    style = ui.Style.for_stream()
+    ui.banner("Let's set up your company on Recala", style=style)
+    client = _client(ctx, org_flag)
+    if client is None:
+        sign_in(ctx, within_onboarding=True)
+        client = _client(ctx, org_flag)
+    if client is None:
+        raise CliError(ExitCode.NOT_AUTHENTICATED, "sign_in_required", "Sign in first: recala login")
+    facts = gather(client)
+    notify(describe_onboarding(_report(facts)))
+    for index, step in enumerate(STEPS, start=1):
+        done, _ = step.check(facts)
+        if step.key == "login" or (only and step.key != only) or (done and not only):
+            continue
+        # A completed setup may need billing attention, reported in the checklist.
+        # Explicit --step plan still validates billing with its existing exit codes.
+        if step.key == "plan" and facts.org.get("onboarding_completed") and not only:
+            continue
+        notify(f"\nStep {index} of {len(STEPS)}  {step.title}")
+        RUNNERS[step.key](ctx, client, facts)
+        client.token = auth.bearer_token(client)
+        facts = gather(client)
+        finished, detail = step.check(facts)
+        if not finished:
+            raise CliError(ExitCode.CONFLICT, "step_incomplete", f"{step.title} is still incomplete. {step.command}")
+        notify(f"  Done: {step.title}: {display_name(detail)}")
+        if step.key == "company":
+            notify("\n".join(credit_lines(facts.summary or {}, None, None)))
+    report = _report(facts)
+    if not report["missing"] and only != "plan" and not facts.org.get("onboarding_completed"):
+        _complete_setup(ctx, client, facts)
+    return report
+
+
+@click.command()
+@common_options
+@command_runner(human=describe_onboarding)
+@click.option("--apply", "apply_step", is_flag=True, help="Apply the complete step, including in JSON mode.")
+@click.option("--step", "only", type=click.Choice((*STEP_KEYS[1:], "complete")), default=None, help="Run just this step (again).")
+@accepted_yes_option
+@dry_run_option
+def onboard(ctx: click.Context, org_flag: str | None, only: str | None, apply_step: bool) -> dict[str, Any]:
+    """Guided setup: company, site, author, CMS, topics.
+
+    Creates a company (es/en), reads its site, adds the signing author, connects its CMS and scouts topics.
+
+    Resumable with y/n/a confirmations. A human enters the hidden CMS token and pays for Go/Self-serve separately.
+    --json reports state; --step complete --apply saves setup. The report guides an agent through topic approval, cadence and automatic approval.
+    Without a terminal, reports missing steps; --step plan checks active billing.
+    """
+    return _onboard(ctx, org_flag, only, apply_step)
+
+
+def _onboard(ctx: click.Context, org_flag: str | None, only: str | None, apply_step: bool = False) -> dict[str, Any]:
+    agent = bool(ctx.find_root().obj.get("as_json"))
+    if apply_step and only != "complete":
+        raise CliError(ExitCode.USAGE, "invalid_step", "--apply requires --step complete.")
+    if only == "complete" and (apply_step or not agent):
+        client = open_client(ctx, org_flag)
+        facts = gather(client, agent=apply_step)
+        rows = evaluate(facts, agent=apply_step)
+        prerequisites = rows[:next(i for i, row in enumerate(rows) if row["key"] == "complete")] if apply_step else rows
+        missing = next_step(prerequisites)
+        if missing:
+            raise CliError(ExitCode.CONFLICT, "setup_incomplete",
+                           f"{missing['title']} must finish first. Run recala onboard --json for the next action.")
+        _complete_setup(ctx, client, facts, refill=apply_step)
+        verified = gather(client, agent=apply_step or agent)
+        before = _report(facts, agent=True)["next"] if apply_step else None
+        after = _report(verified, agent=True)["next"] if apply_step else None
+        stalled_refill = (before and after and before["key"] == after["key"] == "autorun"
+                          and before["command"] == after["command"]
+                          and ("--step complete" in before["command"] or facts.progress.get("completion_not_saved")))
+        if not verified.org.get("onboarding_completed") or stalled_refill:
+            message = ("Up next is still empty after refreshing setup; the server did not confirm progress."
+                       if stalled_refill else
+                       "The completion command returned but the server still reports onboarding_completed false.")
+            from recala_cli.onboarding import completion_state
+            mark(str(client.org_id), completion_not_saved=message, completion_state=completion_state(verified))
+            raise CliError(ExitCode.CONFLICT, "completion_not_saved", message)
+        mark(str(client.org_id), completion_not_saved=None, completion_state=None)
+        return _report(verified, agent=agent)
+    if is_interactive(ctx) and only != "plan":
+        return _run_journey(ctx, org_flag, only)
+    client = _client(ctx, org_flag)
+    facts = gather(client, agent=agent)
+    if only == "plan":
+        _plan(ctx, client, facts)
+    return _report(facts, agent=agent)