Args field %s (--%s): description is required via doc or Inp

Error message

Args field %s (--%s): description is required via doc or InputField.Description

What it means

Every compiled Args field must have a non-empty description used in --help and schema output. compileInput throws this when neither the struct field's doc comment nor an InputField.Description supplement supplied one. Descriptions are a hard requirement for generated CLI help quality.

Source

Thrown at shortcuts/common/typed_compile_args.go:60

	}
	fieldByName := make(map[string]int, len(fields))
	allNames := make(map[string]string, len(fields))
	for i := range fields {
		field := &fields[i]
		if previous, exists := allNames[field.name]; exists {
			return nil, nil, fmt.Errorf("Args field %s flag --%s duplicates %s", field.goName, field.name, previous)
		}
		allNames[field.name] = "--" + field.name
		fieldByName[field.name] = i
		supplement, hasSupplement := supplements[field.name]
		if hasSupplement {
			if err := mergeInputSupplement(field, supplement); err != nil {
				return nil, nil, fmt.Errorf("Args field %s (--%s): %w", field.goName, field.name, err)
			}
			delete(supplements, field.name)
		}
		if field.description == "" {
			return nil, nil, fmt.Errorf("Args field %s (--%s): description is required via doc or InputField.Description", field.goName, field.name)
		}
		if err := validateInputCLI(field); err != nil {
			return nil, nil, fmt.Errorf("Args field %s (--%s): %w", field.goName, field.name, err)
		}
		for _, alias := range field.cli.Aliases {
			if previous, exists := allNames[alias.Name]; exists {
				return nil, nil, fmt.Errorf("Args field %s (--%s): alias --%s duplicates %s", field.goName, field.name, alias.Name, previous)
			}
			allNames[alias.Name] = "alias of --" + field.name
		}
	}
	if len(supplements) > 0 {
		for name := range supplements {
			return nil, nil, fmt.Errorf("Input.Fields references unknown flag --%s", name)
		}
	}
	return fields, fieldByName, nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

Add a doc comment line above the struct field describing the flag.
Or set Description on the matching Input.Fields supplement.
Run the compile step (schema/help generation) again to confirm the field passes.

Example fix

// before
type Args struct {
  UserID string `flag:"user-id"`
}
// after
type Args struct {
  // Lark user ID (open_id or user_id) to assign the task.
  UserID string `flag:"user-id"`
}

Defensive patterns

Strategy: validation

Validate before calling

func allFieldsDocumented(t reflect.Type) error {
  for i := 0; i < t.NumField(); i++ {
    if t.Field(i).IsExported() && docOf(t.Field(i)) == "" {
      return fmt.Errorf("field %s missing description", t.Field(i).Name)
    }
  }
  return nil
}

Prevention

Write a doc comment on every tagged struct field as a habit.
Or supply Description via Input.Fields for externally documented fields.
Gate CI on compiling all definitions so missing docs fail early.

When it happens

Trigger: Defining a struct field with flag/arg tags but no doc comment, and no matching InputField.Description in definition.Fields, then compiling the definition.

Common situations: Adding a new flag field quickly without a comment; stripping comments with a formatter/refactor; assuming a json tag alone provides the description.

Related errors

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