From a1714cc4ceefd4f4b5053e88010547d984c9c39e Mon Sep 17 00:00:00 2001 From: Bill Zhong 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 The API server address. Default 127.0.0.1:8080 -t, -timeout - 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout + + -t, -timeout 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + 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 The API server address. Default 127.0.0.1:8080 - -t, -timeout - Timeout seconds to call API. Default 3 + + -t, -timeout + Timeout in seconds for calling API. Default 3 + +Example: + + {{.Exec}} {{.LongName}} --server=127.0.0.1:8080 `, Run: executeSysStats, }