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

opcli/commands/wiki.py

@@ -0,0 +1,49 @@
+"""Wiki commands (read-only metadata).
+
+OpenProject API v3 exposes only ``GET /api/v3/wiki_pages/{id}`` and the page's
+attachments. The WikiPage model is a stub (id + title only) — there is NO
+list/create/update/delete and NO way to read or write the page body over the
+API. These commands surface what's available and are explicit about the limits.
+"""
+
+from __future__ import annotations
+
+import typer
+
+from .. import serialize
+from ._shared import ctx_obj
+
+app = typer.Typer(no_args_is_help=True)
+
+
+@app.command()
+def get(
+    ctx: typer.Context,
+    page_id: int = typer.Argument(..., help="Wiki page id."),
+    raw: bool = typer.Option(False, "--raw", "-r", help="Return the full HAL document."),
+) -> None:
+    """Show wiki page metadata (id + title only; body is not exposed by the API)."""
+    obj = ctx_obj(ctx)
+    doc = obj.client().get(f"wiki_pages/{page_id}")
+    if raw:
+        obj.emitter.emit(doc)
+        return
+    obj.emitter.emit(
+        {
+            "id": doc.get("id"),
+            "title": doc.get("title"),
+            "project": (doc.get("_embedded") or {}).get("project", {}).get("identifier"),
+            "note": "OpenProject API v3 does not expose wiki page body text.",
+        }
+    )
+
+
+@app.command()
+def attachments(
+    ctx: typer.Context,
+    page_id: int = typer.Argument(..., help="Wiki page id."),
+) -> None:
+    """List attachments on a wiki page."""
+    obj = ctx_obj(ctx)
+    rows = [serialize.attachment(a) for a in obj.client().collect(f"wiki_pages/{page_id}/attachments")]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("File", "fileName"), ("Size", "fileSize"), ("Type", "contentType")])

opcli/commands/workpackages.py

@@ -0,0 +1,338 @@
+"""Work-package commands: CRUD, move, assign, watchers, schema."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from .. import hal, resolve, serialize, wpfilters
+from ..duration import parse_hours_input
+from ..errors import OpError
+from ._shared import apply_custom_fields, ctx_obj, parse_json_option, set_link
+
+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")),
+    ("Project", lambda r: (r.get("project") or {}).get("name")),
+]
+
+
+# --------------------------------------------------------------------- list
+@app.command("list")
+def list_wps(
+    ctx: typer.Context,
+    project: str = typer.Option(None, "--project", "-P", help="Project id/identifier."),
+    status: str = typer.Option(None, "--status", "-s", help="'open', 'closed', or a status name."),
+    type_: str = typer.Option(None, "--type", "-t", help="Work-package type 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')."),
+    priority: str = typer.Option(None, "--priority", help="Priority name."),
+    version: str = typer.Option(None, "--version", help="Target version (name/id)."),
+    overdue: bool = typer.Option(False, "--overdue", help="Past due and still open."),
+    updated_since: str = typer.Option(None, "--updated-since", help="Updated since (date or 7d/today)."),
+    due_before: str = typer.Option(None, "--due-before", help="Due on/before (date or spec)."),
+    query: str = typer.Option(None, "--query", "-q", help="Full-text search (subject/description/comments)."),
+    where: list[str] = typer.Option(None, "--where", "-w", help='Expression filter, e.g. "status = open" (repeatable).'),
+    all_statuses: bool = typer.Option(False, "--all", help="Include closed (disable default open filter)."),
+    sort: str = typer.Option("id", "--sort", help="Sort field, e.g. id, updatedAt, dueDate."),
+    desc: bool = typer.Option(False, "--desc", help="Sort descending."),
+    limit: int = typer.Option(50, "--limit", "-n", help="Maximum rows (0 = all)."),
+) -> None:
+    """List / filter work packages (global, scoped by filters). See `search wp` for the full set."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    filters = wpfilters.build(
+        client, project=project, status=status, type_=type_, assignee=assignee,
+        mine=mine, unassigned=unassigned, author=author, priority=priority, version=version,
+        overdue=overdue, updated_since=updated_since, due_before=due_before,
+        query=query, where=where, all_statuses=all_statuses,
+    )
+    params = {
+        "filters": wpfilters.encode(filters),
+        "sortBy": json.dumps([[sort, "desc" if desc else "asc"]]),
+    }
+    rows = [
+        serialize.work_package(w, include_description=False)
+        for w in client.collect("work_packages", params=params, limit=limit or None)
+    ]
+    obj.emitter.emit(rows, columns=_COLUMNS, empty="(no work packages)")
+
+
+# ---------------------------------------------------------------------- get
+@app.command()
+def get(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    raw: bool = typer.Option(False, "--raw", "-r", help="Return the full HAL document."),
+) -> None:
+    """Show one work package."""
+    obj = ctx_obj(ctx)
+    doc = obj.client().get(f"work_packages/{wp_id}")
+    obj.emitter.emit(doc if raw else serialize.work_package(doc))
+
+
+# ------------------------------------------------------------------- create
+@app.command()
+def create(
+    ctx: typer.Context,
+    subject: str = typer.Argument(..., help="Work package subject/title."),
+    project: str = typer.Option(..., "--project", "-P", help="Project id/identifier."),
+    type_: str = typer.Option("Task", "--type", "-t", help="Type name (default Task)."),
+    description: str = typer.Option(None, "--description", "-d", help="Description (markdown)."),
+    status: str = typer.Option(None, "--status", "-s", help="Initial status name."),
+    priority: str = typer.Option(None, "--priority", help="Priority name."),
+    assignee: str = typer.Option(None, "--assignee", "-a", help="Assignee (login/name/id or 'me')."),
+    responsible: str = typer.Option(None, "--responsible", help="Accountable user."),
+    parent: int = typer.Option(None, "--parent", help="Parent work package id."),
+    start_date: str = typer.Option(None, "--start-date", help="YYYY-MM-DD."),
+    due_date: str = typer.Option(None, "--due-date", help="YYYY-MM-DD."),
+    estimated: str = typer.Option(None, "--estimated", help="Estimated time (hours or ISO8601)."),
+    custom_fields: str = typer.Option(None, "--custom-fields", help="JSON of customFieldN values."),
+    set_: str = typer.Option(None, "--set", help="Raw JSON merged into the create body."),
+    notify: bool = typer.Option(False, "--notify", help="Send notifications for this create."),
+) -> None:
+    """Create a work package. Pass names (type/status/priority/assignee) — they're resolved.
+
+    Example: openproject wp create "Fix login" --project webshop --type Bug --assignee me --priority High
+    Custom fields: --custom-fields '{"customField1":"INV-1"}' (discover them with `cf wp`).
+    Note: the assignee must be a member of the project (see `member add`).
+    """
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+
+    body: dict = {"subject": subject, "_links": {}}
+    set_link(body, "project", f"/api/v3/projects/{pid}")
+    set_link(body, "type", resolve.wp_type(client, type_))
+    if description is not None:
+        body["description"] = {"raw": description}
+    if status:
+        set_link(body, "status", resolve.status(client, status))
+    if priority:
+        set_link(body, "priority", resolve.priority(client, priority))
+    if assignee:
+        set_link(body, "assignee", resolve.user(client, assignee, project_ref=project))
+    if responsible:
+        set_link(body, "responsible", resolve.user(client, responsible, project_ref=project))
+    if parent:
+        set_link(body, "parent", f"/api/v3/work_packages/{parent}")
+    if start_date:
+        body["startDate"] = start_date
+    if due_date:
+        body["dueDate"] = due_date
+    if estimated:
+        body["estimatedTime"] = parse_hours_input(estimated)
+    apply_custom_fields(body, custom_fields)
+    if set_:
+        extra = parse_json_option(set_, what="--set")
+        if isinstance(extra, dict):
+            body.update({k: v for k, v in extra.items() if k != "_links"})
+            body["_links"].update(extra.get("_links", {}))
+
+    doc = client.post("work_packages", json=body, params={"notify": str(notify).lower()})
+    obj.emitter.emit(serialize.work_package(doc))
+
+
+# ------------------------------------------------------------------- update
+@app.command()
+def update(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    subject: str = typer.Option(None, "--subject", help="New subject."),
+    description: str = typer.Option(None, "--description", "-d", help="New description."),
+    status: str = typer.Option(None, "--status", "-s", help="New status name."),
+    type_: str = typer.Option(None, "--type", "-t", help="New type name."),
+    priority: str = typer.Option(None, "--priority", help="New priority."),
+    assignee: str = typer.Option(None, "--assignee", "-a", help="Assignee ('none' to clear)."),
+    responsible: str = typer.Option(None, "--responsible", help="Accountable ('none' to clear)."),
+    parent: str = typer.Option(None, "--parent", help="Parent id ('none' to detach)."),
+    start_date: str = typer.Option(None, "--start-date", help="YYYY-MM-DD."),
+    due_date: str = typer.Option(None, "--due-date", help="YYYY-MM-DD."),
+    estimated: str = typer.Option(None, "--estimated", help="Estimated time (hours or ISO8601)."),
+    done_ratio: int = typer.Option(None, "--done-ratio", help="Percentage done 0-100."),
+    custom_fields: str = typer.Option(None, "--custom-fields", help="JSON of customFieldN values."),
+    set_: str = typer.Option(None, "--set", help="Raw JSON merged into the patch body."),
+    notify: bool = typer.Option(False, "--notify", help="Send notifications for this change."),
+) -> None:
+    """Update a work package. lockVersion is fetched and retried automatically.
+
+    Example: openproject wp update 42 --status "In progress" --assignee jane.doe --done-ratio 50
+    Clear a link with the value 'none' (e.g. --assignee none). Use --set '{...}' for arbitrary fields.
+    """
+    obj = ctx_obj(ctx)
+    client = obj.client()
+
+    body: dict = {"_links": {}}
+    if subject is not None:
+        body["subject"] = subject
+    if description is not None:
+        body["description"] = {"raw": description}
+    if start_date is not None:
+        body["startDate"] = start_date
+    if due_date is not None:
+        body["dueDate"] = due_date
+    if estimated is not None:
+        body["estimatedTime"] = parse_hours_input(estimated)
+    if done_ratio is not None:
+        body["percentageDone"] = done_ratio
+    if status:
+        set_link(body, "status", resolve.status(client, status))
+    if type_:
+        set_link(body, "type", resolve.wp_type(client, type_))
+    if priority:
+        set_link(body, "priority", resolve.priority(client, priority))
+    if assignee is not None:
+        set_link(body, "assignee", None if assignee.lower() == "none" else resolve.user(client, assignee))
+    if responsible is not None:
+        set_link(body, "responsible", None if responsible.lower() == "none" else resolve.user(client, responsible))
+    if parent is not None:
+        set_link(body, "parent", None if parent.lower() == "none" else f"/api/v3/work_packages/{parent}")
+    apply_custom_fields(body, custom_fields)
+    if set_:
+        extra = parse_json_option(set_, what="--set")
+        if isinstance(extra, dict):
+            body.update({k: v for k, v in extra.items() if k != "_links"})
+            body["_links"].update(extra.get("_links", {}))
+    if not body.get("_links"):
+        body.pop("_links")
+    if not body:
+        raise OpError("nothing to update — pass at least one field")
+
+    doc = client.update_locked(f"work_packages/{wp_id}", body, params={"notify": str(notify).lower()})
+    obj.emitter.emit(serialize.work_package(doc))
+
+
+# --------------------------------------------------------------------- move
+@app.command()
+def move(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    project: str = typer.Argument(..., help="Destination project id/identifier."),
+    type_: str = typer.Option(None, "--type", "-t", help="New type (if not valid in target project)."),
+) -> None:
+    """Move a work package to another project."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    body: dict = {"_links": {"project": {"href": f"/api/v3/projects/{pid}"}}}
+    if type_:
+        body["_links"]["type"] = {"href": resolve.wp_type(client, type_)}
+    doc = client.update_locked(f"work_packages/{wp_id}", body)
+    obj.emitter.emit(serialize.work_package(doc))
+
+
+# ------------------------------------------------------------------- delete
+@app.command()
+def delete(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation."),
+) -> None:
+    """Delete a work package."""
+    obj = ctx_obj(ctx)
+    if not yes:
+        typer.confirm(f"Delete work package {wp_id}?", abort=True)
+    obj.client().delete(f"work_packages/{wp_id}")
+    obj.emitter.emit({"status": "deleted", "workPackage": wp_id})
+
+
+# ------------------------------------------------------- assignee shortcuts
+@app.command()
+def assign(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    user: str = typer.Argument(..., help="Assignee (login/name/id or 'me'; 'none' to unassign)."),
+) -> None:
+    """Set (or clear with 'none') the assignee."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    href = None if user.lower() == "none" else resolve.user(client, user)
+    doc = client.update_locked(f"work_packages/{wp_id}", {"_links": {"assignee": {"href": href}}})
+    obj.emitter.emit(serialize.work_package(doc))
+
+
+@app.command()
+def unassign(ctx: typer.Context, wp_id: int = typer.Argument(..., help="Work package id.")) -> None:
+    """Remove the assignee."""
+    obj = ctx_obj(ctx)
+    doc = obj.client().update_locked(f"work_packages/{wp_id}", {"_links": {"assignee": {"href": None}}})
+    obj.emitter.emit(serialize.work_package(doc))
+
+
+@app.command()
+def assignees(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+) -> None:
+    """List users assignable to this work package."""
+    obj = ctx_obj(ctx)
+    rows = [serialize.principal(p) for p in obj.client().collect(f"work_packages/{wp_id}/available_assignees")]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name"), ("Login", "login"), ("Type", "type")])
+
+
+# ----------------------------------------------------------------- watchers
+@app.command()
+def watchers(ctx: typer.Context, wp_id: int = typer.Argument(..., help="Work package id.")) -> None:
+    """List watchers of a work package."""
+    obj = ctx_obj(ctx)
+    rows = [serialize.principal(p) for p in obj.client().collect(f"work_packages/{wp_id}/watchers")]
+    obj.emitter.emit(rows, columns=[("ID", "id"), ("Name", "name"), ("Login", "login")])
+
+
+@app.command()
+def watch(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    user: str = typer.Argument("me", help="User to add as watcher (default: me)."),
+) -> None:
+    """Add a watcher (note: body key is 'user', not under _links)."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    href = resolve.user(client, user)
+    client.post(f"work_packages/{wp_id}/watchers", json={"user": {"href": href}})
+    obj.emitter.emit({"status": "watching", "workPackage": wp_id, "user": href})
+
+
+@app.command()
+def unwatch(
+    ctx: typer.Context,
+    wp_id: int = typer.Argument(..., help="Work package id."),
+    user: str = typer.Argument("me", help="User to remove (default: me)."),
+) -> None:
+    """Remove a watcher."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    href = resolve.user(client, user)
+    uid = hal.id_from_href(href)
+    client.delete(f"work_packages/{wp_id}/watchers/{uid}")
+    obj.emitter.emit({"status": "unwatched", "workPackage": wp_id, "user": uid})
+
+
+# ------------------------------------------------------------------- schema
+@app.command()
+def schema(
+    ctx: typer.Context,
+    project: str = typer.Option(..., "--project", "-P", help="Project id/identifier."),
+    type_: str = typer.Option("Task", "--type", "-t", help="Type name."),
+) -> None:
+    """Discover the create schema (fields, required flags, custom fields) via the form."""
+    obj = ctx_obj(ctx)
+    client = obj.client()
+    pid = resolve.project_id(client, project)
+    body = {"_links": {"project": {"href": f"/api/v3/projects/{pid}"}, "type": {"href": resolve.wp_type(client, type_)}}}
+    form = client.post(f"projects/{pid}/work_packages/form", json=body)
+    sch = (form.get("_embedded") or {}).get("schema") or {}
+    fields = [
+        serialize.custom_field_schema(name, spec)
+        for name, spec in sch.items()
+        if isinstance(spec, dict) and spec.get("type")
+    ]
+    obj.emitter.emit(fields, columns=[("Key", "key"), ("Name", "name"), ("Type", "type"), ("Required", "required"), ("Writable", "writable")])

opcli/config.py

@@ -0,0 +1,134 @@
+"""Non-secret configuration: connection profiles.
+
+Config lives in a plain JSON file (``~/.config/op-cli/config.json`` by
+default). It never contains the API token — that is kept in the OS keyring by
+:mod:`opcli.credentials`. Multiple named *profiles* let one operator point the
+CLI at several OpenProject instances (e.g. ``prod`` and ``staging``).
+
+Environment overrides (useful for CI and the test-suite):
+
+* ``OPCLI_BASE_URL`` — overrides the active profile's base URL.
+* ``OPCLI_PROFILE``  — selects the active profile.
+* ``OPCLI_TOKEN``    — supplies the token directly (see :mod:`credentials`).
+* ``OPCLI_CONFIG_DIR`` / ``XDG_CONFIG_HOME`` — relocate the config directory.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from .errors import ConfigError
+
+DEFAULT_PROFILE = "default"
+
+
+def config_dir() -> Path:
+    base = os.environ.get("OPCLI_CONFIG_DIR")
+    if base:
+        return Path(base)
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    root = Path(xdg) if xdg else Path.home() / ".config"
+    return root / "op-cli"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+@dataclass
+class Profile:
+    name: str
+    base_url: str
+    username: str | None = None  # informational; the login of the API user
+    verify_ssl: bool = True
+
+    def api_root(self) -> str:
+        return self.base_url.rstrip("/") + "/api/v3"
+
+
+@dataclass
+class Config:
+    current_profile: str = DEFAULT_PROFILE
+    profiles: dict[str, Profile] = field(default_factory=dict)
+    default_format: str | None = None  # json | table | markdown; None = not yet chosen
+
+    # ---- persistence -------------------------------------------------
+    @classmethod
+    def load(cls) -> "Config":
+        path = config_path()
+        if not path.exists():
+            return cls()
+        try:
+            raw = json.loads(path.read_text())
+            profiles = {
+                name: Profile(
+                    name=name,
+                    base_url=p["base_url"],
+                    username=p.get("username"),
+                    verify_ssl=p.get("verify_ssl", True),
+                )
+                for name, p in raw.get("profiles", {}).items()
+            }
+            return cls(
+                current_profile=raw.get("current_profile", DEFAULT_PROFILE),
+                profiles=profiles,
+                default_format=raw.get("default_format"),
+            )
+        except (ValueError, KeyError, TypeError, AttributeError) as exc:
+            raise ConfigError(f"malformed config at {path}: {exc}") from exc
+
+    def save(self) -> None:
+        path = config_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        data: dict[str, Any] = {
+            "current_profile": self.current_profile,
+            "default_format": self.default_format,
+            "profiles": {
+                name: {
+                    "base_url": p.base_url,
+                    "username": p.username,
+                    "verify_ssl": p.verify_ssl,
+                }
+                for name, p in self.profiles.items()
+            },
+        }
+        path.write_text(json.dumps(data, indent=2) + "\n")
+
+    # ---- resolution --------------------------------------------------
+    def active_profile_name(self) -> str:
+        return os.environ.get("OPCLI_PROFILE") or self.current_profile
+
+    def resolve(self) -> Profile:
+        """Return the effective profile, applying env overrides.
+
+        A profile can be fully synthesised from the environment even with no
+        config file on disk, so ``OPCLI_BASE_URL`` + ``OPCLI_TOKEN`` are enough
+        to run the CLI headless.
+        """
+        name = self.active_profile_name()
+        env_url = os.environ.get("OPCLI_BASE_URL")
+
+        prof = self.profiles.get(name)
+        if prof is None:
+            if env_url:
+                return Profile(name=name, base_url=env_url)
+            raise ConfigError(
+                f"no profile '{name}' configured. Run `openproject auth login` or set OPCLI_BASE_URL."
+            )
+        if env_url:
+            return Profile(
+                name=prof.name,
+                base_url=env_url,
+                username=prof.username,
+                verify_ssl=prof.verify_ssl,
+            )
+        return prof
+
+    def upsert_profile(self, prof: Profile, make_current: bool = True) -> None:
+        self.profiles[prof.name] = prof
+        if make_current:
+            self.current_profile = prof.name

opcli/context.py

@@ -0,0 +1,117 @@
+"""The shared application context stored on Typer's ``ctx.obj``.
+
+Wires together configuration, stored credentials, the HTTP client, and the
+output emitter so every command can reach them without re-plumbing.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Optional
+
+from . import credentials
+from .client import Client
+from .config import Config, Profile
+from .errors import AuthError
+from .output import Emitter, OutputFormat
+
+
+class AppContext:
+    def __init__(
+        self,
+        output: Optional[OutputFormat] = None,
+        color: bool = True,
+        *,
+        interactive: Optional[bool] = None,
+    ):
+        self.config = Config.load()
+        fmt = self._resolve_format(output, interactive)
+        env_fields = os.environ.get("OPCLI_CLI_FIELDS")
+        fields = env_fields.split(",") if env_fields else None
+        self.emitter = Emitter(fmt, color=color, fields=fields)
+        self._client: Optional[Client] = None
+
+    # ---- output-format resolution ------------------------------------
+    def _resolve_format(self, output: Optional[OutputFormat], interactive: Optional[bool]) -> OutputFormat:
+        """Precedence: --format anywhere > -o/--output > $OPCLI_FORMAT >
+        saved default > first-run prompt (interactive) > json."""
+        cli = os.environ.get("OPCLI_CLI_FORMAT")  # set by `--format/-f` (main pre-parse)
+        if cli:
+            try:
+                return OutputFormat.coerce(cli)
+            except ValueError:
+                pass
+        if output is not None:
+            return output
+        env = os.environ.get("OPCLI_FORMAT")
+        if env:
+            try:
+                return OutputFormat.coerce(env)
+            except ValueError:
+                pass
+        if self.config.default_format:
+            try:
+                return OutputFormat.coerce(self.config.default_format)
+            except ValueError:
+                pass
+        if interactive is None:
+            interactive = sys.stdin.isatty() and sys.stdout.isatty()
+        if interactive:
+            chosen = self._prompt_default_format()
+            if chosen is not None:
+                self.config.default_format = chosen.value
+                try:
+                    self.config.save()
+                except Exception:
+                    pass
+                return chosen
+        return OutputFormat.json
+
+    def _prompt_default_format(self) -> Optional[OutputFormat]:
+        # Prompt on stderr so stdout (the real command output) stays clean.
+        try:
+            sys.stderr.write(
+                "\nFirst run — choose a default output format (saved for next time):\n"
+                "  1) json      structured, best for scripts & agents (default)\n"
+                "  2) table     human-readable terminal tables\n"
+                "  3) markdown  paste-into-docs tables\n"
+                "Enter 1/2/3 [1]: "
+            )
+            sys.stderr.flush()
+            ans = sys.stdin.readline().strip().lower()
+        except Exception:
+            return None
+        return {
+            "": OutputFormat.json, "1": OutputFormat.json, "json": OutputFormat.json,
+            "2": OutputFormat.table, "table": OutputFormat.table,
+            "3": OutputFormat.markdown, "markdown": OutputFormat.markdown, "md": OutputFormat.markdown,
+        }.get(ans, OutputFormat.json)
+
+    @property
+    def output(self) -> OutputFormat:
+        return self.emitter.fmt
+
+    def profile(self) -> Profile:
+        return self.config.resolve()
+
+    def token(self) -> Optional[str]:
+        return credentials.get_token(self.config.active_profile_name())
+
+    def client(self) -> Client:
+        if self._client is not None:
+            return self._client
+        prof = self.profile()
+        token = self.token()
+        if not token:
+            raise AuthError(
+                f"no API token for profile '{prof.name}'. Run `openproject auth login` "
+                f"(or set OPCLI_TOKEN)."
+            )
+        self._client = Client(prof.base_url, token, verify_ssl=prof.verify_ssl)
+        return self._client
+
+    def close(self) -> None:
+        if self._client is not None:
+            self._client.close()
+            self._client = None