siyuan-note/siyuan · error

--ids is required (comma-separated shorthand IDs)

Error message

--ids is required (comma-separated shorthand IDs)

What it means

The `inbox convert` command parses the comma-separated `--ids` flag with parseShorthandIDs; if the resulting list is empty (flag unset, empty string, or only empty segments), the command rejects the invocation. At least one shorthand ID is required to know what to convert.

Solutions

1. Pass at least one shorthand ID: `--ids <id1>` or `--ids <id1,id2,...>` (comma-separated).
2. Verify the IDs exist in the cloud inbox before converting.
3. In scripts, guard: if [ -z "$IDS" ]; then echo "no ids"; exit 1; fi before calling the command.

Example fix

// before
siyuan inbox convert --notebook 20240101120000-abcd123 --ids ""
// after
siyuan inbox convert --notebook 20240101120000-abcd123 --ids abc123,def456

if [ -z "$IDS" ]; then echo "--ids is required"; exit 1; fi
siyuan inbox convert --ids "$IDS" --notebook "$NOTEBOOK"

When it happens

Trigger: Running `siyuan inbox convert --notebook <id>` with no `--ids`, or `--ids ""` / `--ids ",,"` yielding an empty parsed list.

Common situations: Building the ID list programmatically from an empty query result; shell variable expansion producing an empty value; splitting/pasting IDs with wrong separators so nothing parses.

Understand the failure class

Background: "--flag is required" and "must specify" CLI errors: how missing-required-flag validation works and how to fix it — this error's family across 20 libraries.

Related errors

• --av and --ids are required
• --av, --key, --item and --value are required
• --block is required for non-detached rows
• --id and --notebook are required
• --id is required

AI-assisted analysis of siyuan-note/siyuan@9f775e8a12 (2026-09-19). Data as JSON: /api/errors/1c5059192e7f6fc4. Report an issue: GitHub.

Appendix: source

Thrown at kernel/cli/cmd/inbox.go:135

		return nil
	},
}

// inboxConvertCmd 把一条或多条剪藏转为本地文档：取云端 md → 本地建文档 → 成功后清理云端原件。
// 失败的条目不会被删除，也不会中断后续条目的处理；输出逐条结果。
var inboxConvertCmd = &cobra.Command{
	Use:   "convert --ids <id1,id2,...> --notebook <id> [--path </h/path>] [--remove-after]",
	Short: "Convert cloud inbox shorthands into local documents",
	RunE: func(cmd *cobra.Command, args []string) error {
		notebook, _ := cmd.Flags().GetString("notebook")
		if notebook == "" {
			return fmt.Errorf("--notebook is required")
		}

		idsRaw, _ := cmd.Flags().GetString("ids")
		ids := parseShorthandIDs(idsRaw)
		if len(ids) == 0 {
			return fmt.Errorf("--ids is required (comma-separated shorthand IDs)")
		}

		hPath, _ := cmd.Flags().GetString("path")
		if hPath == "" {
			hPath = "/"
		}
		removeAfter, _ := cmd.Flags().GetBool("remove-after")

		// 解析目标父路径（hPath→fsPath）：hPath 指向新文档将要落入的父容器，
		// 其父目录必须已存在；不传或传 "/" 时落到笔记本根目录。
		parentPath := "/"
		parentDir := parentDir(hPath)
		if parentDir != "/" {
			bt := treenode.GetBlockTreeRootByHPath(notebook, parentDir)
			if bt == nil {
				return fmt.Errorf("parent path not found: %s", parentDir)
			}
			parentPath = strings.TrimSuffix(bt.Path, ".sy")

View on GitHub (pinned to 9f775e8a12)