larksuite/cli · error

positional arguments are not supported (got %q); pass values

Error message

positional arguments are not supported (got %q); pass values via flags

What it means

Cobra positional-args validator rejectPositionalArgs rejects any non-flag argument. Lark CLI shortcuts require all values to be passed as named flags; bare words are rejected with the offending args quoted (%q of the []string).

Source

Thrown at shortcuts/common/runner.go:1420

		Format:      rctx.Format,
		JqExpr:      rctx.JqExpr,
		CommandPath: rctx.Cmd.CommandPath(),
		Identity:    rctx.As(),
		Out:         f.IOStreams.Out,
		ErrOut:      f.IOStreams.ErrOut,
	})
}

// rejectPositionalArgs returns a cobra.PositionalArgs that rejects any
// positional arguments. It returns a plain cobra usage error; the root
// handler classifies it into the typed validation envelope (exit 2), the
// same path as other cobra usage failures.
func rejectPositionalArgs() cobra.PositionalArgs {
	return func(cmd *cobra.Command, args []string) error {
		if len(args) == 0 {
			return nil
		}
		return fmt.Errorf("positional arguments are not supported (got %q); pass values via flags", args)
	}
}

// registerShortcutFlags adds the shortcut's declared flags to its Cobra command.
func registerShortcutFlags(cmd *cobra.Command, f *cmdutil.Factory, s *Shortcut) {
	registerShortcutFlagsWithContext(context.Background(), cmd, f, s)
}

// shortcutDeclaresJSONFlag reports whether the shortcut itself declares a flag
// named "json" in its Flags list (custom semantics, e.g. event +subscribe's
// pretty-print switch or base +record-search's request-body payload).
// Framework-injected flags never appear in s.Flags, so this cleanly separates
// "self-declared json" from "injected shorthand".
func shortcutDeclaresJSONFlag(s *Shortcut) bool {
	for _, fl := range s.Flags {
		if fl.Name == "json" {
			return true
		}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Convert every value to its declared flag form: --flag value or --flag=value
2. Quote values containing spaces so they stay one token
3. Run the command with --help to see the exact flag names

Example fix

// before
lark-cli doc create "My Doc"
// after
lark-cli doc create --title "My Doc"

lark-cli <cmd> --help   # confirm all values are flags before running

if len(os.Args) > 1 && !strings.HasPrefix(os.Args[len(os.Args)-1], "-") { /* last token is positional — likely wrong */ }

cmd.SilenceUsage = false // let cobra print usage alongside the validator error

When it happens

Trigger: Invoking a shortcut like `lark-cli doc create mydoc` instead of `lark-cli doc create --title mydoc`; shell word-splitting or unquoted spaces adding extra tokens; pasting examples that use positional syntax from other CLIs.

Common situations: Muscle memory from other CLIs; forgetting --flag= before a value; unquoted paths with spaces producing extra positional tokens.

Related errors

• unknown flag: --{name}

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/3f279d8efdd3d50d. Report an issue: GitHub.