siyuan-note/siyuan · error

--pattern is required

Error message

--pattern is required

What it means

The SiYuan kernel CLI `file grep` command requires a regex pattern via --pattern. The command reads the flag with cmd.Flags().GetString and returns this error immediately when the value is empty. It is a user-input guard, not an internal failure.

Solutions

1. Re-run the command with --pattern <regex>, e.g. file grep --pattern "TODO" --path "data/notebooks"
2. Check that the shell variable supplying the pattern is non-empty before invoking the CLI
3. Run `siyuan file grep --help` to see the expected flags

Example fix

// before
file grep --path data/notebook
// after
file grep --pattern "TODO" --path data/notebook

if [ -z "$PATTERN" ]; then echo "--pattern is required" >&2; exit 1; fi
siyuan file grep --pattern "$PATTERN" --path "$PATH_ARG"

When it happens

Trigger: Running `siyuan file grep` (or `file grep --path <path>`) without --pattern, or passing --pattern "" (empty string).

Common situations: Developer forgets the flag when scripting searches; a shell variable holding the pattern is empty due to an earlier failed capture; flags copied from a doc example omit the pattern.

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

• --av and --ids are required
• --av, --key, --item and --value are required
• --block is required for non-detached rows
• --id and --notebook are required
• --id is required

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

Appendix: source

Thrown at kernel/cli/cmd/file.go:279

		return err
	}
	defer srcF.Close()
	dstF, err := os.Create(dst)
	if err != nil {
		return err
	}
	defer dstF.Close()
	_, err = io.Copy(dstF, srcF)
	return err
}

var fileGrepCmd = &cobra.Command{
	Use:   "grep --pattern <regex> --path <path>",
	Short: "Search file contents with regex",
	RunE: func(cmd *cobra.Command, args []string) error {
		pattern, _ := cmd.Flags().GetString("pattern")
		if pattern == "" {
			return fmt.Errorf("--pattern is required")
		}
		relPath, _ := cmd.Flags().GetString("path")
		if relPath == "" {
			return fmt.Errorf("--path is required")
		}
		abs, err := absPath(relPath)
		if err != nil {
			return err
		}
		include, _ := cmd.Flags().GetString("include")
		ctx, _ := cmd.Flags().GetInt("context")
		max, _ := cmd.Flags().GetInt("limit")
		if max <= 0 {
			max = 200
		}
		results, err := gulu.File.Grep(abs, include, pattern, ctx, max)
		if err != nil {
			return err

View on GitHub (pinned to 9f775e8a12)