siyuan-note/siyuan · error

--id is required

Error message

--id is required

What it means

Argument validation in the cobra outlineGet RunE: fires when the --id flag is empty. Fetching a document outline requires the document (root block) ID to pass to model.Outline; running `outline get` without --id is the faulting usage.

Solutions

1. Re-run with `--id <document-id>`
2. Get the document id from the SiYuan UI (copy block id) or a query command
3. Validate the variable is non-empty before invoking

Example fix

// before
siyuan outline get
// after
siyuan outline get --id 20240101120000-abcdefg

[ -n "$DOC_ID" ] || { echo "--id is required"; exit 1; }
siyuan outline get --id "$DOC_ID"

const isNonEmptyString = (v) => typeof v === "string" && v.length > 0;

try { run(`siyuan outline get --id ${docId}`); } catch (e) { console.error(e.message); }

When it happens

Trigger: Running `outline get` without `--id` or with an empty value.

Common situations: Forgetting to substitute the doc id in scripts; empty shell variable from a failed lookup.

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• document not found or has no headings
• --icon is required
• --id is required
• appearance files not found at
• --attr is required (format: name=value)

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

Appendix: source

Thrown at kernel/cli/cmd/outline.go:40

	"strings"

	"github.com/siyuan-note/siyuan/kernel/model"

	"github.com/spf13/cobra"
)

var outlineCmd = &cobra.Command{
	Use:   "outline",
	Short: "Document outline (heading tree)",
}

var outlineGetCmd = &cobra.Command{
	Use:   "get --id <id>",
	Short: "Get document outline",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}
		paths, err := model.Outline(id, false)
		if err != nil {
			return err
		}
		if len(paths) == 0 {
			return fmt.Errorf("document not found or has no headings")
		}
		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(paths, "", "  ")
			fmt.Println(string(data))
		default:
			var sb strings.Builder
			sb.WriteString(fmt.Sprintf("Document outline (%d headings):\n\n", countOutlineHeadings(paths)))
			for _, p := range paths {
				writeOutlinePath(&sb, p, 0)
			}

View on GitHub (pinned to 9f775e8a12)