siyuan-note/siyuan · error

--title is required

Error message

--title is required

What it means

The `document create` subcommand requires --title in addition to --notebook. The handler checks notebook first, then title, returning this error when title is empty. The title is used as the document's display name and feeds into ValidateCreateDoc, so an empty title would produce an invalid document. The --path and --markdown flags remain optional.

Source

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

			printDocumentTable(files)
		}
		return nil
	},
}

var documentCreateCmd = &cobra.Command{
	Use:   "create --notebook <id> --title <title>",
	Short: "Create a document",
	RunE: func(cmd *cobra.Command, args []string) error {
		notebook, _ := cmd.Flags().GetString("notebook")
		title, _ := cmd.Flags().GetString("title")
		dir, _ := cmd.Flags().GetString("path")
		markdown, _ := cmd.Flags().GetString("markdown")
		if notebook == "" {
			return fmt.Errorf("--notebook is required")
		}
		if title == "" {
			return fmt.Errorf("--title is required")
		}
		dir = normalizeDocumentCreateParentPath(dir)
		id := ast.NewNodeID()
		docPath := path.Join(dir, id+".sy")
		if err := model.ValidateCreateDoc(notebook, docPath, title); err != nil {
			return formatNotebookWriteError(notebook, err)
		}

		if dryRun {
			fmt.Printf("[dry-run] Would create document \"%s\" in notebook %s\n", title, notebook)
			return nil
		}

		_, err := model.CreateDocByMd(notebook, docPath, title, markdown, nil, nil)
		if err != nil {
			return formatNotebookWriteError(notebook, err)
		}
		model.AppendPushCreateEntry(notebook, docPath)

View on GitHub (pinned to 251596fc0d)

Solutions

1. Provide a non-empty title: `siyuan document create --notebook <id> --title "My Doc"`.
2. If the title comes from markdown content, extract it in the script and pass it explicitly.
3. Guard the title variable in scripts before invoking.
4. Confirm the flag with `siyuan document create --help`.

Example fix

// before
siyuan document create --notebook 20240101000000-xyz --markdown '# Hello'
// after
siyuan document create --notebook 20240101000000-xyz --title "Hello" --markdown '# Hello'

[ -n "$TITLE" ] || { echo '--title is required' >&2; exit 2; }
siyuan document create --notebook "$NOTEBOOK" --title "$TITLE"

if ! siyuan document create --notebook "$NOTEBOOK" --title "$TITLE" 2>err.txt; then
  grep -q 'title is required' err.txt && echo "pass a non-empty --title" >&2
  exit 1
fi

When it happens

Trigger: Running `siyuan document create --notebook <id>` without --title; passing `--title ""`; scripting where the title variable is empty for an iteration; using --markdown in the hope it derives a title automatically.

Common situations: Expecting the title to default to the first heading of --markdown content; passing an empty title intending to rename later; shell quoting that collapses the title to empty; copy-paste leaving a placeholder.

Related errors

• --notebook is required
• --id is required
• --id and --notebook are required
• --id is required
• --av, --key, --item and --value are required

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