diff --git a/core/cli/deprecations.go b/core/cli/deprecations.go
new file mode 100644
index 000000000..98154d5fb
--- /dev/null
+++ b/core/cli/deprecations.go
@@ -0,0 +1,29 @@
+package cli
+
+import (
+	"os"
+	"strings"
+
+	"github.com/mudler/xlog"
+)
+
+// deprecatedFlags maps old flag names to their new replacements.
+var deprecatedFlags = map[string]string{
+	"--p2ptoken": "--p2p-token",
+}
+
+// warnDeprecatedFlags checks os.Args for any deprecated flag names and logs
+// a warning directing the user to the new name. Old flags continue to work
+// via kong aliases, so this is purely informational.
+func warnDeprecatedFlags() {
+	for _, arg := range os.Args[1:] {
+		// Strip any =value suffix to match flag names like --p2ptoken=xyz
+		flag := arg
+		if idx := strings.Index(flag, "="); idx != -1 {
+			flag = flag[:idx]
+		}
+		if newName, ok := deprecatedFlags[flag]; ok {
+			xlog.Warn("Deprecated flag used", "old", flag, "new", newName, "message", "please switch to the new flag name; the old name will be removed in a future release")
+		}
+	}
+}
diff --git a/core/cli/federated.go b/core/cli/federated.go
index ceea5a9e4..c61adab0f 100644
--- a/core/cli/federated.go
+++ b/core/cli/federated.go
@@ -10,13 +10,14 @@ import (
 
 type FederatedCLI struct {
 	Address            string `env:"LOCALAI_ADDRESS,ADDRESS" default:":8080" help:"Bind address for the API server" group:"api"`
-	Peer2PeerToken     string `env:"LOCALAI_P2P_TOKEN,P2P_TOKEN,TOKEN" name:"p2ptoken" help:"Token for P2P mode (optional)" group:"p2p"`
+	Peer2PeerToken     string `env:"LOCALAI_P2P_TOKEN,P2P_TOKEN,TOKEN" name:"p2p-token" aliases:"p2ptoken" help:"Token for P2P mode (optional; --p2ptoken is deprecated, use --p2p-token)" group:"p2p"`
 	RandomWorker       bool   `env:"LOCALAI_RANDOM_WORKER,RANDOM_WORKER" default:"false" help:"Select a random worker from the pool" group:"p2p"`
 	Peer2PeerNetworkID string `env:"LOCALAI_P2P_NETWORK_ID,P2P_NETWORK_ID" help:"Network ID for P2P mode, can be set arbitrarly by the user for grouping a set of instances." group:"p2p"`
 	TargetWorker       string `env:"LOCALAI_TARGET_WORKER,TARGET_WORKER" help:"Target worker to run the federated server on" group:"p2p"`
 }
 
 func (f *FederatedCLI) Run(ctx *cliContext.Context) error {
+	warnDeprecatedFlags()
 
 	fs := p2p.NewFederatedServer(f.Address, p2p.NetworkID(f.Peer2PeerNetworkID, p2p.FederatedID), f.Peer2PeerToken, !f.RandomWorker, f.TargetWorker)
 
diff --git a/core/cli/run.go b/core/cli/run.go
index 75100930c..df84ef790 100644
--- a/core/cli/run.go
+++ b/core/cli/run.go
@@ -20,6 +20,11 @@ import (
 	"github.com/mudler/xlog"
 )
 
+// CLI Flag Naming Convention:
+// All CLI flags use kebab-case (e.g., --backends-path, --p2p-token).
+// When renaming flags, add the old name as an alias for backward compatibility
+// and document the deprecation in the help text.
+
 type RunCMD struct {
 	ModelArgs []string `arg:"" optional:"" name:"models" help:"Model configuration URLs to load"`
 
@@ -66,7 +71,7 @@ type RunCMD struct {
 	Peer2Peer                          bool     `env:"LOCALAI_P2P,P2P" name:"p2p" default:"false" help:"Enable P2P mode" group:"p2p"`
 	Peer2PeerDHTInterval               int      `env:"LOCALAI_P2P_DHT_INTERVAL,P2P_DHT_INTERVAL" default:"360" name:"p2p-dht-interval" help:"Interval for DHT refresh (used during token generation)" group:"p2p"`
 	Peer2PeerOTPInterval               int      `env:"LOCALAI_P2P_OTP_INTERVAL,P2P_OTP_INTERVAL" default:"9000" name:"p2p-otp-interval" help:"Interval for OTP refresh (used during token generation)" group:"p2p"`
-	Peer2PeerToken                     string   `env:"LOCALAI_P2P_TOKEN,P2P_TOKEN,TOKEN" name:"p2ptoken" help:"Token for P2P mode (optional)" group:"p2p"`
+	Peer2PeerToken                     string   `env:"LOCALAI_P2P_TOKEN,P2P_TOKEN,TOKEN" name:"p2p-token" aliases:"p2ptoken" help:"Token for P2P mode (optional; --p2ptoken is deprecated, use --p2p-token)" group:"p2p"`
 	Peer2PeerNetworkID                 string   `env:"LOCALAI_P2P_NETWORK_ID,P2P_NETWORK_ID" help:"Network ID for P2P mode, can be set arbitrarly by the user for grouping a set of instances" group:"p2p"`
 	ParallelRequests                   bool     `env:"LOCALAI_PARALLEL_REQUESTS,PARALLEL_REQUESTS" help:"Enable backends to handle multiple requests in parallel if they support it (e.g.: llama.cpp or vllm)" group:"backends"`
 	SingleActiveBackend                bool     `env:"LOCALAI_SINGLE_ACTIVE_BACKEND,SINGLE_ACTIVE_BACKEND" help:"Allow only one backend to be run at a time (deprecated: use --max-active-backends=1 instead)" group:"backends"`
@@ -119,6 +124,8 @@ type RunCMD struct {
 }
 
 func (r *RunCMD) Run(ctx *cliContext.Context) error {
+	warnDeprecatedFlags()
+
 	if r.Version {
 		fmt.Println(internal.Version)
 		return nil
diff --git a/core/cli/util.go b/core/cli/util.go
index b002e254e..b536a5861 100644
--- a/core/cli/util.go
+++ b/core/cli/util.go
@@ -39,7 +39,7 @@ type HFScanCMD struct {
 }
 
 type UsecaseHeuristicCMD struct {
-	ConfigName string `name:"The config file to check"`
+	ConfigName string `arg:"" name:"config-name" help:"The config file to check"`
 	ModelsPath string `env:"LOCALAI_MODELS_PATH,MODELS_PATH" type:"path" default:"${basepath}/models" help:"Path containing models used for inferencing" group:"storage"`
 }