[Bug] Remote CLI Configuration Problem after Upgrading to Headscale 0.23.0

[chuangbo]

Is this a support request?

• This is not a support request

Is there an existing issue for this?

• I have searched the existing issues

Current Behavior

After upgrading from Headscale 0.23.0 beta 3 to 0.23.0, the remote CLI command headscale nodes list fails with the following error:

github.com/juanfont/headscale@v0.23.0/cmd/headscale/cli/root.go:49 > Error loading config error="fatal error reading config file: Config File \"config\" Not Found in \"[/etc/headscale /Users/user/.headscale]\""

This occurs even when HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY environment variables are correctly set.

Expected Behavior

The remote CLI should function properly when either of the following conditions are met:

• The HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY environment variables are set correctly, without requiring an additional configuration file.
• A configuration file (~/.headscale/config.yaml or /etc/headscale/config.yaml) is present with the correct CLI settings.

The remote CLI should be able to connect to the Headscale server and execute commands (such as headscale nodes list) without encountering configuration-related errors, regardless of whether the configuration is provided via environment variables or a configuration file.

Steps To Reproduce

• Upgrade Headscale from version 0.23.0 beta 3 to 0.23.0
• Set HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY environment variables, without any additional configuration files.
• Run headscale nodes list
• Observe the error message

Environment

- OS: macOS 15.0
- Headscale version: 0.23.0
- Tailscale version: 1.74.0

Runtime environment

• Headscale is behind a (reverse) proxy
• Headscale runs in a container

Anything else?

Workarounds

Two workarounds have been identified:

1. Keep the environment variables HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY and create an empty file at ~/.headscale/config.yaml
2. Remove the environment variables and create a ~/.headscale/config.yaml file with the following content:

cli:
  address: headscale.example.com
  api_key: MY_API_KEY

Possible Cause

The issue may be related to commit 8a3a0fe, which removed the IsCLIConfigured check in hscontrol/types/config.go.

Proposed Solutions

We have two potential solutions to address this issue:

1. Update the documentation in docs/ref/remote-cli.md to recommend using a configuration file instead of environment variables.
2. Revert to the previous behavior that allowed the use of environment variables without a configuration file.

Questions

1. Which solution do you prefer: updating the documentation or reverting the behavior?
2. Would you like me to submit a PR to implement the chosen solution?

[nblock]

I can confirm your issue and have a small addition to your workaround:

• an empty config.yaml in one of the config lookup paths or
• an empty file and headscale -c /path/to/empty.yaml

is sufficient to use the settings from the environment variables.

Still, both methods to configure the gRPC connection should be equally supported.