From c39cd3cde9d3a332203291d8533dc6eb17480beb Mon Sep 17 00:00:00 2001 From: Brian <137178429+nonfungible-human@users.noreply.github.com> Date: Thu, 26 Oct 2023 12:31:40 -0600 Subject: [PATCH] main: make cmd documentation coherent --- cmd/litcli/accounts.go | 86 ++++++++++++++++++--------------------- cmd/litcli/actions.go | 13 +++--- cmd/litcli/autopilot.go | 48 ++++++++++------------ cmd/litcli/helpers.go | 32 +++++++-------- cmd/litcli/main.go | 10 ++--- cmd/litcli/privacy_map.go | 21 ++++++---- cmd/litcli/proxy.go | 35 +++++++++------- cmd/litcli/sessions.go | 55 +++++++++++++------------ cmd/litcli/status.go | 7 ++-- 9 files changed, 154 insertions(+), 153 deletions(-) diff --git a/cmd/litcli/accounts.go b/cmd/litcli/accounts.go index a26cfaf42..1165256f1 100644 --- a/cmd/litcli/accounts.go +++ b/cmd/litcli/accounts.go @@ -22,7 +22,7 @@ var accountsCommands = []cli.Command{ { Name: "accounts", ShortName: "a", - Usage: "manage accounts", + Usage: "Manage accounts", Category: "Accounts", Subcommands: []cli.Command{ createAccountCommand, @@ -31,6 +31,7 @@ var accountsCommands = []cli.Command{ accountInfoCommand, removeAccountCommand, }, + Description: "Manage accounts.", }, } @@ -39,38 +40,38 @@ var createAccountCommand = cli.Command{ ShortName: "c", Usage: "Create a new off-chain account with a balance.", ArgsUsage: "balance [expiration_date] [--label=LABEL] [--save_to=FILE]", - Description: ` - Adds an entry to the account database. This entry represents an amount - of satoshis (account balance) that can be spent using off-chain - transactions (e.g. paying invoices). - - Macaroons can be created to be locked to an account. This makes sure - that the bearer of the macaroon can only spend at most that amount of - satoshis through the daemon that has issued the macaroon. - - Accounts only assert a maximum amount spendable. Having a certain - account balance does not guarantee that the node has the channel - liquidity to actually spend that amount. - `, + Description: "Adds an entry to the account database. " + + "This entry represents an amount of satoshis (account " + + "balance) that can be spent using off-chain transactions " + + "(e.g. paying invoices).\n\n" + + + " Macaroons can be created to be locked to an account. " + + "This makes sure that the bearer of the macaroon can only " + + "spend at most that amount of satoshis through the daemon " + + "that has issued the macaroon.\n\n" + + + " Accounts only assert a maximum amount spendable. Having " + + "a certain account balance does not guarantee that the node " + + "has the channel liquidity to actually spend that amount.", Flags: []cli.Flag{ cli.Uint64Flag{ Name: "balance", - Usage: "the initial balance of the account", + Usage: "The initial balance of the account.", }, cli.Int64Flag{ Name: "expiration_date", - Usage: "the expiration date of the account expressed " + + Usage: "The expiration date of the account expressed " + "in seconds since the unix epoch. 0 means " + - "it does not expire", + "it does not expire.", }, cli.StringFlag{ Name: "save_to", - Usage: "store the account macaroon created for the " + - "account to the given file", + Usage: "Store the account macaroon created for the " + + "account to the given file.", }, cli.StringFlag{ Name: labelName, - Usage: "(optional) the unique label of the account", + Usage: "(optional) The unique label of the account.", }, }, Action: createAccount, @@ -152,31 +153,29 @@ var updateAccountCommand = cli.Command{ ShortName: "u", Usage: "Update an existing off-chain account.", ArgsUsage: "[id | label] new_balance [new_expiration_date] [--save_to=]", - Description: ` - Updates an existing off-chain account and sets either a new balance or - new expiration date or both. - `, + Description: "Updates an existing off-chain account and sets " + + "either a new balance or new expiration date or both.", Flags: []cli.Flag{ cli.StringFlag{ Name: idName, - Usage: "the ID of the account to update", + Usage: "The ID of the account to update.", }, cli.StringFlag{ Name: labelName, - Usage: "(optional) the unique label of the account", + Usage: "(optional) The unique label of the account.", }, cli.Int64Flag{ Name: "new_balance", - Usage: "the new balance of the account; -1 means do " + - "not update the balance", + Usage: "The new balance of the account; -1 means do " + + "not update the balance.", Value: -1, }, cli.Int64Flag{ Name: "new_expiration_date", - Usage: "the new expiration date of the account " + + Usage: "The new expiration date of the account " + "expressed in seconds since the unix epoch; " + "-1 means do not update the expiration date; " + - "0 means it does not expire", + "0 means it does not expire.", Value: -1, }, }, @@ -243,11 +242,9 @@ func updateAccount(ctx *cli.Context) error { var listAccountsCommand = cli.Command{ Name: "list", ShortName: "l", - Usage: "Lists all off-chain accounts.", - Description: ` - Returns all accounts that are currently stored in the account - database. - `, + Usage: "List all off-chain accounts.", + Description: "Returns all accounts that are currently stored in " + + "the account database.", Action: listAccounts, } @@ -275,17 +272,16 @@ var accountInfoCommand = cli.Command{ ShortName: "i", Usage: "Show information about a single off-chain account.", ArgsUsage: "[id | label]", - Description: ` - Returns a single account entry from the account database. - `, + Description: "Returns a single account entry from the account " + + "database.", Flags: []cli.Flag{ cli.StringFlag{ Name: idName, - Usage: "the ID of the account", + Usage: "The ID of the account.", }, cli.StringFlag{ Name: labelName, - Usage: "(optional) the unique label of the account", + Usage: "(optional) The unique label of the account.", }, }, Action: accountInfo, @@ -321,19 +317,17 @@ func accountInfo(ctx *cli.Context) error { var removeAccountCommand = cli.Command{ Name: "remove", ShortName: "r", - Usage: "Removes an off-chain account from the database.", + Usage: "Remove an off-chain account from the database.", ArgsUsage: "[id | label]", - Description: ` - Removes an account entry from the account database. - `, + Description: "Removes an account entry from the account database.", Flags: []cli.Flag{ cli.StringFlag{ Name: idName, - Usage: "the ID of the account", + Usage: "The ID of the account.", }, cli.StringFlag{ Name: labelName, - Usage: "(optional) the unique label of the account", + Usage: "(optional) The unique label of the account.", }, }, Action: removeAccount, diff --git a/cmd/litcli/actions.go b/cmd/litcli/actions.go index ebce2da4c..e752c561d 100644 --- a/cmd/litcli/actions.go +++ b/cmd/litcli/actions.go @@ -12,6 +12,7 @@ import ( var listActionsCommand = cli.Command{ Name: "actions", Usage: "List actions performed on the Litd server", + Category: "Firewall", Action: listActions, Flags: []cli.Flag{ cli.StringFlag{ @@ -53,22 +54,22 @@ var listActionsCommand = cli.Command{ Name: "state", Usage: "The action state to filter on. If not set, " + "then actions of any state will be returned. " + - "Options include: 'pending', 'done' and 'error", + "Options include: 'pending', 'done' and 'error'.", }, cli.Uint64Flag{ Name: "index_offset", Usage: "The index of an action that will be used as " + - "either the start a query to determine which " + - "actions should be returned in the response", + "the start of a query to determine which " + + "actions should be returned in the response.", }, cli.Uint64Flag{ Name: "max_num_actions", - Usage: "The max number of actions to return", + Usage: "The max number of actions to return.", }, cli.BoolFlag{ Name: "oldest_first", - Usage: "Tf set, actions succeeding the index_offset " + - "will be returned", + Usage: "If set, actions succeeding the index_offset " + + "will be returned.", }, cli.BoolFlag{ Name: "count_total", diff --git a/cmd/litcli/autopilot.go b/cmd/litcli/autopilot.go index befc5a038..9b8c3f07f 100644 --- a/cmd/litcli/autopilot.go +++ b/cmd/litcli/autopilot.go @@ -16,23 +16,22 @@ import ( var autopilotCommands = cli.Command{ Name: "autopilot", - Usage: "manage autopilot sessions", - Category: "Autopilot", + Usage: "Manage autopilot sessions", + Category: "LNC", Subcommands: []cli.Command{ listAutopilotFeaturesCmd, addAutopilotSessionCmd, revokeAutopilotSessionCmd, listAutopilotSessionsCmd, }, + Description: "Manage autopilot sessions.", } var listAutopilotFeaturesCmd = cli.Command{ Name: "features", ShortName: "f", Usage: "List available Autopilot features.", - Description: ` - List available Autopilot features. - `, + Description: "List available Autopilot features.", Action: listFeatures, } @@ -40,11 +39,10 @@ var addAutopilotSessionCmd = cli.Command{ Name: "add", ShortName: "a", Usage: "Initialize an Autopilot session.", - Description: ` - Initialize an Autopilot session. - - If set for any feature, configuration flags need to be repeated for each - feature that is registered, corresponding to the order of features.`, + Description: "Initialize an Autopilot session.\n\n" + + " If set for any feature, configuration flags need to be " + + "repeated for each feature that is registered, corresponding " + + "to the order of features.", Action: initAutopilotSession, Flags: []cli.Flag{ labelFlag, @@ -57,14 +55,14 @@ var addAutopilotSessionCmd = cli.Command{ }, cli.StringFlag{ Name: "channel-restrict-list", - Usage: "list of channel IDs that the " + + Usage: "List of channel IDs that the " + "Autopilot server should not " + "perform actions on. In the " + "form of: chanID1,chanID2,...", }, cli.StringFlag{ Name: "peer-restrict-list", - Usage: "list of peer IDs that the " + + Usage: "List of peer IDs that the " + "Autopilot server should not " + "perform actions on. In the " + "form of: peerID1,peerID2,...", @@ -72,16 +70,16 @@ var addAutopilotSessionCmd = cli.Command{ cli.StringFlag{ Name: "group_id", Usage: "The hex encoded group ID of the session " + - "group to link this one to", + "group to link this one to.", }, cli.StringSliceFlag{ Name: "feature-config", - Usage: `JSON-serialized configuration with the ` + - `expected format: {"version":0,` + - `"option1":"parameter1",` + - `"option2":"parameter2",...}. An empty ` + - `configuration is allowed with {} to use the ` + - `default configuration`, + Usage: "JSON-serialized configuration with the " + + "expected format: {\"version\":0," + + "\"option1\":\"parameter1\"," + + "\"option2\":\"parameter2\",...}. An empty " + + "configuration is allowed with {} to use the " + + "default configuration.", }, }, } @@ -90,15 +88,13 @@ var revokeAutopilotSessionCmd = cli.Command{ Name: "revoke", ShortName: "r", Usage: "Revoke an Autopilot session.", - Description: ` - Revoke an active Autopilot session. - `, + Description: "Revoke an active Autopilot session.", Action: revokeAutopilotSession, Flags: []cli.Flag{ cli.StringFlag{ Name: "localpubkey", - Usage: "local pubkey of the " + - "session to revoke", + Usage: "Local pubkey of the " + + "session to revoke.", Required: true, }, }, @@ -108,9 +104,7 @@ var listAutopilotSessionsCmd = cli.Command{ Name: "list", ShortName: "l", Usage: "List all Autopilot sessions.", - Description: ` - List all Autopilot sessions. - `, + Description: "List all Autopilot sessions.\n", Action: listAutopilotSessions, } diff --git a/cmd/litcli/helpers.go b/cmd/litcli/helpers.go index 4771509da..d2f4d6fe6 100644 --- a/cmd/litcli/helpers.go +++ b/cmd/litcli/helpers.go @@ -14,9 +14,10 @@ import ( // helperCommands are commands that do not require a connection to LiTd to // return a response. var helperCommands = cli.Command{ - Name: "helper", - Usage: "helper commands", - Category: "Helper", + Name: "helper", + Usage: "Helper commands", + Description: "Helper commands.", + Category: "LiT", Subcommands: []cli.Command{ generateSuperMacRootIDCmd, isSuperMacaroonCmd, @@ -27,12 +28,11 @@ var helperCommands = cli.Command{ // key ID for a super macaroon. A suffix may be specified. var generateSuperMacRootIDCmd = cli.Command{ Name: "supermacrootkey", - Usage: "Generate a valid super macaroon root key ID from scratch " + - "or from a given root key ID suffix", - Description: ` - This command can be used to generate a valid super macaroon root key ID - from scratch or from a given root key ID suffix. - `, + Usage: "Generate a valid super macaroon root key ID from " + + "scratch or from a given root key ID suffix.", + Description: "This command can be used to generate a valid " + + "super macaroon root key ID from scratch or from " + + "a given root key ID suffix.", Action: superMacRootKey, Flags: []cli.Flag{ cli.StringFlag{ @@ -40,8 +40,8 @@ var generateSuperMacRootIDCmd = cli.Command{ Usage: "A 4-byte suffix to use in the construction " + "of the root key ID. If not provided, then a " + "random one will be generated. This must be " + - "specified as a hex string using a maximum of " + - "8 characters.", + "specified as a hex string using a maximum " + + "of 8 characters.", }, }, } @@ -81,16 +81,14 @@ func superMacRootKey(ctx *cli.Context) error { // a macaroon is a super macaroon. var isSuperMacaroonCmd = cli.Command{ Name: "issupermacaroon", - Usage: "Prints 'true' if the given macaroon is a super macaroon", - Description: ` - This command can be used to verify if a macaroon is considered a - super macaroon. - `, + Usage: "Prints 'true' if the given macaroon is a super macaroon.", + Description: "This command can be used to verify if a macaroon is " + + "considered a super macaroon.", Action: isSuperMacaroon, Flags: []cli.Flag{ cli.StringFlag{ Name: "mac", - Usage: "The hex-encoded macaroon", + Usage: "The hex-encoded macaroon.", Required: true, }, }, diff --git a/cmd/litcli/main.go b/cmd/litcli/main.go index 78b8a4bb6..f8dc55747 100644 --- a/cmd/litcli/main.go +++ b/cmd/litcli/main.go @@ -33,22 +33,22 @@ var ( baseDirFlag = cli.StringFlag{ Name: "basedir", Value: terminal.DefaultLitDir, - Usage: "path to lit's base directory", + Usage: "Path to LiT's base directory", } networkFlag = cli.StringFlag{ Name: "network, n", - Usage: "the network litd is running on e.g. mainnet, " + + Usage: "The network litd is running on e.g. mainnet, " + "testnet, etc.", Value: terminal.DefaultNetwork, } tlsCertFlag = cli.StringFlag{ Name: "tlscertpath", - Usage: "path to lit's TLS certificate", + Usage: "Path to lit's TLS certificate", Value: terminal.DefaultTLSCertPath, } macaroonPathFlag = cli.StringFlag{ Name: "macaroonpath", - Usage: "path to lit's macaroon file", + Usage: "Path to lit's macaroon file", Value: terminal.DefaultMacaroonPath, } ) @@ -63,7 +63,7 @@ func main() { cli.StringFlag{ Name: "rpcserver", Value: "localhost:8443", - Usage: "lit daemon address host:port", + Usage: "LiT daemon address host:port", }, networkFlag, baseDirFlag, diff --git a/cmd/litcli/privacy_map.go b/cmd/litcli/privacy_map.go index e71574913..8532d6583 100644 --- a/cmd/litcli/privacy_map.go +++ b/cmd/litcli/privacy_map.go @@ -14,8 +14,8 @@ var privacyMapCommands = cli.Command{ Name: "privacy", ShortName: "p", Usage: "Access the real-pseudo string pairs of the " + - "privacy mapper", - Category: "Privacy", + "privacy mapper.", + Category: "Firewall", Flags: []cli.Flag{ cli.StringFlag{ Name: "session_id", @@ -24,7 +24,7 @@ var privacyMapCommands = cli.Command{ }, cli.BoolFlag{ Name: "realtopseudo", - Usage: "set to true if the input should be " + + Usage: "Set to true if the input should be " + "mapped to its pseudo counterpart. " + "Otherwise the input will be taken " + "as the pseudo value that should be " + @@ -40,17 +40,24 @@ var privacyMapCommands = cli.Command{ privacyMapConvertStrCommand, privacyMapConvertUint64Command, }, + Description: "Access the real-pseudo string pairs of the " + + "privacy mapper. To improve privacy around data " + + "sharing, channel ids, channel points and node " + + "pubkeys are obfuscated by litd through a system " + + "called the Privacy Mapper. The Privacy Mapper can " + + "convert both strings and uint64 to the pseudo " + + "counter part and back.", } var privacyMapConvertStrCommand = cli.Command{ Name: "str", ShortName: "s", - Usage: "convert a string to its real or pseudo counter part", + Usage: "Convert a string to its real or pseudo counter part.", Action: privacyMapConvertStr, Flags: []cli.Flag{ cli.StringFlag{ Name: "input", - Usage: "the string to convert", + Usage: "The string to convert.", Required: true, }, }, @@ -99,12 +106,12 @@ func privacyMapConvertStr(ctx *cli.Context) error { var privacyMapConvertUint64Command = cli.Command{ Name: "uint64", ShortName: "u", - Usage: "convert a uint64 to its real or pseudo counter part", + Usage: "Convert a uint64 to its real or pseudo counter part.", Action: privacyMapConvertUint64, Flags: []cli.Flag{ cli.Uint64Flag{ Name: "input", - Usage: "the uint64 to convert", + Usage: "The uint64 to convert.", Required: true, }, }, diff --git a/cmd/litcli/proxy.go b/cmd/litcli/proxy.go index 08a4ff58e..87ec03b8e 100644 --- a/cmd/litcli/proxy.go +++ b/cmd/litcli/proxy.go @@ -14,22 +14,11 @@ import ( ) var litCommands = []cli.Command{ - { - Name: "stop", - Usage: "shutdown the LiT daemon", - Category: "LiT", - Action: shutdownLit, - }, - { - Name: "getinfo", - Usage: "Returns basic information related to the active " + - "daemon.", - Category: "LiT", - Action: getInfo, - }, { Name: "bakesupermacaroon", Usage: "Bake a new super macaroon with all of LiT's active " + + "permissions", + Description: "Bake a new super macaroon with all of LiT's active " + "permissions.", Category: "LiT", Action: bakeSuperMacaroon, @@ -45,11 +34,27 @@ var litCommands = []cli.Command{ }, cli.StringFlag{ Name: "save_to", - Usage: "save returned admin macaroon to " + - "this file", + Usage: "Save returned admin macaroon to " + + "this file.", }, }, }, + { + Name: "getinfo", + Usage: "Returns basic information related to the active " + + "daemon", + Description: "Returns basic information related to the active " + + "daemon.", + Category: "LiT", + Action: getInfo, + }, + { + Name: "stop", + Usage: "Shutdown the LiT daemon", + Description: "Shutdown the LiT daemon.\n", + Category: "LiT", + Action: shutdownLit, + }, } func getInfo(ctx *cli.Context) error { diff --git a/cmd/litcli/sessions.go b/cmd/litcli/sessions.go index 0075be327..16cbdeb85 100644 --- a/cmd/litcli/sessions.go +++ b/cmd/litcli/sessions.go @@ -17,24 +17,24 @@ var ( defaultSessionExpiry = time.Hour * 24 * 90 labelFlag = cli.StringFlag{ - Name: "label", - Usage: "session label", + Name: "label", + Usage: "The session label.", Required: true, } expiryFlag = cli.Uint64Flag{ Name: "expiry", - Usage: "number of seconds that the session should " + - "remain active", + Usage: "The number of seconds that the session should " + + "remain active.", Value: uint64(defaultSessionExpiry.Seconds()), } mailboxServerAddrFlag = cli.StringFlag{ Name: "mailboxserveraddr", - Usage: "the host:port of the mailbox server to be used", + Usage: "The host:port of the mailbox server to be used.", Value: "mailbox.terminal.lightning.today:443", } devserver = cli.BoolFlag{ Name: "devserver", - Usage: "set to true to skip verification of the " + + Usage: "Set to true to skip verification of the " + "server's tls cert.", } ) @@ -43,20 +43,21 @@ var sessionCommands = []cli.Command{ { Name: "sessions", ShortName: "s", - Usage: "manage Terminal Web sessions", - Category: "Sessions", + Usage: "Manage Lightning Node Connect sessions", + Category: "LNC", Subcommands: []cli.Command{ addSessionCommand, listSessionCommand, revokeSessionCommand, }, + Description: "Manage Lightning Node Connect sessions.", }, } var addSessionCommand = cli.Command{ Name: "add", ShortName: "a", - Usage: "create a new Terminal Web session", + Usage: "Create a new Lightning Node Connect session.", Description: "Add a new active session.", Action: addSession, Flags: []cli.Flag{ @@ -66,15 +67,15 @@ var addSessionCommand = cli.Command{ devserver, cli.StringFlag{ Name: "type", - Usage: "session type to be created which will " + + Usage: "The session type to be created which will " + "determine the permissions a user has when " + - "connecting with the session. Options " + - "include readonly|admin|account|custom", + "connecting with the session; options " + + "include readonly|admin|account|custom.", Value: "readonly", }, cli.StringSliceFlag{ Name: "uri", - Usage: "A URI that should be included in the " + + Usage: "The URI that should be included in the " + "macaroon of a custom session. Note that " + "this flag will only be used if the 'type' " + "flag is set to 'custom'. This flag can be " + @@ -159,7 +160,7 @@ func parseSessionType(sessionType string) (litrpc.SessionType, error) { var listSessionCommand = cli.Command{ Name: "list", ShortName: "l", - Usage: "list Terminal Web sessions", + Usage: "List Lightning Node Connect sessions.", Description: "List sessions.", Subcommands: []cli.Command{ listAllSessionsCommand, @@ -173,40 +174,40 @@ var listSessionCommand = cli.Command{ var listAllSessionsCommand = cli.Command{ Name: "all", ShortName: "a", - Usage: "list all Terminal Web sessions", - Description: "List all sessions.", + Usage: "List all Lightning Node Connect sessions.", + Description: "List all sessions.\n", Action: listSessions(sessionFilterAll), } var listRevokedSessions = cli.Command{ Name: "revoked", ShortName: "r", - Usage: "list revoked Terminal Web sessions", - Description: "List revoked sessions.", + Usage: "List revoked Lightning Node Connect sessions.", + Description: "List revoked sessions.\n", Action: listSessions(sessionFilterRevoked), } var listInUseSessions = cli.Command{ Name: "inuse", ShortName: "u", - Usage: "list in-use Terminal Web sessions", - Description: "List in-use sessions.", + Usage: "List in-use Lightning Node Connect sessions.", + Description: "List in-use sessions.\n", Action: listSessions(sessionFilterInUse), } var listExpiredSessions = cli.Command{ Name: "expired", ShortName: "e", - Usage: "list expired Terminal Web sessions", - Description: "List expired sessions.", + Usage: "List expired Lightning Node Connect sessions.", + Description: "List expired sessions.\n", Action: listSessions(sessionFilterExpired), } var listCreatedSessions = cli.Command{ Name: "created", ShortName: "c", - Usage: "list created Terminal Web sessions", - Description: "List created sessions.", + Usage: "List created Lightning Node Connect sessions.", + Description: "List created sessions.\n", Action: listSessions(sessionFilterCreated), } @@ -266,13 +267,13 @@ func listSessions(filter sessionFilter) func(ctx *cli.Context) error { var revokeSessionCommand = cli.Command{ Name: "revoke", ShortName: "r", - Usage: "revoke a Terminal Web session", - Description: "Revoke an active session", + Usage: "Revoke a Lightning Node Connect session.", + Description: "Revoke an active session.", Action: revokeSession, Flags: []cli.Flag{ cli.StringFlag{ Name: "localpubkey", - Usage: "local pubkey of the session to revoke", + Usage: "The local pubkey of the session to revoke.", Required: true, }, }, diff --git a/cmd/litcli/status.go b/cmd/litcli/status.go index ffd031bb7..f4ea4a66c 100644 --- a/cmd/litcli/status.go +++ b/cmd/litcli/status.go @@ -10,9 +10,10 @@ import ( var statusCommands = []cli.Command{ { - Name: "status", - Usage: "info about litd status", - Category: "Status", + Name: "status", + Usage: "View info about litd status", + Description: "View info about litd status.\n", + Category: "LiT", Action: getStatus, }, }