siyuan-note/siyuan · error

--output is required for docx

Error message

--output is required for docx

What it means

The `export docx` subcommand additionally requires the --output flag (a file path) because Word export produces a binary .docx that cannot be streamed to stdout. The handler checks --id first, then --output, returning this error when --output is empty, before the dry-run check and before model.ExportDocx. This is the key difference from the md/html/preview subcommands which treat --output as optional.

Source

Thrown at kernel/cli/cmd/export.go:115

		if output != "" {
			return os.WriteFile(output, []byte(html), 0644)
		}
		fmt.Print(html)
		return nil
	},
}

var exportDocxCmd = &cobra.Command{
	Use:   "docx --id <id> --output <file>",
	Short: "Export as Word (.docx)",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		output, _ := cmd.Flags().GetString("output")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		if output == "" {
			return fmt.Errorf("--output is required for docx")
		}

		if dryRun {
			fmt.Printf("[dry-run] Would export docx for document %s to %s\n", id, output)
			return nil
		}

		fullPath, err := model.ExportDocx(id, output, false, false)
		if err != nil {
			return err
		}
		fmt.Println(fullPath)
		return nil
	},
}

var exportSYCmd = &cobra.Command{
	Use:   "sy --id <id> [--output <dir>]",

View on GitHub (pinned to 251596fc0d)

Solutions

1. Supply an output file path: `siyuan export docx --id <id> --output /path/to/file.docx`.
2. Ensure the parent directory exists and is writable.
3. Guard the output variable in scripts.
4. Use `--dry-run` to preview before writing.
5. Verify the flag with `siyuan export docx --help`.

Example fix

// before
siyuan export docx --id 20240101000000-abc1234
// after
siyuan export docx --id 20240101000000-abc1234 --output ./notes.docx

[ -n "$OUT" ] || { echo '--output is required for docx' >&2; exit 2; }
mkdir -p "$(dirname "$OUT")"
siyuan export docx --id "$DOC_ID" --output "$OUT"

if ! siyuan export docx --id "$DOC_ID" --output "$OUT" 2>err.txt; then
  grep -q 'output is required' err.txt && echo "docx needs --output <file.docx>" >&2
  exit 1
fi

When it happens

Trigger: Running `siyuan export docx --id <id>` without --output; passing `--output ""`; scripting with an unset output path variable; misspelling the flag; expecting docx content on stdout.

Common situations: Assuming --output is optional like the other export subcommands; forgetting the destination path; pointing --output at an unwritable directory (caught later as a write error, not here); shell variable empty for an iteration.

Related errors

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

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