What causes "--output is required for docx" in siyuan-note/siyuan?

Re-run with an explicit destination: `siyuan export docx --id --output /path/to/file.docx`.

--output is required for docx

Error message

--output is required for docx

What it means

The `siyuan export docx` subcommand requires an output file path via `--output` because a .docx is a binary artifact that cannot be streamed to stdout. The handler returns this error when the flag is empty or absent, after the `--id` check passes.

Solutions

Re-run with an explicit destination: `siyuan export docx --id <id> --output /path/to/file.docx`.
Ensure the parent directory of the output path exists and is writable.
Remember docx never prints to stdout, unlike html/preview.
Use --dry-run first to preview the planned export without writing.

Example fix

// before
siyuan export docx --id 20240101120000-abc1234

// after
siyuan export docx --id 20240101120000-abc1234 --output ./report.docx

Defensive patterns

Strategy: validation

Validate before calling

if [ -z "$OUT" ]; then echo "error: --output is required for docx" >&2; exit 1; fi
mkdir -p "$(dirname "$OUT")"

Try / catch

siyuan export docx --id "$DOC_ID" --output "$OUT" || { echo 'docx export failed (is --output set?)' >&2; exit 1; }

Prevention

Never assume stdout fallback for binary formats like docx
Create the output directory before exporting
Only html/preview (and optionally sy/md-zip) can fall back to stdout
Use --dry-run to echo the planned output path

When it happens

Trigger: Running `siyuan export docx --id <id>` with no `--output`, or `--output ""`.

Common situations: Reusing an invocation pattern from the html/preview/sy/md-zip subcommands where `--output` is optional (stdout fallback); scripts that omit the flag for dry-run mode.

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

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

Appendix: source

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

			return nil
		}

		html := model.ExportPreview(id, false)
		return writeExportContent(html, output)
	},
}

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 <file>]",

View on GitHub (pinned to 9f775e8a12)