feat(base): add base block shortcuts (#1044)

* feat(base): add base block shortcuts

* fix(base): use block scopes for base block shortcuts

* fix(base): split base block shortcut scopes

* docs(base): consolidate base block help

* docs(base): simplify block help wording

* test(base): cover base block shortcut execution

* feat(base): filter base block list by type

* docs(base): clarify base block ids

* docs(base): simplify docx block help

* docs(base): refine base block agent help

Author: zgz2048

shortcuts/base/base_block_create.go

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var BaseBaseBlockCreate = common.Shortcut{
+	Service:     "base",
+	Command:     "+base-block-create",
+	Description: "Create a block",
+	Risk:        "write",
+	Scopes:      []string{"base:block:create"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		{Name: "type", Desc: "resource type", Required: true, Enum: baseBlockTypeEnums},
+		{Name: "name", Desc: "block name", Required: true},
+		{Name: "parent-id", Desc: "folder block id; when omitted, create at root"},
+	},
+	Tips: []string{
+		"Example: lark-cli base +base-block-create --base-token <base_token> --type folder --name \"Project Docs\"",
+		"Example: lark-cli base +base-block-create --base-token <base_token> --type table --name \"Tasks\"",
+		"Example: lark-cli base +base-block-create --base-token <base_token> --type docx --name \"Spec\" --parent-id <folder_block_id>",
+		"Example: lark-cli base +base-block-create --base-token <base_token> --type dashboard --name \"Metrics\"",
+		"Example: lark-cli base +base-block-create --base-token <base_token> --type workflow --name \"Approval Flow\"",
+		"Creates a folder, table, docx, dashboard, or workflow entry.",
+		"Do not pass null for --parent-id. Omit it to create at the root level.",
+		"Created resources still use their own commands for content operations, such as table/field/record/docx/dashboard/workflow commands.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBaseBlockCreate(runtime)
+	},
+	DryRun: dryRunBaseBlockCreate,
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeBaseBlockCreate(runtime)
+	},
+}

shortcuts/base/base_block_delete.go

@@ -0,0 +1,35 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var BaseBaseBlockDelete = common.Shortcut{
+	Service:     "base",
+	Command:     "+base-block-delete",
+	Description: "Delete a block",
+	Risk:        "high-risk-write",
+	Scopes:      []string{"base:block:delete"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		baseBlockIDFlag(true),
+	},
+	Tips: []string{
+		"Example: lark-cli base +base-block-delete --base-token <base_token> --block-id <block_id> --yes",
+		"Deletes the block identified by --block-id.",
+		"Recursive folder deletion is not supported. If a folder is not empty, move or delete its children first.",
+		"Different block types may have independent backing resources; deletion follows backend semantics.",
+		"Use +base-block-list first when you need to confirm the target block id.",
+		"If the user already explicitly confirmed this exact delete target, pass --yes without asking again.",
+	},
+	DryRun: dryRunBaseBlockDelete,
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeBaseBlockDelete(runtime)
+	},
+}

shortcuts/base/base_block_list.go

@@ -0,0 +1,43 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var BaseBaseBlockList = common.Shortcut{
+	Service:     "base",
+	Command:     "+base-block-list",
+	Description: "List blocks in a base",
+	Risk:        "read",
+	Scopes:      []string{"base:block:read"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		{Name: "type", Desc: "filter by resource type", Enum: baseBlockTypeEnums},
+		{Name: "parent-id", Desc: "folder block id; when omitted, list all blocks"},
+	},
+	Tips: []string{
+		"Example: lark-cli base +base-block-list --base-token <base_token>",
+		"Example: lark-cli base +base-block-list --base-token <base_token> --type table",
+		"Example: lark-cli base +base-block-list --base-token <base_token> --parent-id <folder_block_id>",
+		`JQ crop: lark-cli base +base-block-list --base-token <base_token> | jq '.blocks[] | {type, name, block_id: .id, parent_id}'`,
+		`JQ crop docx: lark-cli base +base-block-list --base-token <base_token> --type docx | jq '.blocks[] | {name, docx_token}'`,
+		"Blocks are resources managed directly by the base, such as folder, table, docx, dashboard, and workflow.",
+		"For table, dashboard, and workflow blocks, returned id is the table-id, dashboard-id, or workflow-id used by the corresponding commands.",
+		"For docx blocks, use the returned docx_token with docx commands.",
+		"For folder blocks, pass the returned id as --parent-id when creating, listing, or moving blocks inside that folder.",
+		"This command returns the full backend list. It intentionally does not expose limit or offset.",
+		"Pass --type to list only one resource type.",
+		"Pass --parent-id to list only direct children of a folder.",
+		"Dashboard blocks are chart/widget blocks inside a dashboard; use +dashboard-block-* for those.",
+	},
+	DryRun: dryRunBaseBlockList,
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeBaseBlockList(runtime)
+	},
+}

shortcuts/base/base_block_move.go

@@ -0,0 +1,42 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var BaseBaseBlockMove = common.Shortcut{
+	Service:     "base",
+	Command:     "+base-block-move",
+	Description: "Move a block",
+	Risk:        "write",
+	Scopes:      []string{"base:block:update"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		baseBlockIDFlag(true),
+		{Name: "parent-id", Desc: "target folder block id; when omitted, move to root"},
+		{Name: "before-id", Desc: "sibling block id; move the block before this sibling in the target folder/root order"},
+		{Name: "after-id", Desc: "sibling block id; move the block after this sibling in the target folder/root order"},
+	},
+	Tips: []string{
+		"Example: lark-cli base +base-block-move --base-token <base_token> --block-id <block_id> --parent-id <folder_block_id>",
+		"Example: lark-cli base +base-block-move --base-token <base_token> --block-id <block_id> --after-id <sibling_block_id>",
+		"Example: lark-cli base +base-block-move --base-token <base_token> --block-id <block_id> --before-id <sibling_block_id>",
+		"Example: lark-cli base +base-block-move --base-token <base_token> --block-id <block_id>",
+		"Omit --parent-id to move the block to root; do not pass null.",
+		"--before-id and --after-id are mutually exclusive.",
+		"When moving a folder, its children remain under that folder.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBaseBlockMove(runtime)
+	},
+	DryRun: dryRunBaseBlockMove,
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeBaseBlockMove(runtime)
+	},
+}

shortcuts/base/base_block_ops.go

@@ -0,0 +1,179 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+	"strings"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var baseBlockTypeEnums = []string{"folder", "table", "docx", "dashboard", "workflow"}
+
+func baseBlockIDFlag(required bool) common.Flag {
+	return common.Flag{Name: "block-id", Desc: "block id", Required: required}
+}
+
+func dryRunBaseBlockList(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return common.NewDryRunAPI().
+		POST("/open-apis/base/v3/bases/:base_token/blocks/list").
+		Body(buildBaseBlockListBody(runtime)).
+		Set("base_token", runtime.Str("base-token"))
+}
+
+func dryRunBaseBlockCreate(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return common.NewDryRunAPI().
+		POST("/open-apis/base/v3/bases/:base_token/blocks").
+		Body(buildBaseBlockCreateBody(runtime)).
+		Set("base_token", runtime.Str("base-token"))
+}
+
+func dryRunBaseBlockMove(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return common.NewDryRunAPI().
+		POST("/open-apis/base/v3/bases/:base_token/blocks/:block_id/move").
+		Body(buildBaseBlockMoveBody(runtime)).
+		Set("base_token", runtime.Str("base-token")).
+		Set("block_id", runtime.Str("block-id"))
+}
+
+func dryRunBaseBlockRename(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return common.NewDryRunAPI().
+		POST("/open-apis/base/v3/bases/:base_token/blocks/:block_id/rename").
+		Body(map[string]interface{}{"name": strings.TrimSpace(runtime.Str("name"))}).
+		Set("base_token", runtime.Str("base-token")).
+		Set("block_id", runtime.Str("block-id"))
+}
+
+func dryRunBaseBlockDelete(_ context.Context, runtime *common.RuntimeContext) *common.DryRunAPI {
+	return common.NewDryRunAPI().
+		DELETE("/open-apis/base/v3/bases/:base_token/blocks/:block_id").
+		Set("base_token", runtime.Str("base-token")).
+		Set("block_id", runtime.Str("block-id"))
+}
+
+func validateBaseBlockCreate(runtime *common.RuntimeContext) error {
+	if strings.TrimSpace(runtime.Str("name")) == "" {
+		return common.FlagErrorf("--name must not be blank")
+	}
+	if strings.TrimSpace(runtime.Str("type")) == "" {
+		return common.FlagErrorf("--type must not be blank")
+	}
+	return nil
+}
+
+func validateBaseBlockMove(runtime *common.RuntimeContext) error {
+	if strings.TrimSpace(runtime.Str("before-id")) != "" && strings.TrimSpace(runtime.Str("after-id")) != "" {
+		return common.FlagErrorf("--before-id and --after-id are mutually exclusive")
+	}
+	return nil
+}
+
+func validateBaseBlockRename(runtime *common.RuntimeContext) error {
+	if strings.TrimSpace(runtime.Str("name")) == "" {
+		return common.FlagErrorf("--name must not be blank")
+	}
+	return nil
+}
+
+func executeBaseBlockList(runtime *common.RuntimeContext) error {
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "blocks", "list"), nil, buildBaseBlockListBody(runtime))
+	if err != nil {
+		return err
+	}
+	filterBaseBlockListData(data, strings.TrimSpace(runtime.Str("type")))
+	runtime.Out(data, nil)
+	return nil
+}
+
+func executeBaseBlockCreate(runtime *common.RuntimeContext) error {
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "blocks"), nil, buildBaseBlockCreateBody(runtime))
+	if err != nil {
+		return err
+	}
+	runtime.Out(map[string]interface{}{"block": data, "created": true}, nil)
+	return nil
+}
+
+func executeBaseBlockMove(runtime *common.RuntimeContext) error {
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "blocks", runtime.Str("block-id"), "move"), nil, buildBaseBlockMoveBody(runtime))
+	if err != nil {
+		return err
+	}
+	runtime.Out(map[string]interface{}{"block": data, "moved": true}, nil)
+	return nil
+}
+
+func executeBaseBlockRename(runtime *common.RuntimeContext) error {
+	data, err := baseV3Call(runtime, "POST", baseV3Path("bases", runtime.Str("base-token"), "blocks", runtime.Str("block-id"), "rename"), nil, map[string]interface{}{
+		"name": strings.TrimSpace(runtime.Str("name")),
+	})
+	if err != nil {
+		return err
+	}
+	runtime.Out(map[string]interface{}{"block": data, "renamed": true}, nil)
+	return nil
+}
+
+func executeBaseBlockDelete(runtime *common.RuntimeContext) error {
+	data, err := baseV3Call(runtime, "DELETE", baseV3Path("bases", runtime.Str("base-token"), "blocks", runtime.Str("block-id")), nil, nil)
+	if err != nil {
+		return err
+	}
+	runtime.Out(map[string]interface{}{"block": data, "deleted": true}, nil)
+	return nil
+}
+
+func buildBaseBlockListBody(runtime *common.RuntimeContext) map[string]interface{} {
+	body := map[string]interface{}{}
+	if parentID := strings.TrimSpace(runtime.Str("parent-id")); parentID != "" {
+		body["parent_id"] = parentID
+	}
+	return body
+}
+
+func filterBaseBlockListData(data map[string]interface{}, blockType string) {
+	if blockType == "" {
+		return
+	}
+	blocks, ok := data["blocks"].([]interface{})
+	if !ok {
+		return
+	}
+	filtered := make([]interface{}, 0, len(blocks))
+	for _, block := range blocks {
+		blockMap, ok := block.(map[string]interface{})
+		if !ok || blockMap["type"] != blockType {
+			continue
+		}
+		filtered = append(filtered, block)
+	}
+	data["blocks"] = filtered
+	data["total"] = len(filtered)
+}
+
+func buildBaseBlockCreateBody(runtime *common.RuntimeContext) map[string]interface{} {
+	body := map[string]interface{}{
+		"type": strings.TrimSpace(runtime.Str("type")),
+		"name": strings.TrimSpace(runtime.Str("name")),
+	}
+	if parentID := strings.TrimSpace(runtime.Str("parent-id")); parentID != "" {
+		body["parent_id"] = parentID
+	}
+	return body
+}
+
+func buildBaseBlockMoveBody(runtime *common.RuntimeContext) map[string]interface{} {
+	body := map[string]interface{}{"parent_id": nil}
+	if parentID := strings.TrimSpace(runtime.Str("parent-id")); parentID != "" {
+		body["parent_id"] = parentID
+	}
+	if beforeID := strings.TrimSpace(runtime.Str("before-id")); beforeID != "" {
+		body["before_id"] = beforeID
+	}
+	if afterID := strings.TrimSpace(runtime.Str("after-id")); afterID != "" {
+		body["after_id"] = afterID
+	}
+	return body
+}

shortcuts/base/base_block_rename.go

@@ -0,0 +1,37 @@
+// Copyright (c) 2026 Lark Technologies Pte. Ltd.
+// SPDX-License-Identifier: MIT
+
+package base
+
+import (
+	"context"
+
+	"github.com/larksuite/cli/shortcuts/common"
+)
+
+var BaseBaseBlockRename = common.Shortcut{
+	Service:     "base",
+	Command:     "+base-block-rename",
+	Description: "Rename a block",
+	Risk:        "write",
+	Scopes:      []string{"base:block:update"},
+	AuthTypes:   authTypes(),
+	Flags: []common.Flag{
+		baseTokenFlag(true),
+		baseBlockIDFlag(true),
+		{Name: "name", Desc: "new unique block name; must not duplicate another block name in this base", Required: true},
+	},
+	Tips: []string{
+		"Example: lark-cli base +base-block-rename --base-token <base_token> --block-id <block_id> --name \"New name\"",
+		"Renames the block identified by --block-id.",
+		"Block names must be unique in the base; use +base-block-list first when you need to check existing names.",
+		"Use +base-block-list first when you need to resolve the target block id from a visible name.",
+	},
+	Validate: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return validateBaseBlockRename(runtime)
+	},
+	DryRun: dryRunBaseBlockRename,
+	Execute: func(ctx context.Context, runtime *common.RuntimeContext) error {
+		return executeBaseBlockRename(runtime)
+	},
+}