cli/cli · warning

error: --doc-path not set

Error message

error: --doc-path not set

What it means

This is the gen-docs tool (cmd/gen-docs) that renders gh's manual pages. After parsing flags it requires --doc-path; an empty value returns this error and flags.PrintUsage output precedes it only when -h is given. It is a build-tooling flag error: the program generated docs have nowhere to be written.

Source

Thrown at cmd/gen-docs/main.go:46

func run(args []string) error {
	flags := pflag.NewFlagSet("", pflag.ContinueOnError)
	manPage := flags.BoolP("man-page", "", false, "Generate manual pages")
	website := flags.BoolP("website", "", false, "Generate website pages")
	dir := flags.StringP("doc-path", "", "", "Path directory where you want generate doc files")
	help := flags.BoolP("help", "h", false, "Help about any command")

	if err := flags.Parse(args); err != nil {
		return err
	}

	if *help {
		fmt.Fprintf(os.Stderr, "Usage of %s:\n\n%s", filepath.Base(args[0]), flags.FlagUsages())
		return nil
	}

	if *dir == "" {
		return fmt.Errorf("error: --doc-path not set")
	}

	ios, _, _, _ := iostreams.Test()
	rootCmd, _ := root.NewCmdRoot(&cmdutil.Factory{
		IOStreams: ios,
		Browser:   &browser{},
		Config: func() (gh.Config, error) {
			return config.NewMockConfigFromString(""), nil
		},
		ExtensionManager: &em{},
	}, &telemetry.NoOpService{}, "", "")
	rootCmd.InitDefaultHelpCmd()

	if err := os.MkdirAll(*dir, 0755); err != nil {
		return err
	}

	if *website {

View on GitHub (pinned to 0eeec0b92e)

Solutions

1. Pass the flag explicitly: go run ./cmd/gen-docs --doc-path <dir>
2. In CI, default the variable: DOCS_PATH ?= ./docs in the Makefile target
3. Check for typos in the flag name (single dash -doc-path also works with pflag)

Example fix

# before
go run ./cmd/gen-docs
# -> error: --doc-path not set

# after
go run ./cmd/gen-docs --doc-path ./docs/man

// Shell: fail fast with a clear default
: "${DOCS_PATH:=./docs/man}"
go run ./cmd/gen-docs --doc-path "$DOCS_PATH"

When it happens

Trigger: Running 'go run ./cmd/gen-docs' without arguments, or with --doc-path whose value is empty/unset in the wrapping Makefile target; also invoking the built binary in CI doc generation before the output directory variable is defined.

Common situations: Contributors generating docs locally forgetting the flag; release pipelines where the DOCS_PATH variable is empty due to a missing environment variable; refactors renaming the flag while old scripts pass --docs-path.

Related errors

• cannot use `--stdio` with `--server-port`
• cannot use `--stdio` with `--profile`
• cannot use `--config` with `--profile`
• cannot use `--config` with `--server-port`
• `--template` is not supported when using `--body` or `--body

AI-assisted analysis of cli/cli@0eeec0b92e (2026-08-15). Data as JSON: /api/errors/b572814dcd5bbb2d. Report an issue: GitHub.