clockify-unofficial-cli 0.2.0__py3-none-any.whl

clockify_unofficial_cli/commands/tag.py

@@ -0,0 +1,107 @@
+import dataclasses
+from dataclasses import dataclass
+from typing import Annotated
+from typing import Final
+
+import typer
+from clockify import TagCreate
+from clockify import TagUpdate
+
+from clockify_unofficial_cli.output.columns import TAGS
+from clockify_unofficial_cli.output.renderer import many
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.prompts import confirm
+from clockify_unofficial_cli.services.listing import list_from_options
+from clockify_unofficial_cli.services.resolve import resolve_tag
+
+APP: Final = typer.Typer(help="Manage workspace tags.", no_args_is_help=True)
+
+
+@APP.command(name="list", help="List every tag in the active workspace.")
+@handle_errors
+def list_tags(
+    ctx: typer.Context,
+    *,
+    limit: Annotated[
+        int | None,
+        typer.Option("--limit", help="Stop after N tags; incompatible with --page/--page-size."),
+    ] = None,
+    page: Annotated[
+        int | None,
+        typer.Option("--page", help="1-based page number when paging through results."),
+    ] = None,
+    page_size: Annotated[
+        int | None,
+        typer.Option("--page-size", help="Page size when paging through results."),
+    ] = None,
+) -> None:
+    app_context = get_app_context(ctx)
+    workspace = app_context.workspace()
+    tags = list_from_options(workspace.tags.list, workspace.tags.list_page, limit, page, page_size)
+    app_context.render(many(tags, TAGS))
+
+
+@APP.command(help="Show a tag by ID or exact name.")
+@handle_errors
+def get(ctx: typer.Context, term: Annotated[str, typer.Argument(help="Tag ID or exact name.")]) -> None:
+    app_context = get_app_context(ctx)
+    tag_id = resolve_tag(app_context, term)
+    tag = app_context.workspace().tags.get(tag_id)
+    app_context.render(single(tag, TAGS))
+
+
+@APP.command(help="Create a new tag.")
+@handle_errors
+def create(ctx: typer.Context, *, name: Annotated[str, typer.Option("--name", help="Tag name.")]) -> None:
+    app_context = get_app_context(ctx)
+    tag = app_context.workspace().tags.create(TagCreate(name=name))
+    app_context.render(single(tag, TAGS))
+
+
+@dataclass(frozen=True, slots=True)
+class _UpdateArgs:
+    name: str | None
+    archived: bool | None
+
+
+@APP.command(help="Update an existing tag.")
+@handle_errors
+def update(
+    ctx: typer.Context,
+    term: Annotated[str, typer.Argument(help="Tag ID or exact name.")],
+    *,
+    name: Annotated[
+        str | None,
+        typer.Option("--name", help="New tag name."),
+    ] = None,
+    archived: Annotated[
+        bool | None,
+        typer.Option("--archived/--no-archived", help="Archive or restore the tag."),
+    ] = None,
+) -> None:
+    args = _UpdateArgs(name=name, archived=archived)
+    app_context = get_app_context(ctx)
+    tag_id = resolve_tag(app_context, term)
+    payload = TagUpdate(**{k: v for k, v in dataclasses.asdict(args).items() if v is not None})
+    tag = app_context.workspace().tags.update(tag_id, payload)
+    app_context.render(single(tag, TAGS))
+
+
+@APP.command(help="Delete a tag.")
+@handle_errors
+def delete(
+    ctx: typer.Context,
+    term: Annotated[str, typer.Argument(help="Tag ID or exact name.")],
+    *,
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the interactive confirmation prompt."),
+    ] = False,
+) -> None:
+    app_context = get_app_context(ctx)
+    confirm(f"Delete tag '{term}'", assume_yes=yes)
+    tag_id = resolve_tag(app_context, term)
+    app_context.workspace().tags.delete(tag_id)
+    app_context.notify(f"Deleted tag '{tag_id}'.")

clockify_unofficial_cli/commands/task.py

@@ -0,0 +1,194 @@
+import dataclasses
+from dataclasses import dataclass
+from typing import Annotated
+from typing import Final
+
+import typer
+from clockify import ProjectId
+from clockify import TaskCreate
+from clockify import TaskStatus
+from clockify import TaskUpdate
+from clockify import UserId
+
+from clockify_unofficial_cli.output.columns import TASKS
+from clockify_unofficial_cli.output.renderer import many
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.params import options_from
+from clockify_unofficial_cli.runtime.prompts import confirm
+from clockify_unofficial_cli.services.listing import list_from_options
+from clockify_unofficial_cli.services.resolve import resolve_project
+from clockify_unofficial_cli.services.resolve import resolve_task
+
+APP: Final = typer.Typer(help="Manage tasks inside a project.", no_args_is_help=True)
+
+
+def _project_id(app_context: object, term: str) -> ProjectId:
+    resolved = resolve_project(app_context, term)  # type: ignore[arg-type]
+    return ProjectId(resolved)
+
+
+@dataclass(frozen=True, slots=True)
+class _ListArgs:
+    project: str
+    limit: int | None
+    page: int | None
+    page_size: int | None
+
+
+@APP.command(name="list", help="List tasks for the named project.")
+@handle_errors
+def list_tasks(
+    ctx: typer.Context,
+    *,
+    project: Annotated[str, typer.Option("--project", "-P", help="Project ID or exact name.")],
+    limit: Annotated[
+        int | None,
+        typer.Option("--limit", help="Stop after N tasks; incompatible with --page/--page-size."),
+    ] = None,
+    page: Annotated[
+        int | None,
+        typer.Option("--page", help="1-based page number when paging through results."),
+    ] = None,
+    page_size: Annotated[
+        int | None,
+        typer.Option("--page-size", help="Page size when paging through results."),
+    ] = None,
+) -> None:
+    args = _ListArgs(project=project, limit=limit, page=page, page_size=page_size)
+    app_context = get_app_context(ctx)
+    workspace = app_context.workspace()
+    project_id = _project_id(app_context, args.project)
+    tasks = list_from_options(
+        lambda: workspace.tasks.list(project_id),
+        lambda **kwargs: workspace.tasks.list_page(project_id, **kwargs),
+        args.limit,
+        args.page,
+        args.page_size,
+    )
+    app_context.render(many(tasks, TASKS))
+
+
+@dataclass(frozen=True, slots=True)
+class _TaskProjectArgs:
+    project: str
+
+
+@APP.command(help="Show a task by ID or name within the named project.")
+@handle_errors
+def get(
+    ctx: typer.Context,
+    term: Annotated[str, typer.Argument(help="Task ID or exact name.")],
+    *,
+    project: Annotated[str, typer.Option("--project", "-P", help="Project ID or exact name.")],
+) -> None:
+    args = _TaskProjectArgs(project=project)
+    app_context = get_app_context(ctx)
+    project_id = _project_id(app_context, args.project)
+    task_id = resolve_task(app_context, project_id, term)
+    task = app_context.workspace().tasks.get(project_id, task_id)
+    app_context.render(single(task, TASKS))
+
+
+@dataclass(frozen=True, slots=True)
+class _CreateArgs:
+    project: str
+    name: str
+    assignee_ids: list[UserId] | None
+    estimate: str | None
+    status: TaskStatus | None
+
+
+@dataclass(frozen=True, slots=True)
+class _CreateOptions:
+    project: Annotated[str, typer.Option("--project", "-P", help="Project ID or exact name.")]
+    name: Annotated[str, typer.Option("--name", help="Task display name.")]
+    assignee: Annotated[str | None, typer.Option("--assignee", help="Assignee user ID.")] = None
+    estimate: Annotated[
+        str | None,
+        typer.Option("--estimate", help="ISO-8601 duration estimate, e.g. PT2H30M."),
+    ] = None
+    status: Annotated[
+        TaskStatus | None,
+        typer.Option("--status", case_sensitive=False, help="ACTIVE or DONE."),
+    ] = None
+
+
+@APP.command(help="Create a new task under the named project.")
+@handle_errors
+@options_from(_CreateOptions)
+def create(ctx: typer.Context, options: _CreateOptions) -> None:
+    args = _CreateArgs(
+        project=options.project,
+        name=options.name,
+        assignee_ids=[UserId(options.assignee)] if options.assignee else None,
+        estimate=options.estimate,
+        status=options.status,
+    )
+    app_context = get_app_context(ctx)
+    project_id = _project_id(app_context, args.project)
+    payload = TaskCreate(**{k: v for k, v in dataclasses.asdict(args).items() if v is not None and k != "project"})
+    task = app_context.workspace().tasks.create(project_id, payload)
+    app_context.render(single(task, TASKS))
+
+
+@dataclass(frozen=True, slots=True)
+class _UpdateArgs:
+    project: str
+    name: str | None
+    assignee_ids: list[UserId] | None
+    estimate: str | None
+    status: TaskStatus | None
+
+
+@dataclass(frozen=True, slots=True)
+class _UpdateOptions:
+    term: Annotated[str, typer.Argument(help="Task ID or exact name.")]
+    project: Annotated[str, typer.Option("--project", "-P", help="Project ID or exact name.")]
+    name: Annotated[str | None, typer.Option("--name", help="New task display name.")] = None
+    assignee: Annotated[str | None, typer.Option("--assignee", help="New assignee user ID.")] = None
+    estimate: Annotated[str | None, typer.Option("--estimate", help="New ISO-8601 duration estimate.")] = None
+    status: Annotated[
+        TaskStatus | None,
+        typer.Option("--status", case_sensitive=False, help="ACTIVE or DONE."),
+    ] = None
+
+
+@APP.command(help="Update an existing task.")
+@handle_errors
+@options_from(_UpdateOptions)
+def update(ctx: typer.Context, options: _UpdateOptions) -> None:
+    args = _UpdateArgs(
+        project=options.project,
+        name=options.name,
+        assignee_ids=[UserId(options.assignee)] if options.assignee else None,
+        estimate=options.estimate,
+        status=options.status,
+    )
+    app_context = get_app_context(ctx)
+    project_id = _project_id(app_context, args.project)
+    task_id = resolve_task(app_context, project_id, options.term)
+    payload = TaskUpdate(**{k: v for k, v in dataclasses.asdict(args).items() if v is not None and k != "project"})
+    task = app_context.workspace().tasks.update(project_id, task_id, payload)
+    app_context.render(single(task, TASKS))
+
+
+@APP.command(help="Delete a task.")
+@handle_errors
+def delete(
+    ctx: typer.Context,
+    term: Annotated[str, typer.Argument(help="Task ID or exact name.")],
+    *,
+    project: Annotated[str, typer.Option("--project", "-P", help="Project ID or exact name.")],
+    yes: Annotated[
+        bool,
+        typer.Option("--yes", "-y", help="Skip the interactive confirmation prompt."),
+    ] = False,
+) -> None:
+    app_context = get_app_context(ctx)
+    confirm(f"Delete task '{term}'", assume_yes=yes)
+    project_id = _project_id(app_context, project)
+    task_id = resolve_task(app_context, project_id, term)
+    app_context.workspace().tasks.delete(project_id, task_id)
+    app_context.notify(f"Deleted task '{task_id}'.")

clockify_unofficial_cli/commands/timer_shortcuts.py

@@ -0,0 +1,130 @@
+from dataclasses import dataclass
+from typing import Annotated
+from typing import Final
+
+import typer
+from clockify import ProjectId
+from clockify import TagId
+from clockify import TaskId
+
+from clockify_unofficial_cli.output.columns import TIME_ENTRIES
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.output.renderer import to_record
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+from clockify_unofficial_cli.runtime.params import options_from
+from clockify_unofficial_cli.services.resolve import resolve_project
+from clockify_unofficial_cli.services.resolve import resolve_tag
+from clockify_unofficial_cli.services.resolve import resolve_task
+from clockify_unofficial_cli.services.timer import LogRequest
+from clockify_unofficial_cli.services.timer import TimerRequest
+from clockify_unofficial_cli.services.timer import log_entry
+from clockify_unofficial_cli.services.timer import parse_optional_duration
+from clockify_unofficial_cli.services.timer import parse_optional_instant
+from clockify_unofficial_cli.services.timer import running_entry
+from clockify_unofficial_cli.services.timer import start_timer
+from clockify_unofficial_cli.services.timer import stop_timer
+
+APP: Final = typer.Typer(help="Timer shortcuts (start/stop/status/log).", no_args_is_help=True)
+
+
+@dataclass(frozen=True, slots=True)
+class _StartOptions:
+    description: Annotated[str | None, typer.Argument(help="Entry description.")] = None
+    project: Annotated[str | None, typer.Option("--project", "-P", help="Project ID or exact name.")] = None
+    task: Annotated[str | None, typer.Option("--task", "-t", help="Task ID or exact name; requires --project.")] = None
+    tag: Annotated[list[str] | None, typer.Option("--tag", help="Tag ID or exact name; pass multiple times.")] = None
+    billable: Annotated[bool, typer.Option("--billable/--no-billable", help="Mark the entry as billable.")] = False
+    from_: Annotated[str | None, typer.Option("--from", help="Start instant; defaults to now.")] = None
+
+
+@APP.command(name="start", help="Start a new running timer; defaults to `now` when --from is omitted.")
+@handle_errors
+@options_from(_StartOptions)
+def start_cmd(ctx: typer.Context, options: _StartOptions) -> None:
+    if options.task and not options.project:
+        message = "--task requires --project because tasks are scoped to projects."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    app_context = get_app_context(ctx)
+    project_id = ProjectId(resolve_project(app_context, options.project)) if options.project else None
+    task_id = TaskId(resolve_task(app_context, project_id, options.task)) if options.task and project_id else None
+    request = TimerRequest(
+        description=options.description,
+        project_id=project_id,
+        task_id=task_id,
+        tag_ids=tuple(TagId(resolve_tag(app_context, term)) for term in (options.tag or ())),
+        billable=options.billable,
+        start=parse_optional_instant(options.from_),
+        end=None,
+        duration=None,
+    )
+    entry = start_timer(app_context, request)
+    app_context.render(single(_entry_as_record(entry), TIME_ENTRIES))
+
+
+@APP.command(name="stop", help="Stop the currently running timer.")
+@handle_errors
+def stop_cmd(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    entry = stop_timer(app_context, end=None)
+    app_context.render(single(_entry_as_record(entry), TIME_ENTRIES))
+
+
+@APP.command(
+    name="status", help="Show the currently running timer; exits OK with a stderr notice when none is active."
+)
+@handle_errors
+def status_cmd(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    entry = running_entry(app_context)
+    if entry is None:
+        app_context.notify("No timer running.")
+        raise typer.Exit(ExitCode.OK)
+    app_context.render(single(_entry_as_record(entry), TIME_ENTRIES))
+
+
+@dataclass(frozen=True, slots=True)
+class _LogOptions:
+    description: Annotated[str | None, typer.Option("--description", help="Entry description.")] = None
+    project: Annotated[str | None, typer.Option("--project", "-P", help="Project ID or exact name.")] = None
+    task: Annotated[str | None, typer.Option("--task", "-t", help="Task ID or exact name; requires --project.")] = None
+    tag: Annotated[list[str] | None, typer.Option("--tag", help="Tag ID or exact name; pass multiple times.")] = None
+    billable: Annotated[bool, typer.Option("--billable/--no-billable", help="Mark the entry as billable.")] = False
+    from_: Annotated[str | None, typer.Option("--from", help="Start instant.")] = None
+    to: Annotated[str | None, typer.Option("--to", help="End instant.")] = None
+    duration: Annotated[str | None, typer.Option("--duration", help="Duration, e.g. 1h30m.")] = None
+
+
+@APP.command(name="log", help="Log a finished entry; --duration with one of --from/--to, or both --from and --to.")
+@handle_errors
+@options_from(_LogOptions)
+def log_cmd(ctx: typer.Context, options: _LogOptions) -> None:
+    if options.task and not options.project:
+        message = "--task requires --project because tasks are scoped to projects."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    if options.from_ is None and options.to is None and options.duration is None:
+        message = "`log` needs --from/--to or --duration."
+        raise CliError(message, exit_code=ExitCode.USAGE)
+    app_context = get_app_context(ctx)
+    project_id = ProjectId(resolve_project(app_context, options.project)) if options.project else None
+    task_id = TaskId(resolve_task(app_context, project_id, options.task)) if options.task and project_id else None
+    request = LogRequest(
+        description=options.description,
+        project_id=project_id,
+        task_id=task_id,
+        tag_ids=tuple(TagId(resolve_tag(app_context, term)) for term in (options.tag or ())),
+        billable=options.billable,
+        start=parse_optional_instant(options.from_),
+        end=parse_optional_instant(options.to),
+        duration=parse_optional_duration(options.duration),
+    )
+    entry = log_entry(app_context, request=request)
+    app_context.render(single(_entry_as_record(entry), TIME_ENTRIES))
+
+
+# Wrap the SDK time-entry object into a dict mapping so the renderer's to_record
+# coercion accepts it without mypy complaining about `object` not being a BaseModel.
+def _entry_as_record(entry: object) -> dict[str, object]:
+    return dict(to_record(entry))

clockify_unofficial_cli/commands/user.py

@@ -0,0 +1,45 @@
+from typing import Annotated
+from typing import Final
+
+import typer
+
+from clockify_unofficial_cli.output.columns import USERS
+from clockify_unofficial_cli.output.renderer import many
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.services.listing import list_from_options
+
+APP: Final = typer.Typer(help="Show the authenticated user and workspace members.", no_args_is_help=True)
+
+
+@APP.command(help="Show the API key owner.")
+@handle_errors
+def me(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    user = app_context.client().user.me()
+    app_context.render(single(user, USERS))
+
+
+@APP.command(name="list", help="List every user visible in the active workspace.")
+@handle_errors
+def list_users(
+    ctx: typer.Context,
+    *,
+    limit: Annotated[
+        int | None,
+        typer.Option("--limit", help="Stop after N users; incompatible with --page/--page-size."),
+    ] = None,
+    page: Annotated[
+        int | None,
+        typer.Option("--page", help="1-based page number when paging through results."),
+    ] = None,
+    page_size: Annotated[
+        int | None,
+        typer.Option("--page-size", help="Page size when paging through results."),
+    ] = None,
+) -> None:
+    app_context = get_app_context(ctx)
+    workspace = app_context.workspace()
+    users = list_from_options(workspace.users.list, workspace.users.list_page, limit, page, page_size)
+    app_context.render(many(users, USERS))

clockify_unofficial_cli/commands/workspace.py

@@ -0,0 +1,68 @@
+from typing import Annotated
+from typing import Final
+
+import typer
+
+from clockify_unofficial_cli.output.columns import WORKSPACES
+from clockify_unofficial_cli.output.renderer import many
+from clockify_unofficial_cli.output.renderer import single
+from clockify_unofficial_cli.output.renderer import to_record
+from clockify_unofficial_cli.runtime.context import get_app_context
+from clockify_unofficial_cli.runtime.errors import CliError
+from clockify_unofficial_cli.runtime.errors import handle_errors
+from clockify_unofficial_cli.runtime.exit_codes import ExitCode
+from clockify_unofficial_cli.services.resolve import Candidate
+from clockify_unofficial_cli.services.resolve import resolve
+
+APP: Final = typer.Typer(help="Inspect and select the Clockify workspace.", no_args_is_help=True)
+
+
+@APP.command(name="list", help="List every workspace the API key can see.")
+@handle_errors
+def list_workspaces(ctx: typer.Context) -> None:
+    app_context = get_app_context(ctx)
+    workspaces = app_context.client().workspaces.list()
+    app_context.render(many(workspaces, WORKSPACES))
+
+
+@APP.command(help="Show a workspace by ID or name; defaults to the active one.")
+@handle_errors
+def get(
+    ctx: typer.Context,
+    workspace_id: Annotated[
+        str | None,
+        typer.Argument(help="Workspace ID or exact name; defaults to the resolved workspace."),
+    ] = None,
+) -> None:
+    app_context = get_app_context(ctx)
+    if workspace_id is None:
+        workspace = app_context.workspace()
+        app_context.render(single({"id": str(workspace.id), "name": "<active workspace>"}, WORKSPACES))
+        return
+    workspaces = app_context.client().workspaces.list()
+    candidates = [Candidate(id=str(item.id), name=item.name) for item in workspaces]
+    resolved_id = resolve(workspace_id, candidates, noun="workspace")
+    record: dict[str, object] = dict(next(to_record(item) for item in workspaces if str(item.id) == resolved_id))
+    app_context.render(single(record, WORKSPACES))
+
+
+@APP.command(help="Persist the workspace choice in the active profile.")
+@handle_errors
+def use(
+    ctx: typer.Context,
+    workspace_id: Annotated[str, typer.Argument(help="Workspace ID or exact name to make the default.")],
+) -> None:
+    app_context = get_app_context(ctx)
+    workspaces = app_context.client().workspaces.list()
+    candidates = [Candidate(id=str(item.id), name=item.name) for item in workspaces]
+    resolved_id = resolve(workspace_id, candidates, noun="workspace")
+    store = app_context.services.settings
+    settings = store.load()
+    options = app_context.options
+    if options.profile_name not in settings.profiles:
+        message = f"No profile named '{options.profile_name}'; run `clockify auth login`."
+        raise CliError(message, exit_code=ExitCode.CONFIGURATION)
+    profile = settings.profiles[options.profile_name]
+    updated = profile.model_copy(update={"workspace_id": resolved_id})
+    store.save(settings.with_profile(options.profile_name, updated))
+    app_context.notify(f"Workspace set to '{resolved_id}' for profile '{options.profile_name}'.")

clockify_unofficial_cli/config/paths.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from os import environ
+from pathlib import Path
+from typing import Final
+
+from platformdirs import user_config_path
+
+APP_NAME: Final = "clockify-cli"
+CONFIG_DIR_ENV_VAR: Final = "CLOCKIFY_CLI_CONFIG_DIR"
+
+
+def config_dir() -> Path:
+    override = environ.get(CONFIG_DIR_ENV_VAR)
+    if override:
+        return Path(override)
+    return user_config_path(APP_NAME)
+
+
+def settings_file() -> Path:
+    return config_dir() / "config.toml"
+
+
+def credentials_file() -> Path:
+    return config_dir() / "credentials.toml"

clockify_unofficial_cli/config/settings.py

@@ -0,0 +1,75 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Final
+
+from clockify import Region
+from pydantic import BaseModel
+from pydantic import ConfigDict
+
+DEFAULT_PROFILE: Final = "default"
+
+
+class OutputFormat(StrEnum):
+    TABLE = "table"
+    JSON = "json"
+    JSONL = "jsonl"
+    CSV = "csv"
+    ID = "id"
+
+
+class Profile(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    region: Region = Region.GLOBAL
+    workspace_id: str | None = None
+    user_id: str | None = None
+    email: str | None = None
+
+
+class Settings(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    default_profile: str = DEFAULT_PROFILE
+    output: OutputFormat | None = None
+    profiles: dict[str, Profile] = {}
+
+    def with_profile(self, name: str, profile: Profile) -> Settings:
+        return self.model_copy(update={"profiles": {**self.profiles, name: profile}})
+
+    def without_profile(self, name: str) -> Settings:
+        remaining = {key: value for key, value in self.profiles.items() if key != name}
+        return self.model_copy(update={"profiles": remaining})
+
+
+# Flag and environment values arrive already merged by Typer (flag wins over envvar).
+@dataclass(frozen=True, slots=True)
+class GlobalOptions:
+    profile: str | None = None
+    workspace: str | None = None
+    output: OutputFormat | None = None
+    verbose: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class ResolvedOptions:
+    profile_name: str
+    profile: Profile
+    workspace_id: str | None
+    output: OutputFormat
+    verbose: bool
+
+
+def resolve_options(options: GlobalOptions, settings: Settings, *, is_tty: bool) -> ResolvedOptions:
+    profile_name = options.profile or settings.default_profile
+    profile = settings.profiles.get(profile_name, Profile())
+    # Humans get tables; pipes get machine-readable JSON unless something explicit says otherwise.
+    fallback_output = OutputFormat.TABLE if is_tty else OutputFormat.JSON
+    return ResolvedOptions(
+        profile_name=profile_name,
+        profile=profile,
+        workspace_id=options.workspace or profile.workspace_id,
+        output=options.output or settings.output or fallback_output,
+        verbose=options.verbose,
+    )