Groups Commands

CLI commands for managing groups and group membership.

Explicit CLI commands for group management.

register_cli

register_cli(app: Typer, ctx_provider: Callable[[], AppContext], logger: Logger) -> None

Register group management commands.

Source code in qsh/plugins/groups/cli.py

def register_cli(
    app: typer.Typer, ctx_provider: Callable[[], AppContext], logger: logging.Logger
) -> None:
    """Register group management commands."""
    resource_app = typer.Typer(help="Manage groups.", no_args_is_help=True)
    users_app = typer.Typer(help="Manage group membership.", no_args_is_help=True)

    @resource_app.command("list")
    def list_cmd(
        names: Annotated[
            list[str] | None,
            typer.Option(
                "--name",
                help=(
                    "Filter by name using case-insensitive contains matching "
                    "(repeatable, ORed)"
                ),
            ),
        ] = None,
        is_shared: Annotated[
            bool | None,
            typer.Option(
                "--is-shared/--no-is-shared",
                help="Filter by whether the group is shared",
            ),
        ] = None,
        show_all: ShowAllPagesOption = False,
        page: PageOption = 0,
        size: SizeOption = None,
        sort: Annotated[
            str,
            typer.Option(
                "--sort",
                help=(
                    "Sort criteria (default: created_date,desc). "
                    "Format: property,direction."
                ),
            ),
        ] = DEFAULT_GROUP_SORT_ORDER,
        output: OutputOption = None,
        wide: WideOption = False,
    ) -> None:
        """List groups."""
        ctx = ctx_provider()
        logger.debug(
            "Listing groups: names=%s is_shared=%s all=%s page=%s size=%s sort=%s",
            names,
            is_shared,
            show_all,
            page,
            size,
            sort,
        )

        client = GroupsClient(ctx)
        if show_all:
            payload = collect_pages_payload(
                client.iter_pages(
                    size=DEFAULT_ALL_PAGE_SIZE,
                    sort=sort,
                    name=names,
                    is_shared=is_shared,
                )
            )
        else:
            payload = page_to_payload(
                client.list_page(
                    page=page,
                    size=size,
                    sort=sort,
                    name=names,
                    is_shared=is_shared,
                )
            )

        render_with_optional_schema(
            payload,
            _GROUPS_LIST_SCHEMA,
            ctx=ctx,
            output=output,
            wide=wide,
        )

    @resource_app.command("get")
    def get_cmd(
        group: Annotated[str, typer.Argument(help="Group ID or name")],
        output: OutputOption = None,
    ) -> None:
        """Get a group by UUID or name."""
        ctx = ctx_provider()
        logger.debug("Getting group: ref=%s", group)

        client = GroupsClient(ctx)
        result = client.get(id=client.resolve_id(group))
        render(serialize_model(result), output or ctx.effective_output_format, wrap=ctx.wrap)

    @resource_app.command("create")
    def create_cmd(
        data: Annotated[
            str,
            typer.Argument(help="Group data as JSON, @file.json, file://path, or '-' for stdin"),
        ],
        output: OutputOption = None,
    ) -> None:
        """Create a group."""
        ctx = ctx_provider()
        logger.debug("Creating group")

        payload = load_json_like(data)
        model = validate_model_payload(payload, GroupRequest, field_name="group body")
        result = GroupsClient(ctx).create(body=model)
        render(serialize_model(result), output or ctx.effective_output_format, wrap=ctx.wrap)

    @resource_app.command("update")
    def update_cmd(
        group: Annotated[str, typer.Argument(help="Group ID or name")],
        data: Annotated[
            str,
            typer.Argument(
                help="Updated group data as JSON, @file.json, file://path, or '-' for stdin"
            ),
        ],
        output: OutputOption = None,
    ) -> None:
        """Update a group."""
        ctx = ctx_provider()
        logger.debug("Updating group: ref=%s", group)

        payload = load_json_like(data)
        model = validate_model_payload(payload, GroupRequest, field_name="group body")
        client = GroupsClient(ctx)
        result = client.update(id=client.resolve_id(group), body=model)
        render(serialize_model(result), output or ctx.effective_output_format, wrap=ctx.wrap)

    @resource_app.command("delete")
    def delete_cmd(
        group: Annotated[str, typer.Argument(help="Group ID or name")],
    ) -> None:
        """Delete (deactivate) a group."""
        ctx = ctx_provider()
        logger.debug("Deleting group: ref=%s", group)

        client = GroupsClient(ctx)
        client.delete(id=client.resolve_id(group))

    @users_app.command("list")
    def users_list_cmd(
        group: Annotated[str, typer.Argument(help="Group ID or name")],
        page: PageOption = 0,
        size: SizeOption = None,
        output: OutputOption = None,
        wide: WideOption = False,
    ) -> None:
        """List users in a group."""
        ctx = ctx_provider()
        logger.debug(
            "Listing group users: ref=%s page=%s size=%s", group, page, size
        )

        client = GroupsClient(ctx)
        users = client.list_users(id=client.resolve_id(group), page=page, size=size)
        payload = {"users": serialize_models(users)}
        render_with_optional_schema(
            payload,
            _GROUP_USERS_SCHEMA,
            ctx=ctx,
            output=output,
            wide=wide,
        )

    @users_app.command("add")
    def users_add_cmd(
        group: Annotated[str, typer.Argument(help="Group ID or name")],
        user_ids: Annotated[
            list[UUID], typer.Argument(help="User ID(s) to add to the group")
        ],
    ) -> None:
        """Add users to a group."""
        ctx = ctx_provider()
        logger.debug("Adding group users: ref=%s count=%d", group, len(user_ids))

        client = GroupsClient(ctx)
        client.add_users(
            id=client.resolve_id(group), body=GroupMemberRequest(users=user_ids)
        )

    @users_app.command("remove")
    def users_remove_cmd(
        group: Annotated[str, typer.Argument(help="Group ID or name")],
        user_id: Annotated[UUID, typer.Argument(help="User ID")],
    ) -> None:
        """Remove a user from a group."""
        ctx = ctx_provider()
        logger.debug("Removing group user: ref=%s user_id=%s", group, user_id)

        client = GroupsClient(ctx)
        client.remove_user(id=client.resolve_id(group), user_id=user_id)

    resource_app.add_typer(users_app, name="users")
    app.add_typer(resource_app, name="groups")
    logger.debug("Registered groups CLI commands")