docs: add docs about all cli commands (#2983)

.github/workflows/cli-docs-update.yml

@@ -0,0 +1,24 @@
+name: CLI commands docs check
+
+on:
+  pull_request:
+    branches:
+      - master
+      - support/**
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    name: cli-docs-check
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Generate new CLI doc files
+        run: make cli-gendoc
+
+      - name: Fail if CLI commands files are changed but the documentation is not updated
+        run: |
+          git add -N docs/cli-commands
+          git diff --exit-code -- docs/cli-commands/

CHANGELOG.md

@@ -15,6 +15,8 @@ attribute, which is used for container domain name in NNS contracts (#2954)
 - `neofs-lens meta last-resync-epoch` command (#2966)
 - `neofs-lens fstree cleanup-tmp` command (#2967)
 - `neofs-cli control object revive` command (#2968)
+- `--disable-auto-gen-tag` flag for gendoc command (#2983)
+- Docs files for cli commands to the `docs/cli-commands` folder (#2983)
 
 ### Fixed
 - Do not search for tombstones when handling their expiration, use local indexes instead (#2929)

Makefile

@@ -135,6 +135,10 @@ test:
 lint: .golangci.yml
 	@golangci-lint --timeout=5m run
 
+cli-gendoc: $(BIN)/neofs-cli
+	@echo "⇒ Generating CLI commands documentation"
+	@$< gendoc ./docs/cli-commands -d
+
 # Run linters in Docker
 docker/lint:
 	docker run --rm -t \

README.md

@@ -91,6 +91,8 @@ have additional documents describing them:
  * [Extended headers](docs/cli-xheaders.md)
  * [Exit codes](docs/cli-exit-codes.md)
 
+See [docs/cli-commands](docs/cli-commands) for information about all cli commands.
+
 `neofs-adm` is a network setup and management utility usually used by the
 network administrators. Refer to [docs/cli-adm.md](docs/cli-adm.md) for mode
 information about it.

cmd/neofs-cli/modules/control/shards_set_mode.go

@@ -3,6 +3,7 @@ package control
 import (
 	"errors"
 	"fmt"
+	"sort"
 	"strings"
 
 	"github.com/mr-tron/base58"
@@ -91,6 +92,7 @@ func initControlSetShardModeCmd() {
 	iterateSafeShardModes(func(strMode string) {
 		modes = append(modes, "'"+strMode+"'")
 	})
+	sort.Strings(modes)
 
 	flags.String(shardModeFlag, "",
 		fmt.Sprintf("New shard mode (%s)", strings.Join(modes, ", ")),

docs/cli-commands/neofs-cli.md

@@ -0,0 +1,42 @@
+## neofs-cli
+
+Command Line Tool to work with NeoFS
+
+### Synopsis
+
+NeoFS CLI provides all basic interactions with NeoFS and it's services.
+
+It contains commands for interaction with NeoFS nodes using different versions
+of neofs-api and some useful utilities for compiling ACL rules from JSON
+notation, managing container access through protocol gates, querying network map
+and much more!
+
+```
+neofs-cli [flags]
+```
+
+### Options
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -h, --help            help for neofs-cli
+  -v, --verbose         Verbose output
+      --version         Application version and NeoFS API compatibility
+```
+
+### SEE ALSO
+
+* [neofs-cli accounting](neofs-cli_accounting.md)	 - Operations with accounts and balances
+* [neofs-cli acl](neofs-cli_acl.md)	 - Operations with Access Control Lists
+* [neofs-cli bearer](neofs-cli_bearer.md)	 - Operations with bearer token
+* [neofs-cli completion](neofs-cli_completion.md)	 - Generate completion script
+* [neofs-cli container](neofs-cli_container.md)	 - Operations with containers
+* [neofs-cli control](neofs-cli_control.md)	 - Operations with storage node
+* [neofs-cli gendoc](neofs-cli_gendoc.md)	 - Generate documentation for this command
+* [neofs-cli netmap](neofs-cli_netmap.md)	 - Operations with Network Map
+* [neofs-cli object](neofs-cli_object.md)	 - Operations with Objects
+* [neofs-cli session](neofs-cli_session.md)	 - Operations with session token
+* [neofs-cli storagegroup](neofs-cli_storagegroup.md)	 - Operations with Storage Groups
+* [neofs-cli tree](neofs-cli_tree.md)	 - Operations with the Tree service
+* [neofs-cli util](neofs-cli_util.md)	 - Utility operations
+

docs/cli-commands/neofs-cli_accounting.md

@@ -0,0 +1,26 @@
+## neofs-cli accounting
+
+Operations with accounts and balances
+
+### Synopsis
+
+Operations with accounts and balances
+
+### Options
+
+```
+  -h, --help   help for accounting
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli](neofs-cli.md)	 - Command Line Tool to work with NeoFS
+* [neofs-cli accounting balance](neofs-cli_accounting_balance.md)	 - Get internal balance of NeoFS account
+

docs/cli-commands/neofs-cli_accounting_balance.md

@@ -0,0 +1,33 @@
+## neofs-cli accounting balance
+
+Get internal balance of NeoFS account
+
+### Synopsis
+
+Get internal balance of NeoFS account
+
+```
+neofs-cli accounting balance [flags]
+```
+
+### Options
+
+```
+      --address string        Address of wallet account
+  -h, --help                  help for balance
+      --owner string          owner of balance account (omit to use owner from private key)
+  -r, --rpc-endpoint string   Remote node address (as 'multiaddr' or '<host>:<port>')
+  -w, --wallet string         Path to the wallet
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli accounting](neofs-cli_accounting.md)	 - Operations with accounts and balances
+

docs/cli-commands/neofs-cli_acl.md

@@ -0,0 +1,23 @@
+## neofs-cli acl
+
+Operations with Access Control Lists
+
+### Options
+
+```
+  -h, --help   help for acl
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli](neofs-cli.md)	 - Command Line Tool to work with NeoFS
+* [neofs-cli acl basic](neofs-cli_acl_basic.md)	 - Operations with Basic Access Control Lists
+* [neofs-cli acl extended](neofs-cli_acl_extended.md)	 - Operations with Extended Access Control Lists
+

docs/cli-commands/neofs-cli_acl_basic.md

@@ -0,0 +1,22 @@
+## neofs-cli acl basic
+
+Operations with Basic Access Control Lists
+
+### Options
+
+```
+  -h, --help   help for basic
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli acl](neofs-cli_acl.md)	 - Operations with Access Control Lists
+* [neofs-cli acl basic print](neofs-cli_acl_basic_print.md)	 - Pretty print basic ACL from the HEX representation
+

docs/cli-commands/neofs-cli_acl_basic_print.md

@@ -0,0 +1,40 @@
+## neofs-cli acl basic print
+
+Pretty print basic ACL from the HEX representation
+
+### Synopsis
+
+Pretty print basic ACL from the HEX representation or keyword.
+Few roles have exclusive default access to set of operation, even if particular bit deny it.
+Container have access to the operations of the data replication mechanism:
+    Get, Head, Put, Search, Hash.
+InnerRing members are allowed to data audit ops only:
+    Get, Head, Hash, Search.
+
+```
+neofs-cli acl basic print [flags]
+```
+
+### Examples
+
+```
+neofs-cli acl basic print 0x1C8C8CCC
+```
+
+### Options
+
+```
+  -h, --help   help for print
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli acl basic](neofs-cli_acl_basic.md)	 - Operations with Basic Access Control Lists
+

docs/cli-commands/neofs-cli_acl_extended.md

@@ -0,0 +1,23 @@
+## neofs-cli acl extended
+
+Operations with Extended Access Control Lists
+
+### Options
+
+```
+  -h, --help   help for extended
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli acl](neofs-cli_acl.md)	 - Operations with Access Control Lists
+* [neofs-cli acl extended create](neofs-cli_acl_extended_create.md)	 - Create extended ACL from the text representation
+* [neofs-cli acl extended print](neofs-cli_acl_extended_print.md)	 - Pretty print extended ACL from the file(in text or json format) or for given container.
+

docs/cli-commands/neofs-cli_acl_extended_create.md

@@ -0,0 +1,68 @@
+## neofs-cli acl extended create
+
+Create extended ACL from the text representation
+
+### Synopsis
+
+Create extended ACL from the text representation.
+
+Rule consist of these blocks: <action> <operation> [<filter1> ...] [<target1> ...]
+
+Action is 'allow' or 'deny'.
+
+Operation is an object service verb: 'get', 'head', 'put', 'search', 'delete', 'getrange', or 'getrangehash'.
+
+Filter consists of <typ>:<key><match><value>
+  Typ is 'obj' for object applied filter or 'req' for request applied filter. 
+  Key is a valid unicode string corresponding to object or request header key. 
+    Well-known system object headers start with '$Object:' prefix.
+    User defined headers start without prefix.
+    Read more about filter keys at github.com/nspcc-dev/neofs-api/blob/master/proto-docs/acl.md#message-eaclrecordfilter
+  Match is:
+    '=' for string equality or, if no value, attribute absence;
+    '!=' for string inequality;
+    '>' | '>=' | '<' | '<=' for integer comparison.
+  Value is a valid unicode string corresponding to object or request header value. Numeric filters must have base-10 integer values.
+
+Target is 
+  'user' for container owner, 
+  'system' for Storage nodes in container and Inner Ring nodes,
+  'others' for all other request senders, 
+  'pubkey:<key1>,<key2>,...' for exact request sender, where <key> is a hex-encoded 33-byte public key, DEPRECATED,
+  'address:<adr1>,<adr2>,...' for exact request sender, where <adr> is a base58 25-byte address. Example: NSiVJYZej4XsxG5CUpdwn7VRQk8iiiDMPM.
+
+When both '--rule' and '--file' arguments are used, '--rule' records will be placed higher in resulting extended ACL table.
+
+
+```
+neofs-cli acl extended create [flags]
+```
+
+### Examples
+
+```
+neofs-cli acl extended create --cid EutHBsdT1YCzHxjCfQHnLPL1vFrkSyLSio4vkphfnEk -f rules.txt --out table.json
+neofs-cli acl extended create --cid EutHBsdT1YCzHxjCfQHnLPL1vFrkSyLSio4vkphfnEk -r 'allow get obj:Key=Value others' -r 'deny put others' -r 'deny put obj:$Object:payloadLength<4096 others' -r 'deny get obj:Quality>=100 others'
+```
+
+### Options
+
+```
+      --cid string         Container ID.
+  -f, --file string        Read list of extended ACL table records from text file
+  -h, --help               help for create
+  -o, --out string         Save JSON formatted extended ACL table in file
+  -r, --rule stringArray   Extended ACL table record to apply
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli acl extended](neofs-cli_acl_extended.md)	 - Operations with Extended Access Control Lists
+

docs/cli-commands/neofs-cli_acl_extended_print.md

@@ -0,0 +1,26 @@
+## neofs-cli acl extended print
+
+Pretty print extended ACL from the file(in text or json format) or for given container.
+
+```
+neofs-cli acl extended print [flags]
+```
+
+### Options
+
+```
+  -f, --file string   Read list of extended ACL table records from text or json file
+  -h, --help          help for print
+```
+
+### Options inherited from parent commands
+
+```
+  -c, --config string   Config file (default is $HOME/.config/neofs-cli/config.yaml)
+  -v, --verbose         Verbose output
+```
+
+### SEE ALSO
+
+* [neofs-cli acl extended](neofs-cli_acl_extended.md)	 - Operations with Extended Access Control Lists
+