siyuan-note/siyuan · error

--notebook is required

Error message

--notebook is required

What it means

The `inbox convert` CLI command requires the `--notebook` flag to know which local notebook the cloud inbox shorthands should be converted into. The command returns this error before doing any work when the flag is empty or unset. It is a deliberate pre-flight argument check in the cobra RunE handler.

Solutions

1. Add `--notebook <id>` with the target notebook's ID (the ID shown in the SiYuan UI or printed by notebook create).
2. List available notebook IDs first (e.g. via the kernel API /api/notebook/lsNotebooks) to get a valid ID.
3. If scripting, ensure the variable holding the notebook ID is not empty before invoking the command.

Example fix

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

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

When it happens

Trigger: Running `siyuan inbox convert --ids <id1,id2>` without `--notebook <id>`, or passing `--notebook ""`.

Common situations: Copy-pasting a command from docs and dropping the notebook ID; scripting the convert step and forgetting to parameterize the target notebook; assuming a default notebook would be used (none exists).

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/83b9731e5eb0a936. Report an issue: GitHub.

Appendix: source

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

			if url != "" {
				fmt.Println("URL:    ", url)
			}
			fmt.Println("\nMARKDOWN:")
			fmt.Println(md)
		}
		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)

View on GitHub (pinned to 9f775e8a12)