Skip to content

Commit 392d476

Browse files
committed
docs, Makefile: add docs about all cli commands
Generate docs with `neofs-cli gendoc ./docs/cli-commands -d`. Add Makefile target for generation docs. Closes #1413. Signed-off-by: Andrey Butusov <[email protected]>
1 parent 22ad74a commit 392d476

File tree

76 files changed

+2582
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

76 files changed

+2582
-0
lines changed

CHANGELOG.md

+1
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,7 @@ attribute, which is used for container domain name in NNS contracts (#2954)
1616
- `neofs-lens fstree cleanup-tmp` command (#2967)
1717
- `neofs-cli control object revive` command (#2968)
1818
- `--disable-auto-gen-tag` flag for gendoc command (#2983)
19+
- Docs files for cli commands to the `docs/cli-commands` folder (#2983)
1920

2021
### Fixed
2122
- Do not search for tombstones when handling their expiration, use local indexes instead (#2929)

Makefile

+4
Original file line numberDiff line numberDiff line change
@@ -135,6 +135,10 @@ test:
135135
lint: .golangci.yml
136136
@golangci-lint --timeout=5m run
137137

138+
cli-gendoc: $(BIN)/neofs-cli
139+
@echo "⇒ Generating CLI commands documentation"
140+
@$< gendoc ./docs/cli-commands -d
141+
138142
# Run linters in Docker
139143
docker/lint:
140144
docker run --rm -t \

README.md

+2
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ have additional documents describing them:
9191
* [Extended headers](docs/cli-xheaders.md)
9292
* [Exit codes](docs/cli-exit-codes.md)
9393

94+
See [docs/cli-commands](docs/cli-commands) for information about all cli commands.
95+
9496
`neofs-adm` is a network setup and management utility usually used by the
9597
network administrators. Refer to [docs/cli-adm.md](docs/cli-adm.md) for mode
9698
information about it.

docs/cli-commands/neofs-cli.md

+42
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
## neofs-cli
2+
3+
Command Line Tool to work with NeoFS
4+
5+
### Synopsis
6+
7+
NeoFS CLI provides all basic interactions with NeoFS and it's services.
8+
9+
It contains commands for interaction with NeoFS nodes using different versions
10+
of neofs-api and some useful utilities for compiling ACL rules from JSON
11+
notation, managing container access through protocol gates, querying network map
12+
and much more!
13+
14+
```
15+
neofs-cli [flags]
16+
```
17+
18+
### Options
19+
20+
```
21+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
22+
-h, --help help for neofs-cli
23+
-v, --verbose Verbose output
24+
--version Application version and NeoFS API compatibility
25+
```
26+
27+
### SEE ALSO
28+
29+
* [neofs-cli accounting](neofs-cli_accounting.md) - Operations with accounts and balances
30+
* [neofs-cli acl](neofs-cli_acl.md) - Operations with Access Control Lists
31+
* [neofs-cli bearer](neofs-cli_bearer.md) - Operations with bearer token
32+
* [neofs-cli completion](neofs-cli_completion.md) - Generate completion script
33+
* [neofs-cli container](neofs-cli_container.md) - Operations with containers
34+
* [neofs-cli control](neofs-cli_control.md) - Operations with storage node
35+
* [neofs-cli gendoc](neofs-cli_gendoc.md) - Generate documentation for this command
36+
* [neofs-cli netmap](neofs-cli_netmap.md) - Operations with Network Map
37+
* [neofs-cli object](neofs-cli_object.md) - Operations with Objects
38+
* [neofs-cli session](neofs-cli_session.md) - Operations with session token
39+
* [neofs-cli storagegroup](neofs-cli_storagegroup.md) - Operations with Storage Groups
40+
* [neofs-cli tree](neofs-cli_tree.md) - Operations with the Tree service
41+
* [neofs-cli util](neofs-cli_util.md) - Utility operations
42+
+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## neofs-cli accounting
2+
3+
Operations with accounts and balances
4+
5+
### Synopsis
6+
7+
Operations with accounts and balances
8+
9+
### Options
10+
11+
```
12+
-h, --help help for accounting
13+
```
14+
15+
### Options inherited from parent commands
16+
17+
```
18+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
19+
-v, --verbose Verbose output
20+
```
21+
22+
### SEE ALSO
23+
24+
* [neofs-cli](neofs-cli.md) - Command Line Tool to work with NeoFS
25+
* [neofs-cli accounting balance](neofs-cli_accounting_balance.md) - Get internal balance of NeoFS account
26+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
## neofs-cli accounting balance
2+
3+
Get internal balance of NeoFS account
4+
5+
### Synopsis
6+
7+
Get internal balance of NeoFS account
8+
9+
```
10+
neofs-cli accounting balance [flags]
11+
```
12+
13+
### Options
14+
15+
```
16+
--address string Address of wallet account
17+
-h, --help help for balance
18+
--owner string owner of balance account (omit to use owner from private key)
19+
-r, --rpc-endpoint string Remote node address (as 'multiaddr' or '<host>:<port>')
20+
-w, --wallet string Path to the wallet
21+
```
22+
23+
### Options inherited from parent commands
24+
25+
```
26+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
27+
-v, --verbose Verbose output
28+
```
29+
30+
### SEE ALSO
31+
32+
* [neofs-cli accounting](neofs-cli_accounting.md) - Operations with accounts and balances
33+

docs/cli-commands/neofs-cli_acl.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## neofs-cli acl
2+
3+
Operations with Access Control Lists
4+
5+
### Options
6+
7+
```
8+
-h, --help help for acl
9+
```
10+
11+
### Options inherited from parent commands
12+
13+
```
14+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
15+
-v, --verbose Verbose output
16+
```
17+
18+
### SEE ALSO
19+
20+
* [neofs-cli](neofs-cli.md) - Command Line Tool to work with NeoFS
21+
* [neofs-cli acl basic](neofs-cli_acl_basic.md) - Operations with Basic Access Control Lists
22+
* [neofs-cli acl extended](neofs-cli_acl_extended.md) - Operations with Extended Access Control Lists
23+
+22
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
## neofs-cli acl basic
2+
3+
Operations with Basic Access Control Lists
4+
5+
### Options
6+
7+
```
8+
-h, --help help for basic
9+
```
10+
11+
### Options inherited from parent commands
12+
13+
```
14+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
15+
-v, --verbose Verbose output
16+
```
17+
18+
### SEE ALSO
19+
20+
* [neofs-cli acl](neofs-cli_acl.md) - Operations with Access Control Lists
21+
* [neofs-cli acl basic print](neofs-cli_acl_basic_print.md) - Pretty print basic ACL from the HEX representation
22+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
## neofs-cli acl basic print
2+
3+
Pretty print basic ACL from the HEX representation
4+
5+
### Synopsis
6+
7+
Pretty print basic ACL from the HEX representation or keyword.
8+
Few roles have exclusive default access to set of operation, even if particular bit deny it.
9+
Container have access to the operations of the data replication mechanism:
10+
Get, Head, Put, Search, Hash.
11+
InnerRing members are allowed to data audit ops only:
12+
Get, Head, Hash, Search.
13+
14+
```
15+
neofs-cli acl basic print [flags]
16+
```
17+
18+
### Examples
19+
20+
```
21+
neofs-cli acl basic print 0x1C8C8CCC
22+
```
23+
24+
### Options
25+
26+
```
27+
-h, --help help for print
28+
```
29+
30+
### Options inherited from parent commands
31+
32+
```
33+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
34+
-v, --verbose Verbose output
35+
```
36+
37+
### SEE ALSO
38+
39+
* [neofs-cli acl basic](neofs-cli_acl_basic.md) - Operations with Basic Access Control Lists
40+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## neofs-cli acl extended
2+
3+
Operations with Extended Access Control Lists
4+
5+
### Options
6+
7+
```
8+
-h, --help help for extended
9+
```
10+
11+
### Options inherited from parent commands
12+
13+
```
14+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
15+
-v, --verbose Verbose output
16+
```
17+
18+
### SEE ALSO
19+
20+
* [neofs-cli acl](neofs-cli_acl.md) - Operations with Access Control Lists
21+
* [neofs-cli acl extended create](neofs-cli_acl_extended_create.md) - Create extended ACL from the text representation
22+
* [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.
23+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
## neofs-cli acl extended create
2+
3+
Create extended ACL from the text representation
4+
5+
### Synopsis
6+
7+
Create extended ACL from the text representation.
8+
9+
Rule consist of these blocks: <action> <operation> [<filter1> ...] [<target1> ...]
10+
11+
Action is 'allow' or 'deny'.
12+
13+
Operation is an object service verb: 'get', 'head', 'put', 'search', 'delete', 'getrange', or 'getrangehash'.
14+
15+
Filter consists of <typ>:<key><match><value>
16+
Typ is 'obj' for object applied filter or 'req' for request applied filter.
17+
Key is a valid unicode string corresponding to object or request header key.
18+
Well-known system object headers start with '$Object:' prefix.
19+
User defined headers start without prefix.
20+
Read more about filter keys at github.com/nspcc-dev/neofs-api/blob/master/proto-docs/acl.md#message-eaclrecordfilter
21+
Match is:
22+
'=' for string equality or, if no value, attribute absence;
23+
'!=' for string inequality;
24+
'>' | '>=' | '<' | '<=' for integer comparison.
25+
Value is a valid unicode string corresponding to object or request header value. Numeric filters must have base-10 integer values.
26+
27+
Target is
28+
'user' for container owner,
29+
'system' for Storage nodes in container and Inner Ring nodes,
30+
'others' for all other request senders,
31+
'pubkey:<key1>,<key2>,...' for exact request sender, where <key> is a hex-encoded 33-byte public key, DEPRECATED,
32+
'address:<adr1>,<adr2>,...' for exact request sender, where <adr> is a base58 25-byte address. Example: NSiVJYZej4XsxG5CUpdwn7VRQk8iiiDMPM.
33+
34+
When both '--rule' and '--file' arguments are used, '--rule' records will be placed higher in resulting extended ACL table.
35+
36+
37+
```
38+
neofs-cli acl extended create [flags]
39+
```
40+
41+
### Examples
42+
43+
```
44+
neofs-cli acl extended create --cid EutHBsdT1YCzHxjCfQHnLPL1vFrkSyLSio4vkphfnEk -f rules.txt --out table.json
45+
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'
46+
```
47+
48+
### Options
49+
50+
```
51+
--cid string Container ID.
52+
-f, --file string Read list of extended ACL table records from text file
53+
-h, --help help for create
54+
-o, --out string Save JSON formatted extended ACL table in file
55+
-r, --rule stringArray Extended ACL table record to apply
56+
```
57+
58+
### Options inherited from parent commands
59+
60+
```
61+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
62+
-v, --verbose Verbose output
63+
```
64+
65+
### SEE ALSO
66+
67+
* [neofs-cli acl extended](neofs-cli_acl_extended.md) - Operations with Extended Access Control Lists
68+
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
## neofs-cli acl extended print
2+
3+
Pretty print extended ACL from the file(in text or json format) or for given container.
4+
5+
```
6+
neofs-cli acl extended print [flags]
7+
```
8+
9+
### Options
10+
11+
```
12+
-f, --file string Read list of extended ACL table records from text or json file
13+
-h, --help help for print
14+
```
15+
16+
### Options inherited from parent commands
17+
18+
```
19+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
20+
-v, --verbose Verbose output
21+
```
22+
23+
### SEE ALSO
24+
25+
* [neofs-cli acl extended](neofs-cli_acl_extended.md) - Operations with Extended Access Control Lists
26+

docs/cli-commands/neofs-cli_bearer.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
## neofs-cli bearer
2+
3+
Operations with bearer token
4+
5+
### Options
6+
7+
```
8+
-h, --help help for bearer
9+
```
10+
11+
### Options inherited from parent commands
12+
13+
```
14+
-c, --config string Config file (default is $HOME/.config/neofs-cli/config.yaml)
15+
-v, --verbose Verbose output
16+
```
17+
18+
### SEE ALSO
19+
20+
* [neofs-cli](neofs-cli.md) - Command Line Tool to work with NeoFS
21+
* [neofs-cli bearer create](neofs-cli_bearer_create.md) - Create bearer token
22+
* [neofs-cli bearer print](neofs-cli_bearer_print.md) - Print binary-marshalled bearer tokens from file or STDIN in JSON format
23+

0 commit comments

Comments
 (0)