siyuan-note/siyuan · error

--notebook is required

Error message

--notebook is required

What it means

Argument validation in the cobra importMd RunE: fires when the --notebook flag is empty. Importing a Markdown file or directory requires the target notebook ID into which the .sy documents are created; running `import md` with only --file is the faulting usage.

Solutions

1. Re-run with --notebook <notebook-id>; get the ID from `siyernel notebook list` / the notebook ls command
2. Copy the exact notebook ID (timestamp-random format) from the UI or API /api/notebook/lsNotebooks
3. Ensure the variable holding the notebook ID is non-empty

Example fix

// before
import --file ~/notes.md
// after
import --file ~/notes.md --notebook 20240101123456-abcdefg

if [ -z "$NB_ID" ]; then echo "--notebook is required (use the notebook ID, not its name)" >&2; exit 1; fi
siyuan import --file "$SRC_FILE" --notebook "$NB_ID"

When it happens

Trigger: Running `siyuan import --file <path>` without --notebook or with an empty value.

Common situations: Developer uses the notebook name instead of its ID (e.g. "My Notes" rather than "20240101123456-abcdefg"); forgetting the flag entirely in scripts; notebook deleted so its ID variable is empty.

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

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

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

Appendix: source

Thrown at kernel/cli/cmd/import.go:45

var importCmd = &cobra.Command{
	Use:   "import",
	Short: "Import files",
}

var importMdCmd = &cobra.Command{
	Use:   "md --file <path> --notebook <id>",
	Short: "Import Markdown file or directory",
	RunE: func(cmd *cobra.Command, args []string) error {
		filePath, _ := cmd.Flags().GetString("file")
		notebook, _ := cmd.Flags().GetString("notebook")
		toPath, _ := cmd.Flags().GetString("path")
		hpath, _ := cmd.Flags().GetString("hpath")
		if filePath == "" {
			return fmt.Errorf("--file is required")
		}
		if notebook == "" {
			return fmt.Errorf("--notebook is required")
		}

		absPath, err := filepath.Abs(filePath)
		if err != nil {
			return err
		}
		targetPath, err := resolvePath(notebook, toPath, hpath)
		if err != nil {
			return err
		}

		if dryRun {
			if err := model.ValidateImportFromLocalPath(notebook, absPath, targetPath); err != nil {
				return formatNotebookWriteError(notebook, err)
			}
			fmt.Printf("[dry-run] Would import Markdown from \"%s\" to notebook %s\n", filePath, notebook)
			return nil
		}

View on GitHub (pinned to 9f775e8a12)