siyuan-note/siyuan · error

--notebook is required

Error message

--notebook is required

What it means

The `siyuan document list` command requires the notebook ID via the `--notebook` flag. RunE returns this error before calling resolvePath/model.ListDocTree when the flag is empty. The kernel needs the notebook to scope the document-tree listing.

Solutions

1. Pass the notebook ID: `siyuan document list --notebook <notebookID>`
2. List notebooks first (e.g. the notebooks API/command) to get the exact ID
3. Fix scripts to fail early when NOTEBOOK is unset instead of passing an empty value

Example fix

// before
siyuan document list
// after
siyuan document list --notebook 20210808180117-c6jeg35

[ -n "$NOTEBOOK_ID" ] || { echo "--notebook is required" >&2; exit 1; }
siyuan document list --notebook "$NOTEBOOK_ID"

When it happens

Trigger: Running `siyuan document list` without `--notebook <notebookID>` or with an empty string value. Optional flags --path/--hpath may be present or absent; only the missing notebook triggers this.

Common situations: Mistaking a notebook name for its ID (the flag needs the ID like `20210808180117-c6jeg35`); forgetting the flag after copying a `document create` example; an empty NOTEBOOK variable in a script because the notebook list step was skipped.

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

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

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

Appendix: source

Thrown at kernel/cli/cmd/document.go:47

	"github.com/siyuan-note/siyuan/kernel/treenode"

	"github.com/spf13/cobra"
)

var documentCmd = &cobra.Command{
	Use:   "document",
	Short: "Manage documents",
}

var documentListCmd = &cobra.Command{
	Use:   "list --notebook <id>",
	Short: "List documents in a notebook",
	RunE: func(cmd *cobra.Command, args []string) error {
		notebook, _ := cmd.Flags().GetString("notebook")
		docPath, _ := cmd.Flags().GetString("path")
		hpath, _ := cmd.Flags().GetString("hpath")
		if notebook == "" {
			return fmt.Errorf("--notebook is required")
		}
		listPath, err := resolvePath(notebook, docPath, hpath)
		if err != nil {
			return err
		}
		files, _, err := model.ListDocTree(notebook, listPath, 0, false, false, 128)
		if err != nil {
			return err
		}
		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(files, "", "  ")
			fmt.Println(string(data))
		default:
			printDocumentTable(files)
		}
		return nil
	},

View on GitHub (pinned to 9f775e8a12)