{"record":{"id":"25e4340b71e1bd83","repo":"siyuan-note/siyuan","slug":"notebook-is-required-25e434","errorCode":null,"errorMessage":"--notebook is required","messagePattern":"--notebook is required","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kernel/cli/cmd/document.go","lineNumber":47,"sourceCode":"\t\"github.com/siyuan-note/siyuan/kernel/treenode\"\n\n\t\"github.com/spf13/cobra\"\n)\n\nvar documentCmd = &cobra.Command{\n\tUse:   \"document\",\n\tShort: \"Manage documents\",\n}\n\nvar documentListCmd = &cobra.Command{\n\tUse:   \"list --notebook <id>\",\n\tShort: \"List documents in a notebook\",\n\tRunE: func(cmd *cobra.Command, args []string) error {\n\t\tnotebook, _ := cmd.Flags().GetString(\"notebook\")\n\t\tdocPath, _ := cmd.Flags().GetString(\"path\")\n\t\thpath, _ := cmd.Flags().GetString(\"hpath\")\n\t\tif notebook == \"\" {\n\t\t\treturn fmt.Errorf(\"--notebook is required\")\n\t\t}\n\t\tlistPath, err := resolvePath(notebook, docPath, hpath)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tfiles, _, err := model.ListDocTree(notebook, listPath, 0, false, false, 128)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tswitch outputFormat {\n\t\tcase \"json\":\n\t\t\tdata, _ := json.MarshalIndent(files, \"\", \"  \")\n\t\t\tfmt.Println(string(data))\n\t\tdefault:\n\t\t\tprintDocumentTable(files)\n\t\t}\n\t\treturn nil\n\t},","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/9f775e8a12daef8255556097396f9b2739078892/kernel/cli/cmd/document.go#L29-L65","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass the notebook ID: `siyuan document list --notebook <notebookID>`","List notebooks first (e.g. the notebooks API/command) to get the exact ID","Fix scripts to fail early when NOTEBOOK is unset instead of passing an empty value"],"exampleFix":"// before\nsiyuan document list\n// after\nsiyuan document list --notebook 20210808180117-c6jeg35","handlingStrategy":"validation","validationCode":"[ -n \"$NOTEBOOK_ID\" ] || { echo \"--notebook is required\" >&2; exit 1; }\nsiyuan document list --notebook \"$NOTEBOOK_ID\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Resolve notebook IDs once at script start via the notebooks listing","Distinguish notebook names from IDs; the flag takes the ID","Use `set -u` to catch unset variables"],"tags":["cli","validation","document","missing-flag"],"backgroundTag":"missing-required-flag","analyzedSha":"9f775e8a12daef8255556097396f9b2739078892","analyzedAt":"2026-09-19T03:17:15.984Z","contentChangedAt":"2026-09-19T03:17:15.984Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}