you have to set the remote endpoint, try --help for details

Error message

you have to set the remote endpoint, try --help for details

What it means

cmdx.NewClient builds an HTTP client for a CLI command targeting a remote endpoint. The endpoint must come from a flag or the environment variable (envKeyEndpoint); when both are empty it refuses to proceed with this message, pointing the user to --help.

Source

Thrown at oryx/cmdx/http.go:75

		return nil, err
	}

	return endpoint, nil
}

// NewClient creates a new HTTP client.
func NewClient(cmd *cobra.Command) (*http.Client, *url.URL, error) {
	endpoint, err := cmd.Flags().GetString(FlagEndpoint)
	if err != nil {
		return nil, nil, errors.WithStack(err)
	}

	if endpoint == "" {
		endpoint = os.Getenv(envKeyEndpoint)
	}

	if endpoint == "" {
		return nil, nil, errors.Errorf("you have to set the remote endpoint, try --help for details")
	}

	u, err := url.Parse(strings.TrimRight(endpoint, "/"))
	if err != nil {
		return nil, nil, errors.Wrapf(err, `could not parse the endpoint URL "%s"`, endpoint)
	}

	hc := retryablehttp.NewClient().StandardClient()
	hc.Timeout = time.Second * 10

	rawHeaders, err := cmd.Flags().GetStringSlice(FlagHeaders)
	if err != nil {
		return nil, nil, errors.WithStack(err)
	}
	header := http.Header{}
	for _, h := range rawHeaders {
		parts := strings.Split(h, ":")
		if len(parts) != 2 {

View on GitHub (pinned to 4174065ffb)

Solutions

Pass the remote endpoint explicitly via the command's endpoint flag
Export the expected environment variable (see envKeyEndpoint in oryx/cmdx/http.go) with the remote URL
Run the command with --help to see the exact flag/env names
Fix CI/shell scripts so the env var is set before invoking the command

Example fix

// before
$ hydra token client --client-id foo
// after
$ export HYDRA_CLI_URL=https://hydra.example.com
$ hydra token client --client-id foo

Defensive patterns

Strategy: validation

Validate before calling

endpoint := flagOrEnvEndpoint()
if endpoint == "" {
    return fmt.Errorf("remote endpoint missing: set the endpoint flag or %s", envKeyEndpoint)
}

Try / catch

client, err := cmdx.NewClient(cmd)
if err != nil && strings.Contains(err.Error(), "you have to set the remote endpoint") {
    return cmd.Usage() // guide user to the flag/env var
}

Prevention

Always export the endpoint env var in shell profiles and CI before running CLI commands
Verify the exact env var name with --help; do not guess
Add preflight checks in scripts that assert the env var is non-empty
Prefer explicit flags in scripts to avoid env-var ambiguity

When it happens

Trigger: Running a CLI subcommand that requires a remote API without passing the endpoint flag and without the corresponding environment variable set (e.g. HYDRA_CLI_URL/ORY_URL style env var unset), so endpoint remains "" after both lookups.

Common situations: CI environments where the endpoint env var was never exported; forgetting the --endpoint flag while the env var has a different name than expected; typos in the env var name.

Related errors

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