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

opcli/commands/search.py

@@ -0,0 +1,256 @@
+"""Powerful, discoverable work-package search.
+
+Three ways to search, easiest first:
+
+1. **Predefined flags** — ``--mine``, ``--overdue``, ``--status open``,
+   ``--updated-since 7d``, ``--version v1`` … no JSON needed.
+2. **Presets** — ``search mine``, ``search overdue``, ``search recent`` …
+3. **``--where``** — compact expressions: ``--where "status = open"``,
+   ``--where "assignee:none"``, ``--where "updated > 7d"``.
+
+And to learn what's available:
+
+* ``search fields``    — what you can filter on
+* ``search operators`` — what the operator codes mean
+* ``search values X``  — allowed values for a field
+"""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from .. import resolve, searchspec, serialize, wpfilters
+from ._shared import ctx_obj, parse_json_option
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Type", "type"),
+    ("Subject", "subject"),
+    ("Status", "status"),
+    ("Assignee", lambda r: (r.get("assignee") or {}).get("name")),
+    ("Due", "dueDate"),
+    ("Updated", "updatedAt"),
+]
+
+
+def _render(obj, client, filters, *, sort, asc, group_by, limit, count, raw):
+    params: dict = {"filters": json.dumps(filters), "sortBy": json.dumps([[sort, "asc" if asc else "desc"]])}
+    if group_by:
+        params["groupBy"] = group_by
+    if count:
+        params["pageSize"] = 1
+        doc = client.get("work_packages", params=params)
+        obj.emitter.emit({"total": doc.get("total", 0), "filters": filters})
+        return
+    elements = client.collect("work_packages", params=params, limit=limit or None)
+    if raw:
+        obj.emitter.emit(elements)
+        return
+    rows = [serialize.work_package(w, include_description=False) for w in elements]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no matches)")
+
+
+@app.command()
+def wp(
+    ctx: typer.Context,
+    text: str = typer.Argument(None, help="Full-text query (subject/description/comments)."),
+    project: str = typer.Option(None, "--project", "-P", help="Restrict to a project."),
+    status: str = typer.Option(None, "--status", "-s", help="'open', 'closed', or a status name."),
+    open_: bool = typer.Option(False, "--open", help="Only open work packages."),
+    closed: bool = typer.Option(False, "--closed", help="Only closed work packages."),
+    type_: str = typer.Option(None, "--type", "-t", help="Type name."),
+    priority: str = typer.Option(None, "--priority", help="Priority name."),
+    assignee: str = typer.Option(None, "--assignee", "-a", help="Assignee (login/name/id or 'me')."),
+    mine: bool = typer.Option(False, "--mine", help="Assigned to me."),
+    unassigned: bool = typer.Option(False, "--unassigned", help="No assignee."),
+    author: str = typer.Option(None, "--author", "--created-by", help="Author (login/name/id or 'me')."),
+    responsible: str = typer.Option(None, "--responsible", help="Accountable person."),
+    watching: bool = typer.Option(False, "--watching", help="Watched by me."),
+    version: str = typer.Option(None, "--version", help="Target version/milestone (name/id)."),
+    parent: int = typer.Option(None, "--parent", help="Children of this work-package id."),
+    ids: str = typer.Option(None, "--id", help="Specific ids, comma-separated."),
+    subject: str = typer.Option(None, "--subject", help="Subject contains (LIKE)."),
+    created_since: str = typer.Option(None, "--created-since", help="Created on/after (date or 7d/2w/today)."),
+    created_before: str = typer.Option(None, "--created-before", help="Created before (date or spec)."),
+    updated_since: str = typer.Option(None, "--updated-since", help="Updated on/after (date or spec)."),
+    due_before: str = typer.Option(None, "--due-before", help="Due on/before (date or spec)."),
+    due_after: str = typer.Option(None, "--due-after", help="Due on/after (date or spec)."),
+    overdue: bool = typer.Option(False, "--overdue", help="Past due and still open."),
+    start_after: str = typer.Option(None, "--start-after", help="Starts on/after."),
+    start_before: str = typer.Option(None, "--start-before", help="Starts on/before."),
+    where: list[str] = typer.Option(None, "--where", "-w", help='Expression e.g. "status = open" (repeatable).'),
+    filters_json: str = typer.Option(None, "--filters", help="Raw OpenProject filters JSON (overrides everything)."),
+    all_statuses: bool = typer.Option(False, "--all", help="Include closed work packages."),
+    sort: str = typer.Option("updatedAt", "--sort", help="Sort field."),
+    asc: bool = typer.Option(False, "--asc", help="Ascending (default descending)."),
+    group_by: str = typer.Option(None, "--group-by", help="Group column (status/type/assignee/project/priority)."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Maximum rows (0 = all)."),
+    count: bool = typer.Option(False, "--count", help="Return only the total match count."),
+    raw: bool = typer.Option(False, "--raw", "-r", help="Return raw HAL elements."),
+) -> None:
+    """Search work packages with rich, plain-language filters."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+
+    if filters_json:
+        filters = parse_json_option(filters_json, what="--filters")
+    else:
+        if open_:
+            status = "open"
+        elif closed:
+            status = "closed"
+        filters = wpfilters.build(
+            client, project=project, status=status, type_=type_, priority=priority,
+            assignee=assignee, mine=mine, unassigned=unassigned, author=author,
+            responsible=responsible, watching=watching, version=version, parent=parent,
+            id_list=ids, query=text, subject=subject,
+            created_since=created_since, created_before=created_before,
+            updated_since=updated_since, due_before=due_before, due_after=due_after,
+            overdue=overdue, start_after=start_after, start_before=start_before,
+            where=where, all_statuses=all_statuses,
+        )
+    _render(obj, client, filters, sort=sort, asc=asc, group_by=group_by, limit=limit, count=count, raw=raw)
+
+
+# ------------------------------------------------------------- presets
+def _preset(ctx, *, sort="updatedAt", asc=False, limit=50, **build_kwargs):
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    filters = wpfilters.build(client, **build_kwargs)
+    _render(obj, client, filters, sort=sort, asc=asc, group_by=None, limit=limit, count=False, raw=False)
+
+
+@app.command()
+def mine(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P", help="Restrict to a project."),
+    all_statuses: bool = typer.Option(False, "--all", help="Include closed."),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """Open work packages assigned to me."""
+    _preset(ctx, mine=True, project=project, all_statuses=all_statuses, limit=limit)
+
+
+@app.command()
+def reported(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P"),
+    all_statuses: bool = typer.Option(False, "--all"),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """Work packages I created (authored)."""
+    _preset(ctx, author="me", project=project, all_statuses=all_statuses, limit=limit)
+
+
+@app.command()
+def watching(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P"),
+    all_statuses: bool = typer.Option(False, "--all"),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """Work packages I watch."""
+    _preset(ctx, watching=True, project=project, all_statuses=all_statuses, limit=limit)
+
+
+@app.command()
+def unassigned(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P"),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """Open work packages with no assignee."""
+    _preset(ctx, unassigned=True, project=project, limit=limit)
+
+
+@app.command()
+def overdue(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P"),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """Past-due, still-open work packages."""
+    _preset(ctx, overdue=True, project=project, sort="dueDate", asc=True, limit=limit)
+
+
+@app.command()
+def recent(
+    ctx: typer.Context,
+    days: int = typer.Option(7, "--days", "-d", help="Updated within the last N days."),
+    project: str = typer.Option(None, "--project", "-P"),
+    all_statuses: bool = typer.Option(True, "--all/--open-only", help="Include closed (default yes)."),
+    limit: int = typer.Option(50, "--limit", "-n"),
+) -> None:
+    """Recently updated work packages."""
+    _preset(ctx, updated_since=f"{days}d", project=project, all_statuses=all_statuses, limit=limit)
+
+
+# ------------------------------------------------------- discoverability
+@app.command()
+def fields(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P", help="Show project-specific filters (incl. its custom fields)."),
+) -> None:
+    """List what you can filter/search work packages on (live from the instance)."""
+    obj = ctx_obj(ctx)
+    rows = searchspec.live_fields(obj.client(), project)
+    obj.emitter.emit(
+        rows,
+        columns=[("Field", "field"), ("Kind", "kind"), ("CLI flag", "flag"), ("Description", "description")],
+        empty="(no filters)",
+    )
+
+
+@app.command()
+def operators(ctx: typer.Context) -> None:
+    """Explain the filter operator codes."""
+    obj = ctx_obj(ctx)
+    rows = [{"operator": code, "meaning": meaning} for code, meaning in searchspec.OPERATORS]
+    obj.emitter.emit(rows, columns=[("Operator", "operator"), ("Meaning", "meaning")])
+
+
+@app.command()
+def values(
+    ctx: typer.Context,
+    field: str = typer.Argument(..., help="Field to list allowed values for (status/type/priority/version/...)."),
+    project: str = typer.Option(None, "--project", "-P", help="Project context (versions, assignees, custom fields)."),
+    limit: int = typer.Option(100, "--limit", "-n"),
+) -> None:
+    """List the allowed values for a filterable field."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    f = field.strip()
+    simple = {"status": "statuses", "type": "types", "priority": "priorities", "project": "projects"}
+    rows: list[dict]
+    if f in simple:
+        rows = [{"id": e.get("id"), "name": e.get("name")} for e in client.collect(simple[f], limit=limit)]
+    elif f == "version":
+        coll = f"projects/{resolve.project_id(client, project)}/versions" if project else "versions"
+        rows = [{"id": e.get("id"), "name": e.get("name")} for e in client.collect(coll, limit=limit)]
+    elif f in ("assignee", "author", "responsible", "watcher", "user"):
+        if project:
+            pid = resolve.project_id(client, project)
+            rows = [serialize.principal(p) for p in client.collect(f"projects/{pid}/available_assignees", limit=limit)]
+        else:
+            rows = [serialize.principal(p) for p in client.collect("principals", limit=limit)]
+    elif f.startswith("customField"):
+        pid = resolve.project_id(client, project or 1)
+        form = client.post(
+            f"projects/{pid}/work_packages/form",
+            json={"_links": {"project": {"href": f"/api/v3/projects/{pid}"}}},
+        )
+        spec = ((form.get("_embedded") or {}).get("schema") or {}).get(f) or {}
+        allowed = (spec.get("_links") or {}).get("allowedValues") or []
+        rows = [{"name": a.get("title"), "href": a.get("href")} for a in allowed]
+    else:
+        from ..errors import OpError
+
+        raise OpError(
+            f"no value list for '{field}'. Try status, type, priority, project, version, assignee, or a customFieldN. "
+            f"Free-text/date/number fields take literal values."
+        )
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name")], empty="(no values)")

opcli/commands/settings.py

@@ -0,0 +1,59 @@
+"""Manage CLI settings — most importantly the default output format."""
+
+from __future__ import annotations
+
+import typer
+
+from .. import credentials
+from ..config import Config, config_path
+from ..errors import OpError
+from ..output import OutputFormat
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def show(ctx: typer.Context) -> None:
+    """Show current settings (default format, active profile, config location)."""
+    obj = ctx_obj(ctx)
+    cfg = obj.config
+    obj.emitter.emit(
+        {
+            "configPath": str(config_path()),
+            "defaultFormat": cfg.default_format or "(not set — defaults to json)",
+            "activeProfile": cfg.active_profile_name(),
+            "profiles": sorted(cfg.profiles.keys()),
+            "credentialBackend": credentials.backend_name(),
+        }
+    )
+
+
+@app.command("set-format")
+def set_format(
+    ctx: typer.Context,
+    fmt: str = typer.Argument(..., help="json | table | markdown (md)."),
+) -> None:
+    """Set the default output format used when no --format/-o is given."""
+    obj = ctx_obj(ctx)
+    try:
+        chosen = OutputFormat.coerce(fmt)
+    except ValueError as exc:
+        raise OpError(str(exc)) from exc
+    cfg = Config.load()  # reload to avoid clobbering concurrent changes
+    cfg.default_format = chosen.value
+    cfg.save()
+    obj.emitter.emit({"status": "saved", "defaultFormat": chosen.value, "configPath": str(config_path())})
+
+
+@app.command("get-format")
+def get_format(ctx: typer.Context) -> None:
+    """Print the effective default format."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit({"defaultFormat": obj.config.default_format or "json"})
+
+
+@app.command()
+def path(ctx: typer.Context) -> None:
+    """Print the config file path."""
+    ctx_obj(ctx).emitter.emit({"configPath": str(config_path())})

opcli/commands/time_entries.py

@@ -0,0 +1,214 @@
+"""Time-entry commands: log, edit, list, delete, activities, and reporting.
+
+Time-entry filters use snake_case names (``user_id``, ``project_id``,
+``entity_type``/``entity_id``, ``spent_on``) — different from work-package
+filters. ``hours`` is an ISO-8601 duration; we accept decimals and convert.
+Time entries have no lockVersion.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+
+import typer
+
+from .. import hal, resolve, serialize
+from ..duration import iso_to_hours, parse_hours_input
+from ..errors import ApiError, OpError, ValidationError
+from ._shared import ctx_obj, set_link
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Date", "spentOn"),
+    ("Hours", lambda r: iso_to_hours(r.get("hours"))),
+    ("User", lambda r: (r.get("user") or {}).get("name")),
+    ("WorkPkg", lambda r: (r.get("workPackage") or {}).get("id")),
+    ("Activity", "activity"),
+    ("Comment", "comment"),
+]
+
+
+def _month_range(month: str) -> tuple[str, str]:
+    year, mon = (int(x) for x in month.split("-"))
+    first = _dt.date(year, mon, 1)
+    nxt = _dt.date(year + (mon == 12), (mon % 12) + 1, 1)
+    last = nxt - _dt.timedelta(days=1)
+    return first.isoformat(), last.isoformat()
+
+
+def _build_filters(client, *, user, project, work_package, frm, to, month, wp_style="work_package_id") -> list[dict]:
+    filters: list[dict] = []
+    if month:
+        frm, to = _month_range(month)
+    if user:
+        href = resolve.user(client, user, project_ref=project)
+        filters.append({"user_id": {"operator": "=", "values": [str(hal.id_from_href(href))]}})
+    if project:
+        filters.append({"project_id": {"operator": "=", "values": [str(resolve.project_id(client, project))]}})
+    if work_package:
+        if wp_style == "entity":
+            filters.append({"entity_type": {"operator": "=", "values": ["WorkPackage"]}})
+            filters.append({"entity_id": {"operator": "=", "values": [str(work_package)]}})
+        else:
+            filters.append({"work_package_id": {"operator": "=", "values": [str(work_package)]}})
+    if frm and to:
+        filters.append({"spent_on": {"operator": "<>d", "values": [frm, to]}})
+    elif frm:
+        # single-sided: use the between operator with an empty upper bound
+        # (>=d/<=d are not valid OpenProject operator codes).
+        filters.append({"spent_on": {"operator": "<>d", "values": [frm, ""]}})
+    elif to:
+        filters.append({"spent_on": {"operator": "<>d", "values": ["", to]}})
+    return filters
+
+
+def query_time_entries(client, *, user=None, project=None, work_package=None, frm=None, to=None,
+                       month=None, sort="spent_on", desc=True, limit=None) -> list[dict]:
+    """Fetch time entries, tolerating the work-package-filter name difference
+    across OpenProject versions (``work_package_id`` vs ``entity_type``/``entity_id``)."""
+    styles = ("work_package_id", "entity") if work_package else ("work_package_id",)
+    last: Exception | None = None
+    for style in styles:
+        filters = _build_filters(client, user=user, project=project, work_package=work_package,
+                                 frm=frm, to=to, month=month, wp_style=style)
+        params = {"sortBy": json.dumps([[sort, "desc" if desc else "asc"]])}
+        if filters:
+            params["filters"] = json.dumps(filters)
+        try:
+            return client.collect("time_entries", params=params, limit=limit)
+        except (ApiError, ValidationError) as exc:
+            last = exc
+            if work_package and "does not exist" in (exc.message or "").lower():
+                continue
+            raise
+    if last:
+        raise last
+    return []
+
+
+@app.command("list")
+def list_entries(
+    ctx: typer.Context,
+    user: str = typer.Option(None, "--user", "-u", help="Filter by user (login/name/id or 'me')."),
+    project: str = typer.Option(None, "--project", "-P", help="Filter by project."),
+    work_package: int = typer.Option(None, "--work-package", "-w", help="Filter by work package id."),
+    frm: str = typer.Option(None, "--from", help="Start date (YYYY-MM-DD)."),
+    to: str = typer.Option(None, "--to", help="End date (YYYY-MM-DD)."),
+    month: str = typer.Option(None, "--month", help="Convenience month filter YYYY-MM."),
+    limit: int = typer.Option(100, "--limit", "-n", help="Maximum rows (0 = all)."),
+) -> None:
+    """List time entries with filters (per person / project / work package)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    entries = query_time_entries(client, user=user, project=project, work_package=work_package,
+                                 frm=frm, to=to, month=month, limit=limit or None)
+    rows = [serialize.time_entry(t) for t in entries]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no time entries)")
+
+
+@app.command()
+def get(ctx: typer.Context, entry_id: int = typer.Argument(..., help="Time entry id.")) -> None:
+    """Show a single time entry."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit(serialize.time_entry(obj.client().get(f"time_entries/{entry_id}")))
+
+
+@app.command()
+def add(
+    ctx: typer.Context,
+    hours: str = typer.Argument(..., help="Hours (decimal like 2.5 or ISO8601 like PT2H30M)."),
+    work_package: int = typer.Option(None, "--work-package", "-w", help="Work package id to log against."),
+    project: str = typer.Option(None, "--project", "-P", help="Project id/identifier (if not logging on a WP)."),
+    spent_on: str = typer.Option(None, "--date", help="Date YYYY-MM-DD (default today)."),
+    activity: str = typer.Option(None, "--activity", help="Activity name (e.g. Development)."),
+    comment: str = typer.Option(None, "--comment", "-m", help="Comment."),
+    user: str = typer.Option(None, "--user", "-u", help="Log on behalf of another user (needs permission)."),
+) -> None:
+    """Log a time entry. Hours accept decimals (2.5) or ISO-8601 (PT2H30M).
+
+    Example: openproject time add 2.5 --work-package 42 --activity Development --comment "debugging"
+    Provide --work-package OR --project. Date defaults to today (`--date 2026-07-10`).
+    """
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    if not work_package and not project:
+        raise OpError("provide --work-package or --project")
+
+    body: dict = {
+        "hours": parse_hours_input(hours),
+        "spentOn": spent_on or _dt.date.today().isoformat(),
+        "_links": {},
+    }
+    if work_package:
+        set_link(body, "workPackage", f"/api/v3/work_packages/{work_package}")
+    if project:
+        set_link(body, "project", f"/api/v3/projects/{resolve.project_id(client, project)}")
+    if activity:
+        set_link(body, "activity", resolve.time_activity(client, activity, project_ref=project, wp_id=work_package))
+    if comment is not None:
+        body["comment"] = {"raw": comment}
+    if user:
+        set_link(body, "user", resolve.user(client, user, project_ref=project))
+
+    obj.emitter.emit(serialize.time_entry(client.post("time_entries", json=body)))
+
+
+@app.command()
+def edit(
+    ctx: typer.Context,
+    entry_id: int = typer.Argument(..., help="Time entry id."),
+    hours: str = typer.Option(None, "--hours", help="New hours (decimal or ISO8601)."),
+    spent_on: str = typer.Option(None, "--date", help="New date YYYY-MM-DD."),
+    activity: str = typer.Option(None, "--activity", help="New activity name."),
+    comment: str = typer.Option(None, "--comment", "-m", help="New comment."),
+) -> None:
+    """Edit a time entry (partial; no lockVersion)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    body: dict = {}
+    if hours is not None:
+        body["hours"] = parse_hours_input(hours)
+    if spent_on is not None:
+        body["spentOn"] = spent_on
+    if comment is not None:
+        body["comment"] = {"raw": comment}
+    if activity is not None:
+        current = client.get(f"time_entries/{entry_id}")
+        pid = hal.link_id(current, "project")
+        set_link(body, "activity", resolve.time_activity(client, activity, project_ref=pid))
+    if not body:
+        raise OpError("nothing to update")
+    obj.emitter.emit(serialize.time_entry(client.patch(f"time_entries/{entry_id}", json=body)))
+
+
+@app.command()
+def delete(
+    ctx: typer.Context,
+    entry_id: int = typer.Argument(..., help="Time entry id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Delete a time entry."""
+    obj = ctx_obj(ctx)
+    if not yes:
+        typer.confirm(f"Delete time entry {entry_id}?", abort=True)
+    obj.client().delete(f"time_entries/{entry_id}")
+    obj.emitter.emit({"status": "deleted", "timeEntry": entry_id})
+
+
+@app.command()
+def activities(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P", help="Project context (activities can be project-scoped)."),
+) -> None:
+    """List available time-entry activities (Development, Management, ...)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    if project is None:
+        # activities live in the form schema; any accessible project gives the global set
+        first = client.collect("projects", page_size=1, limit=1)
+        project = first[0]["id"] if first else None
+    acts = resolve.time_activities(client, project_ref=project)
+    obj.emitter.emit([{"id": a["id"], "name": a["name"]} for a in acts], columns=[("ID", "id"), ("Name", "name")])

opcli/commands/users.py

@@ -0,0 +1,109 @@
+"""User / principal commands: list, get, me, available assignees, groups."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from .. import resolve, serialize
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+_COLUMNS = [
+    ("ID", "id"),
+    ("Login", "login"),
+    ("Name", "name"),
+    ("Email", "email"),
+    ("Status", "status"),
+    ("Admin", "admin"),
+]
+
+
+@app.command("list")
+def list_users(
+    ctx: typer.Context,
+    status: str = typer.Option(None, "--status", help="Filter by status (active, locked, invited...)."),
+    name: str = typer.Option(None, "--name", help="Name/login substring filter."),
+    limit: int = typer.Option(100, "--limit", "-n", help="Maximum rows (0 = all)."),
+) -> None:
+    """List users (requires admin permission on most instances)."""
+    obj = ctx_obj(ctx)
+    filters = []
+    if status:
+        filters.append({"status": {"operator": "=", "values": [status]}})
+    if name:
+        filters.append({"name": {"operator": "~", "values": [name]}})
+    params = {"filters": json.dumps(filters)} if filters else {}
+    rows = [serialize.user(u) for u in obj.client().collect("users", params=params, limit=limit or None)]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no users)")
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    user: str = typer.Argument(..., help="User id, login, or 'me'."),
+    raw: bool = typer.Option(False, "--raw", "-r", help="Return the full HAL document."),
+) -> None:
+    """Show a single user."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    href = resolve.user(client, user)
+    doc = client.get(href)
+    obj.emitter.emit(doc if raw else serialize.user(doc))
+
+
+@app.command()
+def create(
+    ctx: typer.Context,
+    login: str = typer.Argument(..., help="Login/username."),
+    email: str = typer.Option(..., "--email", "-e", help="Email address."),
+    first_name: str = typer.Option(..., "--first-name", help="First name."),
+    last_name: str = typer.Option(..., "--last-name", help="Last name."),
+    password: str = typer.Option(None, "--password", help="Initial password (else invite/status)."),
+    status: str = typer.Option("active", "--status", help="active | invited | registered."),
+    admin: bool = typer.Option(False, "--admin", help="Grant admin."),
+) -> None:
+    """Create a user (requires admin)."""
+    obj = ctx_obj(ctx)
+    body: dict = {
+        "login": login,
+        "email": email,
+        "firstName": first_name,
+        "lastName": last_name,
+        "admin": admin,
+        "status": status,
+    }
+    if password:
+        body["password"] = password
+        body["status"] = "active"
+    obj.emitter.emit(serialize.user(obj.client().post("users", json=body)))
+
+
+@app.command()
+def me(ctx: typer.Context) -> None:
+    """Show the authenticated user."""
+    obj = ctx_obj(ctx)
+    obj.emitter.emit(serialize.user(obj.client().me()))
+
+
+@app.command()
+def available(
+    ctx: typer.Context,
+    project: str = typer.Argument(..., help="Project id/identifier."),
+) -> None:
+    """List users assignable within a project (available assignees)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    rows = [serialize.principal(p) for p in client.collect(f"projects/{pid}/available_assignees")]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name"), ("Login", "login"), ("Type", "type")])
+
+
+@app.command()
+def groups(ctx: typer.Context) -> None:
+    """List groups."""
+    obj = ctx_obj(ctx)
+    rows = [{"id": g.get("id"), "name": g.get("name")} for g in obj.client().collect("groups")]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name")])