agent-tool-openproject-cli 0.2.1__py3-none-any.whl

opcli/commands/comments.py

@@ -0,0 +1,90 @@
+"""Work-package comments (activities): list, add, edit.
+
+OpenProject stores comments as *activities*. The collection is fetched by work
+package id; edits target the activity id (from each entry's self link). There is
+no delete-comment endpoint in API v3.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import hal, serialize
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ActID", "id"),
+    ("User", lambda r: (r.get("user") or {}).get("name")),
+    ("When", "createdAt"),
+    ("Comment", "comment"),
+]
+
+
+@app.command("list")
+def list_comments(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    comments_only: bool = typer.Option(True, "--comments-only/--all-activity", help="Only entries with a comment."),
+) -> None:
+    """List activities/comments for a work package (oldest first)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    activities = client.collect(f"work_packages/{wp_id}/activities")
+    rows = []
+    name_cache: dict[int, str] = {}
+    for a in activities:
+        s = serialize.comment(a)
+        if comments_only and not (s.get("comment") or "").strip():
+            continue
+        # activity user links carry no title on some versions — resolve once.
+        user = s.get("user")
+        if user and user.get("id") and not user.get("name"):
+            uid = user["id"]
+            if uid not in name_cache:
+                try:
+                    name_cache[uid] = client.get(f"users/{uid}").get("name")
+                except Exception:
+                    name_cache[uid] = None
+            user["name"] = name_cache[uid]
+        rows.append(s)
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no comments)")
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    text: str = typer.Argument(..., help="Comment body (markdown)."),
+    notify: bool = typer.Option(False, "--notify/--no-notify", help="Send notifications (default off)."),
+) -> None:
+    """Add a comment (markdown) to a work package.
+
+    Example: openproject comment add 42 "Deployed to **staging** — please retest." --notify
+    """
+    obj = ctx_obj(ctx)
+    doc = obj.client().post(
+        f"work_packages/{wp_id}/activities",
+        json={"comment": {"raw": text}},
+        params={"notify": str(notify).lower()},
+    )
+    obj.emitter.emit(serialize.comment(doc))
+
+
+@app.command()
+def edit(
+    ctx: typer.Context,
+    activity_id: int = typer.Argument(..., help="Activity id (from `comment list`)."),
+    text: str = typer.Argument(..., help="New comment body."),
+) -> None:
+    """Edit a comment. The id is the ACTIVITY id (from `comment list`), not the work-package id.
+
+    Example: openproject comment list 42   # find the activity id, then:
+             openproject comment edit 137 "Corrected note."
+    """
+    obj = ctx_obj(ctx)
+    # The activity PATCH endpoint expects `comment` as a plain string (unlike the
+    # POST add endpoint, which takes a {"raw": ...} Formattable).
+    doc = obj.client().patch(f"activities/{activity_id}", json={"comment": text})
+    obj.emitter.emit(serialize.comment(doc))

opcli/commands/costs.py

@@ -0,0 +1,205 @@
+"""Per-person time & cost reporting for monthly invoicing.
+
+Reality check (from the API research): OpenProject's API v3 exposes **no**
+hourly rates and **no** cost-report endpoints. The only reliable, per-person
+figures come from summing ``time_entries`` client-side. So this report pulls the
+time bookings for a period, groups them by person (and project), sums the hours,
+and — if you supply a rate table — multiplies to get billable amounts.
+
+Rate table (JSON) format::
+
+    {
+      "currency": "EUR",
+      "default": 90,
+      "users":    { "admin": 120, "jane.doe": 100 },
+      "projects": { "demo-project": { "default": 100, "admin": 110 } }
+    }
+
+User keys may be a login, a full name, or a numeric id. Project keys may be an
+identifier or name. Most specific wins: project+user → project default → user → default.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+
+from .. import hal
+from ..duration import iso_to_hours
+from ..errors import OpError
+from ._shared import ctx_obj
+from .time_entries import query_time_entries
+
+app = typer.Typer(no_args_is_help=True)
+
+
+def _load_rates(path: Path | None) -> dict | None:
+    if path is None:
+        return None
+    if not path.exists():
+        raise OpError(f"rates file not found: {path}")
+    try:
+        return json.loads(path.read_text())
+    except json.JSONDecodeError as exc:
+        raise OpError(f"invalid rates JSON: {exc}") from exc
+
+
+def _rate_for(rates: dict, user_keys: list[str], project_keys: list[str]) -> float | None:
+    # Keys are ordered by priority (most specific first) so the result is
+    # deterministic when a rate table has overlapping keys.
+    if not rates:
+        return None
+    projects = rates.get("projects", {})
+    for pk in project_keys:
+        if pk in projects:
+            pconf = projects[pk]
+            if isinstance(pconf, dict):
+                for uk in user_keys:
+                    if uk in pconf:
+                        return float(pconf[uk])
+                if "default" in pconf:
+                    return float(pconf["default"])
+            else:
+                return float(pconf)
+    users = rates.get("users", {})
+    for uk in user_keys:
+        if uk in users:
+            return float(users[uk])
+    if "default" in rates:
+        return float(rates["default"])
+    return None
+
+
+@app.command()
+def report(
+    ctx: typer.Context,
+    month: str = typer.Option(None, "--month", help="Month YYYY-MM (sets the date range)."),
+    frm: str = typer.Option(None, "--from", help="Start date YYYY-MM-DD."),
+    to: str = typer.Option(None, "--to", help="End date YYYY-MM-DD."),
+    user: str = typer.Option(None, "--user", "-u", help="Restrict to one user (login/name/id or 'me')."),
+    project: str = typer.Option(None, "--project", "-P", help="Restrict to one project."),
+    rates: Path = typer.Option(None, "--rates", help="JSON rate table for billable amounts."),
+    by_project: bool = typer.Option(True, "--by-project/--no-by-project", help="Break each person down by project."),
+) -> None:
+    """Summarise hours (and billable cost) per person for a period — for invoicing."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    rate_table = _load_rates(rates)
+
+    entries = query_time_entries(client, user=user, project=project, frm=frm, to=to, month=month, desc=False, limit=None)
+
+    # cache user + project details so rate keys can match login/name/id and
+    # project identifier/name/id (the rate table may key by any of them).
+    user_cache: dict[int, dict] = {}
+    project_cache: dict[int, dict] = {}
+
+    def user_info(entry) -> dict:
+        uid = hal.link_id(entry, "user")
+        if uid not in user_cache:
+            name = hal.link_title(entry, "user")
+            info = {"id": uid, "name": name, "login": None}
+            try:
+                u = client.get(f"users/{uid}")
+                info["login"] = u.get("login")
+                info["name"] = u.get("name") or name
+            except OpError:
+                pass
+            user_cache[uid] = info
+        return user_cache[uid]
+
+    def project_info(entry) -> dict:
+        pid = hal.link_id(entry, "project")
+        name = hal.link_title(entry, "project") or "(none)"
+        if pid is None:
+            return {"id": None, "name": name, "identifier": None}
+        if pid not in project_cache:
+            info = {"id": pid, "name": name, "identifier": None}
+            try:
+                p = client.get(f"projects/{pid}")
+                info["identifier"] = p.get("identifier")
+                info["name"] = p.get("name") or name
+            except OpError:
+                pass
+            project_cache[pid] = info
+        return project_cache[pid]
+
+    people: dict[int, dict] = {}
+    grand_hours = 0.0
+    grand_amount = 0.0
+    for e in entries:
+        info = user_info(e)
+        uid = info["id"]
+        hours = iso_to_hours(e.get("hours")) or 0.0
+        pinfo = project_info(e)
+        proj_name = pinfo["name"]
+        proj_id = pinfo["id"]
+
+        # ordered by specificity -> deterministic matching
+        user_keys = [str(k) for k in (info.get("login"), info.get("name"), uid) if k is not None]
+        project_keys = [str(k) for k in (pinfo.get("identifier"), proj_name, proj_id) if k is not None]
+        rate = _rate_for(rate_table, user_keys, project_keys) if rate_table else None
+        # accumulate unrounded; round only at output to avoid cent drift
+        amount = hours * rate if rate is not None else None
+
+        person = people.setdefault(
+            uid,
+            {"user": info, "hours": 0.0, "entries": 0, "amount": 0.0 if rate_table else None, "projects": {}},
+        )
+        person["hours"] += hours
+        person["entries"] += 1
+        if amount is not None:
+            person["amount"] = (person["amount"] or 0.0) + amount
+        if by_project:
+            pj = person["projects"].setdefault(proj_name, {"project": proj_name, "hours": 0.0, "amount": 0.0 if rate_table else None, "rate": rate})
+            pj["hours"] += hours
+            if amount is not None:
+                pj["amount"] = (pj["amount"] or 0.0) + amount
+
+        grand_hours += hours
+        if amount is not None:
+            grand_amount += amount
+
+    by_user = []
+    for p in people.values():
+        row = {
+            "user": p["user"],
+            "hours": round(p["hours"], 2),
+            "entries": p["entries"],
+            "amount": round(p["amount"], 2) if p["amount"] is not None else None,
+        }
+        if by_project:
+            row["projects"] = [
+                {"project": pj["project"], "hours": round(pj["hours"], 2),
+                 "rate": pj["rate"], "amount": round(pj["amount"], 2) if pj["amount"] is not None else None}
+                for pj in p["projects"].values()
+            ]
+        by_user.append(row)
+    by_user.sort(key=lambda r: r["hours"], reverse=True)
+
+    result = {
+        "period": {"month": month, "from": frm, "to": to},
+        "currency": (rate_table or {}).get("currency"),
+        "billable": rate_table is not None,
+        "byUser": by_user,
+        "totals": {
+            "hours": round(grand_hours, 2),
+            "amount": round(grand_amount, 2) if rate_table is not None else None,
+            "entries": sum(p["entries"] for p in people.values()),
+            "people": len(people),
+        },
+    }
+
+    if obj.output.value == "table":
+        cols = [
+            ("User", lambda r: r["user"].get("name")),
+            ("Login", lambda r: r["user"].get("login")),
+            ("Hours", "hours"),
+            ("Entries", "entries"),
+            ("Amount", "amount"),
+        ]
+        obj.emitter.emit(by_user, columns=cols, title=f"Time report {month or (frm or '') + '..' + (to or '')}")
+        obj.emitter.message(f"TOTAL: {result['totals']['hours']}h" + (f", {result['currency'] or ''} {result['totals']['amount']}" if rate_table else ""))
+    else:
+        obj.emitter.emit(result)

opcli/commands/custom_fields.py

@@ -0,0 +1,82 @@
+"""Custom-field discovery.
+
+Custom fields cannot be *created* through the API v3 (that's admin-UI/Rails
+only). What the API *does* let you do is discover which custom fields exist on a
+resource and their allowed values — which is exactly what you need to then set
+them via `wp create/update --custom-fields`. These commands read the relevant
+schema/form and surface the ``customFieldN`` entries.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import resolve, serialize
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("Key", "key"),
+    ("Name", "name"),
+    ("Type", "type"),
+    ("Required", "required"),
+    ("Writable", "writable"),
+    ("AllowedValues", lambda r: len(r.get("allowedValues", [])) if r.get("allowedValues") else ""),
+]
+
+
+def _schema_fields(schema: dict, *, only_custom: bool) -> list[dict]:
+    out = []
+    for name, spec in schema.items():
+        if not isinstance(spec, dict) or not spec.get("type"):
+            continue
+        if only_custom and not name.startswith("customField"):
+            continue
+        out.append(serialize.custom_field_schema(name, spec))
+    return out
+
+
+@app.command()
+def wp(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", "-P", help="Project id/identifier."),
+    type_: str = typer.Option("Task", "--type", "-t", help="Work-package type name."),
+    all_fields: bool = typer.Option(False, "--all", help="Include built-in fields, not just custom."),
+) -> None:
+    """List custom fields available on work packages of a project/type."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    form = client.post(
+        f"projects/{pid}/work_packages/form",
+        json={"_links": {"project": {"href": f"/api/v3/projects/{pid}"}, "type": {"href": resolve.wp_type(client, type_)}}},
+    )
+    schema = (form.get("_embedded") or {}).get("schema") or {}
+    obj.emitter.emit(_schema_fields(schema, only_custom=not all_fields), columns=_COLUMNS, empty="(no custom fields)")
+
+
+@app.command()
+def project(
+    ctx: typer.Context,
+    all_fields: bool = typer.Option(False, "--all", help="Include built-in fields, not just custom."),
+) -> None:
+    """List custom fields (project attributes) available on projects."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    form = client.post("projects/form", json={})
+    schema = (form.get("_embedded") or {}).get("schema") or {}
+    obj.emitter.emit(_schema_fields(schema, only_custom=not all_fields), columns=_COLUMNS, empty="(no custom fields)")
+
+
+@app.command("time")
+def time_entry(
+    ctx: typer.Context,
+    all_fields: bool = typer.Option(False, "--all", help="Include built-in fields, not just custom."),
+) -> None:
+    """List custom fields available on time entries."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    form = client.post("time_entries/form", json={})
+    schema = (form.get("_embedded") or {}).get("schema") or {}
+    obj.emitter.emit(_schema_fields(schema, only_custom=not all_fields), columns=_COLUMNS, empty="(no custom fields)")

opcli/commands/filelinks.py

@@ -0,0 +1,100 @@
+"""File-storage (Nextcloud) links on work packages.
+
+Links an existing file in a configured storage (e.g. your Nextcloud) to a work
+package via ``/api/v3/work_packages/{id}/file_links``. Requires the storage to
+be set up in OpenProject admin and connected to the project. Creating a link is
+idempotent on (originData.id, work package, storage).
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import serialize
+from ..errors import OpError
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Name", "originName"),
+    ("OriginID", "originId"),
+    ("Storage", "storage"),
+    ("Status", "status"),
+]
+
+
+@app.command()
+def storages(ctx: typer.Context) -> None:
+    """List configured file storages (Nextcloud etc.)."""
+    obj = ctx_obj(ctx)
+    rows = [
+        {
+            "id": s.get("id"),
+            "name": s.get("name"),
+            "type": s.get("_type"),
+            "host": s.get("host"),
+        }
+        for s in obj.client().collect("storages")
+    ]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name"), ("Type", "type"), ("Host", "host")], empty="(no storages configured)")
+
+
+@app.command("list")
+def list_links(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+) -> None:
+    """List file links on a work package."""
+    obj = ctx_obj(ctx)
+    rows = [serialize.file_link(f) for f in obj.client().collect(f"work_packages/{wp_id}/file_links")]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no file links)")
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    storage: int = typer.Option(..., "--storage", "-s", help="Storage id (see `filelink storages`)."),
+    file_id: str = typer.Option(..., "--file-id", help="File id within the storage (Nextcloud fileid)."),
+    file_name: str = typer.Option(..., "--file-name", help="File name to display."),
+    mime: str = typer.Option("application/octet-stream", "--mime", help="MIME type (folder: application/x-op-directory)."),
+) -> None:
+    """Link a Nextcloud/storage file to a work package."""
+    obj = ctx_obj(ctx)
+    body = {
+        "_type": "Collection",
+        "_embedded": {
+            "elements": [
+                {
+                    "originData": {"id": file_id, "name": file_name, "mimeType": mime},
+                    "_links": {"storage": {"href": f"/api/v3/storages/{storage}"}},
+                }
+            ]
+        },
+    }
+    resp = obj.client().post(f"work_packages/{wp_id}/file_links", json=body)
+    elements = (resp.get("_embedded") or {}).get("elements") or [resp]
+    obj.emitter.emit([serialize.file_link(e) for e in elements])
+
+
+@app.command()
+def get(ctx: typer.Context, file_link_id: int = typer.Argument(..., help="File link id.")) -> None:
+    """Show a single file link."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit(serialize.file_link(obj.client().get(f"file_links/{file_link_id}")))
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    file_link_id: int = typer.Argument(..., help="File link id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Remove a file link."""
+    obj = ctx_obj(ctx)
+    if not yes:
+        typer.confirm(f"Delete file link {file_link_id}?", abort=True)
+    obj.client().delete(f"file_links/{file_link_id}")
+    obj.emitter.emit({"status": "deleted", "fileLink": file_link_id})

opcli/commands/guide.py

@@ -0,0 +1,198 @@
+"""`openproject guide` — a built-in operating manual.
+
+The point of this command is self-sufficiency: an agent (or human) with only the
+installed CLI and no other context can run `openproject guide` and learn the
+output contract, how to authenticate, how to discover filters, and the gotchas —
+without needing the README or any external docs.
+"""
+
+from __future__ import annotations
+
+import typer
+
+OVERVIEW = """\
+openproject — operating guide (run `openproject guide <topic>` for details)
+
+WHAT IT IS
+  A CLI for OpenProject: work packages, projects, assignees, custom fields,
+  comments, time entries, search, notifications, wiki, attachments, and
+  per-person time/cost reporting for invoicing.
+
+OUTPUT CONTRACT (important for scripting/agents)
+  - stdout is JSON by default — parse it.
+  - Errors go to stderr as JSON with a non-zero exit code: {"error": "...", "status": 404}.
+  - Exit codes: 0 ok · 3 config · 4 auth · 5 not-found · 6 conflict(lockVersion) · 7 validation · 1 other.
+  - Change format anywhere on the line: `-o table`, `-o markdown` (or `-f markdown`).
+  - Trim output to what you need: `--fields id,subject,status,assignee.name` (dotted paths ok).
+  - Get just a count: add `--count` to `search wp`.
+
+AUTHENTICATE
+  Non-interactive (best for agents/CI — no keyring, never prompts):
+    export OPCLI_BASE_URL=https://openproject.example.com
+    export OPCLI_TOKEN=opapi-xxxxxxxx
+  Or store in the OS keyring:  openproject auth login --url <URL> --token <TOKEN>
+  Verify:  openproject auth whoami        (or `auth status`)
+
+USE NAMES, NOT IDS
+  Names are resolved for you: --status "In progress", --assignee jane.doe,
+  --type Bug, --priority High, --project my-proj, --version "Sprint 3".
+  `me` always means the authenticated user.
+
+FIND THINGS — don't hand-write filter JSON
+  Plain flags:   openproject search wp --mine --overdue --updated-since 7d
+  Expressions:   openproject search wp --where "status = open" --where "updated > 7d"
+  Presets:       openproject search mine | overdue | recent | unassigned | reported | watching
+  Discover:      openproject search fields         # what you can filter on (live)
+                 openproject search operators       # what =, o, !*, <>d, ~ mean
+                 openproject search values status   # allowed values for a field
+
+DISCOVER COMMANDS & OPTIONS
+  openproject --help
+  openproject <group> --help              e.g. `openproject wp --help`
+  openproject <group> <command> --help    e.g. `openproject wp create --help`
+
+KEY GOTCHAS (save yourself a round-trip)
+  - `wp update` handles lockVersion automatically; `raw patch` does NOT (send it yourself).
+  - Time `hours` accept decimals (2.5) or ISO-8601 (PT2H30M).
+  - Assignees must be project members — a new project has none; add with `member add`.
+  - `comment add` takes markdown; `comment edit` takes a plain string.
+  - Wiki is read-only metadata over the API; costs have no rates, so `cost report`
+    multiplies hours by a rate table you pass with --rates.
+  - Anything not wrapped: `openproject raw {get,post,patch,delete} <path> [-d JSON]`.
+
+TOPICS:  search · wp · time · comments · projects · costs · customfields · output · auth · notifications
+"""
+
+TOPICS: dict[str, str] = {
+    "search": """\
+SEARCH — three ways, easiest first
+
+1) Flags:   openproject search wp --mine --overdue
+            openproject search wp --project P --type Bug --priority High --updated-since 7d
+            openproject search wp --unassigned --status open
+            openproject search wp --id 42,57 --all
+            Dates accept ISO (2026-08-01) or relative: 7d, 2w, 1m, +30d, today, yesterday.
+2) Presets: openproject search mine | overdue | recent --days 3 | unassigned | reported | watching
+3) --where: openproject search wp --where "status = open" --where "assignee = me" --where "updated > 14d"
+            Operators in --where: =, !=, ~ (contains), >=, <=, >, <, and :open/:closed/:none/:any.
+            Field aliases: updated->updatedAt, created->createdAt, due->dueDate.
+
+DISCOVER (so you never guess):
+   openproject search fields [--project P]   # every filterable field (incl. custom fields)
+   openproject search operators              # operator cheat-sheet
+   openproject search values <field>         # allowed values (status/type/priority/version/...)
+
+Handy: --sort <field> --asc/--desc, --group-by status, --limit N (0=all), --count, --raw.
+Default is OPEN work packages only; add --all for closed too.
+""",
+    "wp": """\
+WORK PACKAGES
+  create:  openproject wp create "Title" --project P --type Bug --assignee me --priority High \\
+             --due-date 2026-08-01 --estimated 3 --description "..."
+  read:    openproject wp get <id>            # add --raw for the full HAL document
+  update:  openproject wp update <id> --status "In progress" --done-ratio 50   (lockVersion auto)
+  assign:  openproject wp assign <id> jane.doe     (or `... none` / `wp unassign <id>`)
+  move:    openproject wp move <id> other-project
+  watch:   openproject wp watch <id> me            (list: `wp watchers <id>`)
+  delete:  openproject wp delete <id> -y
+  fields:  openproject wp schema --project P --type Bug   # discover writable + custom fields
+  set custom fields:  --custom-fields '{"customField1":"INV-1","customField2":{"href":"/api/v3/custom_options/3"}}'
+""",
+    "time": """\
+TIME ENTRIES
+  log:     openproject time add 2.5 --work-package <id> --activity Development --comment "..."
+           openproject time add 1 --project P --date 2026-07-10      (hours: 2.5 or PT2H30M)
+  list:    openproject time list --user me --month 2026-07
+           (filters: --from/--to dates, --work-package, --project)
+  edit:    openproject time edit <id> --hours 3 --comment "..."
+  delete:  openproject time delete <id> -y
+  activities: openproject time activities --project P   (Development, Management, ...)
+""",
+    "comments": """\
+COMMENTS (stored as work-package activities)
+  add:   openproject comment add <wp_id> "markdown body"   (add --notify to email watchers)
+  list:  openproject comment list <wp_id>
+  edit:  openproject comment edit <activity_id> "plain string"   # NOTE: edit takes a plain string
+  The activity_id comes from `comment list` (not the work-package id). No delete via the API.
+""",
+    "projects": """\
+PROJECTS
+  create:    openproject project create "Name" --identifier my-id --description "..." [--parent P] [--public]
+  list:      openproject project list          (add --archived for archived ones)
+  update:    openproject project update my-id --name "..." --description "..."
+  archive:   openproject project archive my-id     (unarchive: `project unarchive my-id`)
+  delete:    openproject project delete my-id -y
+  Members:   openproject member add --project my-id --user jane.doe --role Member
+             (only members can be assignees; `user available my-id` lists assignable people)
+""",
+    "costs": """\
+TIME & COST REPORTING (for invoicing, per person)
+  openproject cost report --month 2026-07 --rates rates.json
+  openproject cost report --from 2026-07-01 --to 2026-07-31 --user jane.doe --rates rates.json
+
+  The OpenProject API exposes no hourly rates, so you supply them. rates.json:
+    {"currency":"EUR","default":90,"users":{"jane.doe":100},
+     "projects":{"my-proj":{"default":100,"admin":110}}}
+  Most specific wins: project+user > project default > user > global default.
+  Without --rates you get hours only. Output groups by user, then by project.
+""",
+    "customfields": """\
+CUSTOM FIELDS
+  Custom fields are created in the OpenProject admin UI (not via the API). You can
+  DISCOVER and SET them:
+    openproject cf wp --project P --type Bug      # lists customFieldN, type, allowed values
+    openproject cf project                        # project attributes
+    openproject cf time                           # time-entry custom fields
+  Set on create/update with --custom-fields (JSON):
+    scalar (string/int/date/bool):  {"customField1":"INV-1"}
+    reference (list/user/version):  {"customField2":{"href":"/api/v3/custom_options/3"}}
+  Use the ids shown by `cf wp` / `search values customFieldN`.
+""",
+    "output": """\
+OUTPUT & FIELDS
+  Formats: json (default), table, markdown. Choose per command:
+     openproject wp list -o table
+     openproject wp get 42 -f markdown
+  Set a default:  openproject settings set-format table   (see `settings show`)
+  Select fields (dotted paths ok, works in every format):
+     openproject search mine --fields id,subject,status,assignee.name
+  -o/--format/-f and --fields work ANYWHERE on the line (before or after the command).
+  Precedence: --format > -o > $OPCLI_FORMAT > saved default > json.
+""",
+    "auth": """\
+AUTH & PROFILES
+  login:   openproject auth login --url https://op.example.com --token opapi-xxxx [--name prod]
+  check:   openproject auth whoami     |     openproject auth status
+  logout:  openproject auth logout [--name prod]
+  Env (non-interactive, no keyring): OPCLI_BASE_URL, OPCLI_TOKEN (+ OPCLI_PROFILE).
+  Multiple instances: `openproject -p prod wp list` targets a saved profile.
+  Get a token in OpenProject: My account -> Access tokens -> API.
+""",
+    "notifications": """\
+NOTIFICATIONS (in-app)
+  list:   openproject notify list                 (unread by default; --state read|all)
+          openproject notify list --today
+  count:  openproject notify count [--today]       -> {"total","unread","today","todayUnread"}
+  mark:   openproject notify read <id> | unread <id> | read-all
+""",
+}
+
+
+def guide(
+    topic: str = typer.Argument(None, help="Optional topic: search, wp, time, comments, projects, costs, customfields, output, auth, notifications."),
+) -> None:
+    """Print a built-in operating guide so the CLI is usable without external docs.
+
+    Run `openproject guide` for the overview, or `openproject guide <topic>` for a
+    focused cheat-sheet (e.g. `openproject guide search`).
+    """
+    if not topic:
+        typer.echo(OVERVIEW)
+        return
+    key = topic.strip().lower()
+    text = TOPICS.get(key)
+    if text is None:
+        typer.echo(f"unknown topic '{topic}'. Available: " + ", ".join(TOPICS) + "\n")
+        typer.echo(OVERVIEW)
+        raise typer.Exit(code=2)
+    typer.echo(text)