ory/hydra · warning

command expects one argument which is the path to the…

Error message

command expects one argument which is the path to the output directory

What it means

This error is returned by the clidoc Generate cobra command when the number of positional arguments is not exactly one. The command generates markdown documentation for a command tree and requires exactly one argument: the path to the output directory.

Solutions

1. Run the command with exactly one argument: the output directory path, e.g. `myapp docs ./docs/cli`.
2. Quote paths containing spaces so they count as one argument.
3. Create the output directory beforehand if the generator does not mkdir it.
4. Check `myapp docs --help` for the exact usage string.

Example fix

# before
$ myapp docs
Error: command expects one argument which is the path to the output directory
# after
$ myapp docs ./docs/commands

// wrapper that enforces the argument before invoking the command
func mustDocsArgs(args []string) error {
    if len(args) != 1 {
        return fmt.Errorf("usage: myapp docs <output-dir>")
    }
    if fi, err := os.Stat(args[0]); err != nil || !fi.IsDir() {
        return fmt.Errorf("output directory %q does not exist", args[0])
    }
    return nil
}

When it happens

Trigger: Running the generated CLI's docs command with zero arguments or more than one argument — `len(args) != 1` in Generate (oryx/clidoc/generate.go:19).

Common situations: Users run `myapp docs` without the output path; shell scripts pass extra flags interpreted as positional args; copy-pasted examples quote paths into two arguments; forgetting that the command takes a directory, not a file.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

• A DSN is required as a positional argument when not passing…
• Could not cleanup inactive
• Could not create driver
• could not parse the endpoint URL
• could not start debug server on port

AI-assisted analysis of ory/hydra@4174065ffb (2026-09-03). Data as JSON: /api/errors/f37edceb8d48ba35. Report an issue: GitHub.

Appendix: source

Thrown at oryx/clidoc/generate.go:19

package clidoc

import (
	"bytes"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"strings"

	"github.com/pkg/errors"

	"github.com/spf13/cobra"
)

// Generate generates markdown documentation for a cobra command and its children.
func Generate(cmd *cobra.Command, args []string) error {
	if len(args) != 1 {
		return errors.New("command expects one argument which is the path to the output directory")
	}

	return generate(cmd, args[0])
}

func trimExt(s string) string {
	return strings.ReplaceAll(strings.TrimSuffix(s, filepath.Ext(s)), "_", "-")
}

func generate(cmd *cobra.Command, dir string) error {
	cmd.DisableAutoGenTag = true
	for _, c := range cmd.Commands() {
		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
			continue
		}
		if err := generate(c, dir); err != nil {
			return err
		}

View on GitHub (pinned to 4174065ffb)