siyuan-note/siyuan · error

--id is required

Error message

--id is required

What it means

Argument validation in the cobra refBacklinksCmd RunE: fires when the --id flag is empty. Querying backlinks requires the target block ID passed to model.GetBacklink2; running `ref backlinks` without --id is the faulting usage.

Solutions

1. Re-run with `--id <block-id>`
2. Copy the block id from the SiYuan editor (right-click, copy block id)
3. Guard the id variable in scripts before invoking

Example fix

// before
siyuan ref backlinks --keyword "todo"
// after
siyuan ref backlinks --id 20240101120000-abcdefg --keyword "todo"

[ -n "$BLOCK_ID" ] || { echo "--id is required"; exit 1; }
siyuan ref backlinks --id "$BLOCK_ID"

const requireBlockId = (v) => (typeof v === "string" && v.length > 0) ? v : null;

try { run(`siyuan ref backlinks --id ${blockId}`); } catch (e) { console.error("backlinks failed:", e.message); }

When it happens

Trigger: Running `ref backlinks` without `--id`, or with `--id ""`.

Common situations: Scripts where the block id variable was never set; omitting the flag while only passing optional `--keyword`/`--sort`.

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

• --icon is required
• --id is required
• appearance files not found at
• --attr is required (format: name=value)
• --av and --ids are required

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

Appendix: source

Thrown at kernel/cli/cmd/ref.go:41

	"text/tabwriter"

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

	"github.com/spf13/cobra"
)

var refCmd = &cobra.Command{
	Use:   "ref",
	Short: "Backlinks and references",
}

var refBacklinksCmd = &cobra.Command{
	Use:   "backlinks --id <id>",
	Short: "Get backlinks for a block",
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}

		keyword, _ := cmd.Flags().GetString("keyword")
		sortMode, _ := cmd.Flags().GetInt("sort")

		_, backlinks, _, count, _ := model.GetBacklink2(id, keyword, "", sortMode, 0, model.Conf.Editor.BacklinkContainChildren)

		switch outputFormat {
		case "json":
			data, _ := json.MarshalIndent(backlinks, "", "  ")
			fmt.Println(string(data))
		default:
			printPathTable(backlinks, false)
		}

		fmt.Printf("\n%d backlink(s)\n", count)
		return nil
	},

View on GitHub (pinned to 9f775e8a12)