From a1714cc4ceefd4f4b5053e88010547d984c9c39e Mon Sep 17 00:00:00 2001
From: Bill Zhong <billzhong@users.noreply.github.com>
Date: Tue, 18 Feb 2025 05:06:39 -0330
Subject: [PATCH] API: Improve cli usage descriptions (#4401)
---
main/commands/all/api/balancer_info.go | 15 ++++------
main/commands/all/api/balancer_override.go | 26 +++++++----------
main/commands/all/api/inbound_user.go | 22 +++++++++-----
main/commands/all/api/inbound_user_count.go | 20 ++++++++-----
main/commands/all/api/inbounds_add.go | 13 ++++++---
main/commands/all/api/inbounds_remove.go | 13 ++++++---
main/commands/all/api/logger_restart.go | 13 +++++++--
main/commands/all/api/outbounds_add.go | 13 ++++++---
main/commands/all/api/outbounds_remove.go | 13 ++++++---
main/commands/all/api/rules_add.go | 13 ++++++---
main/commands/all/api/rules_remove.go | 15 ++++++----
main/commands/all/api/source_ip_block.go | 29 ++++++++++++-------
main/commands/all/api/stats_get.go | 21 +++++++++-----
main/commands/all/api/stats_online.go | 24 ++++++++-------
main/commands/all/api/stats_online_ip_list.go | 24 ++++++++-------
main/commands/all/api/stats_query.go | 17 +++++++----
main/commands/all/api/stats_sys.go | 17 +++++++----
17 files changed, 194 insertions(+), 114 deletions(-)
diff --git a/main/commands/all/api/balancer_info.go b/main/commands/all/api/balancer_info.go
index 0d376d63..f5b6804c 100644
--- a/main/commands/all/api/balancer_info.go
+++ b/main/commands/all/api/balancer_info.go
@@ -13,25 +13,20 @@ import (
var cmdBalancerInfo = &base.Command{
CustomFlags: true,
UsageLine: "{{.Exec}} api bi [--server=127.0.0.1:8080] [balancer]...",
- Short: "balancer information",
+ Short: "Retrieve balancer information",
Long: `
-Get information of specified balancers, including health, strategy
-and selecting. If no balancer tag specified, get information of
-all balancers.
+Retrieve information of specified balancers, including health, strategy and selecting.
+If no balancer tag specified, information for all balancers is returned.
-> Make sure you have "RoutingService" set in "config.api.services"
-of server config.
+> Ensure that "RoutingService" is enabled under "config.api.services" in the server configuration.
Arguments:
- -json
- Use json output.
-
-s, -server <server:port>
The API server address. Default 127.0.0.1:8080
-t, -timeout <seconds>
- Timeout seconds to call API. Default 3
+ Timeout in seconds for calling API. Default 3
Example:
diff --git a/main/commands/all/api/balancer_override.go b/main/commands/all/api/balancer_override.go
index 3ac013e9..7386b1a5 100644
--- a/main/commands/all/api/balancer_override.go
+++ b/main/commands/all/api/balancer_override.go
@@ -7,31 +7,27 @@ import (
var cmdBalancerOverride = &base.Command{
CustomFlags: true,
- UsageLine: "{{.Exec}} api bo [--server=127.0.0.1:8080] <-b balancer> outboundTag",
- Short: "balancer override",
+ UsageLine: "{{.Exec}} api bo [--server=127.0.0.1:8080] <-b balancer> outboundTag <-r>",
+ Short: "Override balancer",
Long: `
-Override a balancer's selection.
+Override the selection target of a balancer.
-> Make sure you have "RoutingService" set in "config.api.services"
-of server config.
+> Ensure that the "RoutingService" is properly configured under "config.api.services" in the server configuration.
-Once a balancer's selecting is overridden:
+Once the balancer's selection is overridden:
- The balancer's selection result will always be outboundTag
Arguments:
- -r, -remove
- Remove the overridden
-
- -r, -remove
- Remove the override
-
- -s, -server
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
+ -r, -remove
+ Remove the existing override.
Example:
diff --git a/main/commands/all/api/inbound_user.go b/main/commands/all/api/inbound_user.go
index 7a443183..23c191d5 100644
--- a/main/commands/all/api/inbound_user.go
+++ b/main/commands/all/api/inbound_user.go
@@ -8,20 +8,28 @@ import (
var cmdInboundUser = &base.Command{
CustomFlags: true,
UsageLine: "{{.Exec}} api inbounduser [--server=127.0.0.1:8080] -tag=tag [-email=email]",
- Short: "Get Inbound User",
+ Short: "Retrieve inbound user(s)",
Long: `
Get User info from an inbound.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-tag
Inbound tag
- -email
- User email. If email is not given, will get all users
+
+ -email
+ The user's email address. If not provided, all users will be retrieved.
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -tag="tag name" -email="xray@love.com"
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -tag="tag name"
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -tag="tag name" -email="xray@love.com"
`,
Run: executeInboundUser,
}
diff --git a/main/commands/all/api/inbound_user_count.go b/main/commands/all/api/inbound_user_count.go
index 18cab7e8..8c7c0fc3 100644
--- a/main/commands/all/api/inbound_user_count.go
+++ b/main/commands/all/api/inbound_user_count.go
@@ -8,18 +8,24 @@ import (
var cmdInboundUserCount = &base.Command{
CustomFlags: true,
UsageLine: "{{.Exec}} api inboundusercount [--server=127.0.0.1:8080] -tag=tag",
- Short: "Get Inbound User Count",
+ Short: "Retrieve inbound user count",
Long: `
-Get User count from an inbound.
+Retrieve the user count for a specified inbound tag.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-tag
- Inbound tag
+ Inbound tag
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -tag="tag name"
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -tag="tag name"
`,
Run: executeInboundUserCount,
}
diff --git a/main/commands/all/api/inbounds_add.go b/main/commands/all/api/inbounds_add.go
index dad8b0f9..9bad6f87 100644
--- a/main/commands/all/api/inbounds_add.go
+++ b/main/commands/all/api/inbounds_add.go
@@ -15,13 +15,18 @@ var cmdAddInbounds = &base.Command{
Short: "Add inbounds",
Long: `
Add inbounds to Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
`,
Run: executeAddInbounds,
}
diff --git a/main/commands/all/api/inbounds_remove.go b/main/commands/all/api/inbounds_remove.go
index 9ab83e20..400a239e 100644
--- a/main/commands/all/api/inbounds_remove.go
+++ b/main/commands/all/api/inbounds_remove.go
@@ -14,13 +14,18 @@ var cmdRemoveInbounds = &base.Command{
Short: "Remove inbounds",
Long: `
Remove inbounds from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json "tag name"
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json "tag name"
`,
Run: executeRemoveInbounds,
}
diff --git a/main/commands/all/api/logger_restart.go b/main/commands/all/api/logger_restart.go
index 7bd6f10d..15dacc15 100644
--- a/main/commands/all/api/logger_restart.go
+++ b/main/commands/all/api/logger_restart.go
@@ -11,11 +11,18 @@ var cmdRestartLogger = &base.Command{
Short: "Restart the logger",
Long: `
Restart the logger of Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
+Example:
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080
`,
Run: executeRestartLogger,
}
diff --git a/main/commands/all/api/outbounds_add.go b/main/commands/all/api/outbounds_add.go
index 5066e543..8d36f75a 100644
--- a/main/commands/all/api/outbounds_add.go
+++ b/main/commands/all/api/outbounds_add.go
@@ -15,13 +15,18 @@ var cmdAddOutbounds = &base.Command{
Short: "Add outbounds",
Long: `
Add outbounds to Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
`,
Run: executeAddOutbounds,
}
diff --git a/main/commands/all/api/outbounds_remove.go b/main/commands/all/api/outbounds_remove.go
index 9fdbc078..a081bc62 100644
--- a/main/commands/all/api/outbounds_remove.go
+++ b/main/commands/all/api/outbounds_remove.go
@@ -14,13 +14,18 @@ var cmdRemoveOutbounds = &base.Command{
Short: "Remove outbounds",
Long: `
Remove outbounds from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json "tag name"
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json "tag name"
`,
Run: executeRemoveOutbounds,
}
diff --git a/main/commands/all/api/rules_add.go b/main/commands/all/api/rules_add.go
index 11ec1e01..2e1404e6 100644
--- a/main/commands/all/api/rules_add.go
+++ b/main/commands/all/api/rules_add.go
@@ -16,16 +16,21 @@ var cmdAddRules = &base.Command{
Short: "Add routing rules",
Long: `
Add routing rules to Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
+
+ -t, -timeout <seconds>
Timeout seconds to call API. Default 3
+
-append
- append or replace config. Default false
+ Append to the existing configuration instead of replacing it. Default false
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
`,
Run: executeAddRules,
}
diff --git a/main/commands/all/api/rules_remove.go b/main/commands/all/api/rules_remove.go
index 4904022a..ac9a8d09 100644
--- a/main/commands/all/api/rules_remove.go
+++ b/main/commands/all/api/rules_remove.go
@@ -9,17 +9,22 @@ import (
var cmdRemoveRules = &base.Command{
CustomFlags: true,
- UsageLine: "{{.Exec}} api rmrules [--server=127.0.0.1:8080] ruleTag1 ruleTag2...",
+ UsageLine: "{{.Exec}} api rmrules [--server=127.0.0.1:8080] [ruleTag]...",
Short: "Remove routing rules by ruleTag",
Long: `
Remove routing rules by ruleTag from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 ruleTag1 ruleTag2
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 ruleTag1 ruleTag2
`,
Run: executeRemoveRules,
}
diff --git a/main/commands/all/api/source_ip_block.go b/main/commands/all/api/source_ip_block.go
index 1f773187..11f3d55d 100644
--- a/main/commands/all/api/source_ip_block.go
+++ b/main/commands/all/api/source_ip_block.go
@@ -14,25 +14,34 @@ import (
var cmdSourceIpBlock = &base.Command{
CustomFlags: true,
UsageLine: "{{.Exec}} api sib [--server=127.0.0.1:8080] -outbound=blocked -inbound=socks 1.2.3.4",
- Short: "Drop connections by source ip",
+ Short: "Block connections by source IP",
Long: `
-Drop connections by source ip.
+Block connections by source IP address.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-outbound
- route traffic to specific outbound.
+ Specifies the outbound tag.
+
-inbound
- target traffig from specific inbound.
+ Specifies the inbound tag.
+
-ruletag
- set ruleTag. Default sourceIpBlock
+ The ruleTag. Default sourceIpBlock
+
-reset
remove ruletag and apply new source IPs. Default false
- Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 c1.json c2.json
+Example:
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -outbound=blocked -inbound=socks 1.2.3.4
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -outbound=blocked -inbound=socks 1.2.3.4 -reset
`,
Run: executeSourceIpBlock,
}
diff --git a/main/commands/all/api/stats_get.go b/main/commands/all/api/stats_get.go
index c03fe5f8..9b5d82f9 100644
--- a/main/commands/all/api/stats_get.go
+++ b/main/commands/all/api/stats_get.go
@@ -8,19 +8,26 @@ import (
var cmdGetStats = &base.Command{
CustomFlags: true,
UsageLine: "{{.Exec}} api stats [--server=127.0.0.1:8080] [-name '']",
- Short: "Get statistics",
+ Short: "Retrieve statistics",
Long: `
-Get statistics from Xray.
+Retrieve the statistics from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-name
- Name of the stat counter.
+ Name of the counter.
+
-reset
- Reset the counter to fetching its value.
+ Reset the counter after fetching their values. Default false
+
Example:
+
{{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -name "inbound>>>statin>>>traffic>>>downlink"
`,
Run: executeGetStats,
diff --git a/main/commands/all/api/stats_online.go b/main/commands/all/api/stats_online.go
index 93592807..aca547a6 100644
--- a/main/commands/all/api/stats_online.go
+++ b/main/commands/all/api/stats_online.go
@@ -7,21 +7,25 @@ import (
var cmdOnlineStats = &base.Command{
CustomFlags: true,
- UsageLine: "{{.Exec}} api statsonline [--server=127.0.0.1:8080] [-name '']",
- Short: "Get online user",
+ UsageLine: "{{.Exec}} api statsonline [--server=127.0.0.1:8080] [-email '']",
+ Short: "Retrieve the online session count for a user",
Long: `
-Get statistics from Xray.
+Retrieve the current number of active sessions for a user from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-email
- email of the user.
- -reset
- Reset the counter to fetching its value.
+ The user's email address.
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -email "user1@test.com"
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -email "xray@love.com"
`,
Run: executeOnlineStats,
}
diff --git a/main/commands/all/api/stats_online_ip_list.go b/main/commands/all/api/stats_online_ip_list.go
index 45b0ed51..74e066f9 100644
--- a/main/commands/all/api/stats_online_ip_list.go
+++ b/main/commands/all/api/stats_online_ip_list.go
@@ -7,21 +7,25 @@ import (
var cmdOnlineStatsIpList = &base.Command{
CustomFlags: true,
- UsageLine: "{{.Exec}} api statsonlineiplist [--server=127.0.0.1:8080] [-name '']",
- Short: "Get online user ips list and access times",
+ UsageLine: "{{.Exec}} api statsonlineiplist [--server=127.0.0.1:8080] [-email '']",
+ Short: "Retrieve a user's online IP addresses and access times",
Long: `
-Get statistics from Xray.
+Retrieve the online IP addresses and corresponding access timestamps for a user from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-email
- email of the user.
- -reset
- Reset the counter to fetching its value (not used).
+ The user's email address.
+
Example:
- {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -email "user1@test.com"
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -email "xray@love.com"
`,
Run: executeOnlineStatsIpList,
}
diff --git a/main/commands/all/api/stats_query.go b/main/commands/all/api/stats_query.go
index f3163199..99d64437 100644
--- a/main/commands/all/api/stats_query.go
+++ b/main/commands/all/api/stats_query.go
@@ -11,16 +11,23 @@ var cmdQueryStats = &base.Command{
Short: "Query statistics",
Long: `
Query statistics from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
-pattern
- Pattern of the query.
+ Filter pattern for the statistics query.
+
-reset
- Reset the counter to fetching its value.
+ Reset the counter after fetching their values. Default false
+
Example:
+
{{.Exec}} {{.LongName}} --server=127.0.0.1:8080 -pattern "counter_"
`,
Run: executeQueryStats,
diff --git a/main/commands/all/api/stats_sys.go b/main/commands/all/api/stats_sys.go
index de7a8ce2..e34d056e 100644
--- a/main/commands/all/api/stats_sys.go
+++ b/main/commands/all/api/stats_sys.go
@@ -8,14 +8,21 @@ import (
var cmdSysStats = &base.Command{
CustomFlags: true,
UsageLine: "{{.Exec}} api statssys [--server=127.0.0.1:8080]",
- Short: "Get system statistics",
+ Short: "Retrieve system statistics",
Long: `
-Get system statistics from Xray.
+Retrieve system statistics from Xray.
+
Arguments:
- -s, -server
+
+ -s, -server <server:port>
The API server address. Default 127.0.0.1:8080
- -t, -timeout
- Timeout seconds to call API. Default 3
+
+ -t, -timeout <seconds>
+ Timeout in seconds for calling API. Default 3
+
+Example:
+
+ {{.Exec}} {{.LongName}} --server=127.0.0.1:8080
`,
Run: executeSysStats,
}