{"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\tfiles, _, err := model.ListDocTree(notebook, resolvePath(notebook, docPath, hpath), 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},\n}\n\nvar documentCreateCmd = &cobra.Command{\n\tUse:   \"create --notebook <id> --title <title>\",","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/siyuan-note/siyuan/blob/251596fc0de2f9528c00c224252fd073a99973f4/kernel/cli/cmd/document.go#L29-L65","documentation":"The `document list` cobra subcommand requires the --notebook flag because ListDocTree operates on a specific notebook (box) ID. The RunE handler reads --notebook and returns this error immediately when it is empty, before calling model.ListDocTree. The --path and --hpath flags are optional and only refine which subtree is listed.","triggerScenarios":"Running `siyuan document list` with no flags; passing an empty `--notebook \"\"`; misspelling the flag; referencing a notebook ID stored in a shell variable that is unset.","commonSituations":"Forgetting the notebook ID after switching workspaces; assuming the command lists all notebooks; scripting a loop over notebooks but one variable is empty; copying a command from docs where <id> was a placeholder.","solutions":["Provide the notebook (box) ID: `siyuan document list --notebook 20240101000000-xyz`.","List available notebooks first with `siyuan notebook list` to obtain the ID.","If scripting, assert the variable is non-empty before calling the command.","Double-check flag spelling with `siyuan document list --help`."],"exampleFix":"// before\nsiyuan document list\n// after\nsiyuan document list --notebook 20240101000000-xyz","handlingStrategy":"validation","validationCode":"# assert notebook id is set\n[ -n \"$NOTEBOOK\" ] || { echo '--notebook is required' >&2; exit 2; }\nsiyuan document list --notebook \"$NOTEBOOK\"","typeGuard":null,"tryCatchPattern":"if ! siyuan document list --notebook \"$NOTEBOOK\" 2>err.txt; then\n  grep -q 'notebook is required' err.txt && echo \"pass --notebook <id> (try: siyuan notebook list)\" >&2\n  exit 1\nfi","preventionTips":["Keep a helper that resolves notebook IDs: `siyuan notebook list`.","Use `set -u` in scripts to catch unset variables.","Store commonly used notebook IDs in a config your script sources."],"tags":["cli","cobra","flag-validation","document","notebook","go"],"backgroundTag":null,"analyzedSha":"251596fc0de2f9528c00c224252fd073a99973f4","analyzedAt":"2026-08-12T21:18:37.123Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}