ory/hydra · warning

command expects one argument which is the path to the output

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.

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)

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
• Janitor requires at least one of --tokens, --requests or --g
• Values for --limit and --batch-size should both be greater t
• Value for --batch-size must not be greater than value for --
• When using flag -e, environment variable DSN must be set. Wh

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