siyuan-note/siyuan · error

--notebook is required

Error message

--notebook is required

What it means

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.

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")
		}
		files, _, err := model.ListDocTree(notebook, resolvePath(notebook, docPath, hpath), 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
	},
}

var documentCreateCmd = &cobra.Command{
	Use:   "create --notebook <id> --title <title>",

View on GitHub (pinned to 251596fc0d)

Solutions

1. Provide the notebook (box) ID: `siyuan document list --notebook 20240101000000-xyz`.
2. List available notebooks first with `siyuan notebook list` to obtain the ID.
3. If scripting, assert the variable is non-empty before calling the command.
4. Double-check flag spelling with `siyuan document list --help`.

Example fix

// before
siyuan document list
// after
siyuan document list --notebook 20240101000000-xyz

# assert notebook id is set
[ -n "$NOTEBOOK" ] || { echo '--notebook is required' >&2; exit 2; }
siyuan document list --notebook "$NOTEBOOK"

if ! siyuan document list --notebook "$NOTEBOOK" 2>err.txt; then
  grep -q 'notebook is required' err.txt && echo "pass --notebook <id> (try: siyuan notebook list)" >&2
  exit 1
fi

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• --id and --notebook are required
• --title is required
• --id is required
• target human-readable path not found: %s
• --id is required

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/25e4340b71e1bd83. Report an issue: GitHub.