larksuite / larksuite/cli

[Base] Add +role-member-list/+role-member-add/+role-member-remove shortcuts for custom role collaborators

Open
#2,652 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug domain/base
Dominant language
Go
Stars
17.3k
Forks
1.4k
Avg merge
2d 4h
Merged PRs (30d)
105

Description

Prerequisites
  • I searched existing issues and discussions, this is not already proposed.
  • This is a concrete, actionable proposal, not a vague wish.
Problem or motivation

The Base domain covers custom roles (+role-create, +role-get, +role-list, +role-update, +role-delete) but not the collaborator-assignment half: there is no way to list, add, or remove members of a role. Agents must fall back to the raw API:

lark-cli api GET /open-apis/bitable/v1/apps/<app_token>/roles/<role_id>/members
lark-cli api POST /open-apis/bitable/v1/apps/<app_token>/roles/<role_id>/members/batch_create
lark-cli api POST /open-apis/bitable/v1/apps/<app_token>/roles/<role_id>/members/batch_delete

The apps domain already ships +role-member-list, +role-member-add, and +role-member-remove for Miaoda app roles, so the command shape exists in the CLI, just not for Base advanced-permission roles.

Proposed solution

Three shortcuts under base:

  • +role-member-list --base-token --role-id [--member-id-type] [--page-size] [--page-token] (risk: read, scope: base:collaborator:read)
  • +role-member-add --base-token --role-id --member-ids [--member-id-type] (risk: write, scope: base:collaborator:create, max 100 IDs per call)
  • +role-member-remove --base-token --role-id --member-ids [--member-id-type] (risk: high-risk-write, scope: base:collaborator:delete)

Notes from verifying the endpoints against a live tenant:

  • The granular scopes above are accepted; bitable:app is the broader alternative listed in the docs.
  • member_id_type works as a query parameter, but the batch create/delete payload wants member_list items carrying their own type and id. Sending only id items plus the query parameter silently succeeds without adding anyone.
  • Prereqs worth surfacing in help: advanced permissions must be enabled on the Base and the caller needs manage-level permission, otherwise the API returns 1254301 or 1254302.
  • Adding the Base owner returns success but the owner never appears in the member list. Owners bypass roles; worth a docs note so agents do not retry in a loop.
  • Invalid member IDs fail with 1254048, which gives a good per-ID validation signal.
  • List returns member_name, member_type, open_id, user_id, has_more, page_token, total. The full add, list, remove, list cycle was verified end to end.
Alternatives considered

Keep using lark-cli api raw calls. It works, but loses scope preflight, dry-run previews, typed errors, and risk gating, and agents currently get the per-item type requirement wrong without guidance.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating the existing apps-domain +role-member-list, +role-member-add, and +role-member-remove implementations and compare their command shapes with the Base role endpoints. Implement the three Base shortcuts with the stated scopes, member_list item types, pagination, and risk levels. Done means the list, add, remove, and list cycle works while surfacing the documented permission and per-member errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
api, cli
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.