siyuan-note/siyuan · error

--attr is required (format: name=value)

Error message

--attr is required (format: name=value)

What it means

The `attr set` subcommand requires at least one `--attr name=value` flag to know which attributes to write. The handler counts the string-array `--attr` values and returns this error when none were supplied. It fires before any attribute is applied.

Solutions

1. Pass at least one attribute: `--attr name=value` (repeatable, e.g. --attr icon=1f4ca --attr title-img=...)
2. If you meant to read attributes, use `attr batch-get --ids <id>` instead
3. In scripts, build the --attr list first and abort if it is empty

Example fix

// before
siyuan-kernel attr set --id 20260605100657-v080a4j
// after
siyuan-kernel attr set --id 20260605100657-v080a4j --attr icon=1f4ca

ATTRS=("icon=1f4ca")
if [ ${#ATTRS[@]} -eq 0 ]; then echo "--attr is required (format: name=value)" >&2; exit 1; fi
ARGS=(); for a in "${ATTRS[@]}"; do ARGS+=(--attr "$a"); done
siyuan-kernel attr set --id "$ID" "${ARGS[@]}"

function hasAttrs(flags) { return Array.isArray(flags) && flags.length > 0; }

if err := run(); err != nil && strings.Contains(err.Error(), "--attr is required") { // print usage hint about name=value }

When it happens

Trigger: Running `siyuan-kernel attr set --id 20260605100657-v080a4j` with no `--attr` flags at all.

Common situations: Intending to clear attributes but calling the command with only --id; writing a wrapper that forwards an empty attribute list; confusing attr set with a get command that needs no --attr.

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

• --id is required
• --ids is required
• --remote requires a URL
• appearance files not found at
• --av and --ids are required

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

Appendix: source

Thrown at kernel/cli/cmd/attr.go:82

Common attributes:
  icon       Emoji hex codepoint (e.g. "1f4ca"), emoji character (e.g. "📊"), custom image path (e.g. "1/b3log.png"), network image URL (e.g.
             "https://example.com/icon.png"), or dynamic icon URL (e.g. "api/icon/getDynamicIcon?type=8&color=%23d23f31&content=SiYuan&id=xxx").
  title-img  CSS background-image format (e.g. 'background-image:url("assets/example.jpg")').
             DO NOT use a bare asset path.
  tags       Comma-separated tag names.

Examples:
  siyuan-kernel attr set --id 20260605100657-v080a4j --attr icon=1f4ca
  siyuan-kernel attr set --id 20260605100657-v080a4j --attr title-img='background-image:url("assets/example.jpg")'`,
	RunE: func(cmd *cobra.Command, args []string) error {
		id, _ := cmd.Flags().GetString("id")
		if id == "" {
			return fmt.Errorf("--id is required")
		}

		attrFlags, _ := cmd.Flags().GetStringArray("attr")
		if len(attrFlags) == 0 {
			return fmt.Errorf("--attr is required (format: name=value)")
		}

		nameValues := make(map[string]string, len(attrFlags))
		for _, a := range attrFlags {
			parts := strings.SplitN(a, "=", 2)
			if len(parts) != 2 {
				return fmt.Errorf("invalid attr format [%s], expected name=value", a)
			}
			nameValues[strings.TrimSpace(parts[0])] = parts[1]
		}

		if dryRun {
			var parts []string
			for k, v := range nameValues {
				parts = append(parts, fmt.Sprintf("%s=%s", k, v))
			}
			fmt.Printf("[dry-run] Would set attributes on block %s: %s\n", id, strings.Join(parts, ", "))
			return nil

View on GitHub (pinned to 9f775e8a12)