[docs] updated docs

Signed-off-by: Alberto Ricart <[email protected]>
nats-io · Jan 2, 2025 · a50fef9 · a50fef9
1 parent e267e48
commit a50fef9
Show file tree

Hide file tree

Showing 81 changed files with 834 additions and 383 deletions.
diff --git a/Makefile b/Makefile
@@ -28,6 +28,9 @@ install: compile build
 cover: test
 	go tool cover -html=./coverage.out
 
+doc:
+	go run ./ test doc docs
+
 # The NSC_*_OPERATOR unset is because those variables pre-define operators which break the interactive tests
 test:
 	go mod vendor

diff --git a/docs/nsc.md b/docs/nsc.md
@@ -2,13 +2,14 @@
 
 nsc creates NATS operators, accounts, users, and manage their permissions.
 
-### Synopsis
-
-nsc creates NATS operators, accounts, users, and manage their permissions.
+```
+nsc [flags]
+```
 
 ### Options
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -h, --help                  help for nsc
@@ -17,27 +18,32 @@ nsc creates NATS operators, accounts, users, and manage their permissions.
   -K, --private-key string    Key used to sign. Can be specified as role (where applicable),
                               public key (private portion is retrieved)
                               or file path to a private key or private key 
+  -v, --version               version for nsc
 ```
 
 ### SEE ALSO
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
+* [nsc completion](nsc_completion.md)	 - Generate the autocompletion script for the specified shell
 * [nsc delete](nsc_delete.md)	 - Delete imports and exports
 * [nsc describe](nsc_describe.md)	 - Describe assets such as operators, accounts, users, and jwt files
 * [nsc edit](nsc_edit.md)	 - Edit assets such as accounts, imports, and users
 * [nsc env](nsc_env.md)	 - Prints and manage the nsc environment
+* [nsc expirations](nsc_expirations.md)	 - Create a new expiration report
 * [nsc export](nsc_export.md)	 - Export assets such as nkeys
 * [nsc generate](nsc_generate.md)	 - Generate activations, creds, configs or nkeys
 * [nsc import](nsc_import.md)	 - Import assets such as nkeys
 * [nsc init](nsc_init.md)	 - Initialize an environment by creating an operator, account and user
 * [nsc keys](nsc_keys.md)	 - Manage keys for operators, accounts, and users
 * [nsc list](nsc_list.md)	 - List assets such as accounts, imports, users
+* [nsc load](nsc_load.md)	 - install entities for an operator, account and key
 * [nsc pull](nsc_pull.md)	 - Pull an operator or account jwt replacing the local jwt with the server's version
 * [nsc push](nsc_push.md)	 - Push an account jwt to an Account JWT Server
 * [nsc reissue](nsc_reissue.md)	 - Re-issue objects with a new identity key
 * [nsc revocations](nsc_revocations.md)	 - Manage revocation for users and activations from an account
+* [nsc select](nsc_select.md)	 - Set the current operator or account
 * [nsc tool](nsc_tool.md)	 - NATS tools: pub, sub, req, rep, rtt
 * [nsc update](nsc_update.md)	 - Update this tool to latest version
 * [nsc validate](nsc_validate.md)	 - Validate an operator, account(s), and users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add.md b/docs/nsc_add.md
@@ -2,10 +2,6 @@
 
 Add assets such as accounts, imports, users
 
-### Synopsis
-
-Add assets such as accounts, imports, users
-
 ### Options
 
 ```
@@ -15,6 +11,7 @@ Add assets such as accounts, imports, users
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -34,4 +31,4 @@ Add assets such as accounts, imports, users
 * [nsc add operator](nsc_add_operator.md)	 - Add an operator
 * [nsc add user](nsc_add_user.md)	 - Add an user to the account
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add_account.md b/docs/nsc_add_account.md
@@ -2,10 +2,6 @@
 
 Add an account
 
-### Synopsis
-
-Add an account
-
 ```
 nsc add account [flags]
 ```
@@ -20,17 +16,18 @@ nsc add account [flags]
       --deny-pub strings             add deny publish default permissions - comma separated list or option can be specified multiple times
       --deny-pubsub strings          add deny publish and subscribe default permissions - comma separated list or option can be specified multiple times
       --deny-sub strings             add deny subscribe default permissions - comma separated list or option can be specified multiple times
-      --expiry string                valid until ('0' is always, '2M' is two months) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears) (default "0")
+      --expiry string                valid until ('0' is always, '2M' is two months) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears)
   -h, --help                         help for account
   -n, --name string                  account name
   -k, --public-key string            public key identifying the account
       --response-ttl string          the amount of time the default permissions is valid (global) - [#ms(millis) | #s(econds) | m(inutes) | h(ours)] - Default is no time limit.
-      --start string                 valid from ('0' is always, '3d' is three days) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears) (default "0")
+      --start string                 valid from ('0' is always, '3d' is three days) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears)
 ```
 
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -44,4 +41,4 @@ nsc add account [flags]
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add_export.md b/docs/nsc_add_export.md
@@ -2,10 +2,6 @@
 
 Add an export
 
-### Synopsis
-
-Add an export
-
 ```
 nsc add export [flags]
 ```
@@ -24,6 +20,7 @@ nsc add export --name myexport --subject a.b --service
 ```
   -a, --account string                account name
       --account-token-position uint   subject token position where account is expected (public exports only)
+      --allow-trace                   allow trace requests
   -h, --help                          help for export
       --latency string                latency metrics subject (services only)
   -n, --name string                   export name
@@ -38,6 +35,7 @@ nsc add export --name myexport --subject a.b --service
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -51,4 +49,4 @@ nsc add export --name myexport --subject a.b --service
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add_import.md b/docs/nsc_add_import.md
@@ -2,10 +2,6 @@
 
 Add an import
 
-### Synopsis
-
-Add an import
-
 ```
 nsc add import [flags]
 ```
@@ -23,6 +19,7 @@ nsc add import --src-account <account_pubkey> --remote-subject <remote-sub> --lo
 
 ```
   -a, --account string          account name
+      --allow-trace             allow trace requests
   -h, --help                    help for import
   -s, --local-subject string    local subject
   -n, --name string             import name
@@ -36,6 +33,7 @@ nsc add import --src-account <account_pubkey> --remote-subject <remote-sub> --lo
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -49,4 +47,4 @@ nsc add import --src-account <account_pubkey> --remote-subject <remote-sub> --lo
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add_mapping.md b/docs/nsc_add_mapping.md
@@ -2,10 +2,6 @@
 
 Add (or modify) a mapping entry
 
-### Synopsis
-
-Add (or modify) a mapping entry
-
 ```
 nsc add mapping [flags]
 ```
@@ -35,6 +31,7 @@ nsc add mapping --from "a" --to "c" --weight 50
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -48,4 +45,4 @@ nsc add mapping --from "a" --to "c" --weight 50
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add_operator.md b/docs/nsc_add_operator.md
@@ -2,30 +2,27 @@
 
 Add an operator
 
-### Synopsis
-
-Add an operator
-
 ```
 nsc add operator [flags]
 ```
 
 ### Options
 
 ```
-      --expiry string          valid until ('0' is always, '2M' is two months) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears) (default "0")
+      --expiry string          valid until ('0' is always, '2M' is two months) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears)
       --force                  on import, overwrite existing when already present
       --generate-signing-key   generate a signing key with the operator
   -h, --help                   help for operator
   -n, --name string            operator name
-      --start string           valid from ('0' is always, '3d' is three days) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears) (default "0")
+      --start string           valid from ('0' is always, '3d' is three days) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears)
   -s, --sys                    generate system account with the operator (if specified will be signed with signing key)
   -u, --url string             import from a jwt server url, file, or well known operator
 ```
 
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -39,4 +36,4 @@ nsc add operator [flags]
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_add_user.md b/docs/nsc_add_user.md
@@ -2,10 +2,6 @@
 
 Add an user to the account
 
-### Synopsis
-
-Add an user to the account
-
 ```
 nsc add user [flags]
 ```
@@ -58,19 +54,20 @@ nsc add user --name <n> --allow-pub-response=5
       --deny-pub strings             add deny publish permissions - comma separated list or option can be specified multiple times
       --deny-pubsub strings          add deny publish and subscribe permissions - comma separated list or option can be specified multiple times
       --deny-sub strings             add deny subscribe permissions - comma separated list or option can be specified multiple times
-      --expiry string                valid until ('0' is always, '2M' is two months) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears) (default "0")
+      --expiry string                valid until ('0' is always, '2M' is two months) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears)
   -h, --help                         help for user
   -n, --name string                  name to assign the user
   -k, --public-key string            public key identifying the user
       --response-ttl string          the amount of time the permissions is valid (global) - [#ms(millis) | #s(econds) | m(inutes) | h(ours)] - Default is no time limit.
       --source-network strings       source network for connection - comma separated list or option can be specified multiple times
-      --start string                 valid from ('0' is always, '3d' is three days) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears) (default "0")
+      --start string                 valid from ('0' is always, '3d' is three days) - yyyy-mm-dd, #m(inutes), #h(ours), #d(ays), #w(eeks), #M(onths), #y(ears)
       --tag strings                  tags for user - comma separated list or option can be specified multiple times
 ```
 
 ### Options inherited from parent commands
 
 ```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
       --config-dir string     nsc config directory
       --data-dir string       nsc data store directory
   -i, --interactive           ask questions for various settings
@@ -84,4 +81,4 @@ nsc add user --name <n> --allow-pub-response=5
 
 * [nsc add](nsc_add.md)	 - Add assets such as accounts, imports, users
 
-###### Auto generated by spf13/cobra on 25-Feb-2022
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_completion.md b/docs/nsc_completion.md
@@ -0,0 +1,38 @@
+## nsc completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for nsc for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
+      --config-dir string     nsc config directory
+      --data-dir string       nsc data store directory
+  -i, --interactive           ask questions for various settings
+      --keystore-dir string   nsc keystore directory
+  -K, --private-key string    Key used to sign. Can be specified as role (where applicable),
+                              public key (private portion is retrieved)
+                              or file path to a private key or private key 
+```
+
+### SEE ALSO
+
+* [nsc](nsc.md)	 - nsc creates NATS operators, accounts, users, and manage their permissions.
+* [nsc completion bash](nsc_completion_bash.md)	 - Generate the autocompletion script for bash
+* [nsc completion fish](nsc_completion_fish.md)	 - Generate the autocompletion script for fish
+* [nsc completion powershell](nsc_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [nsc completion zsh](nsc_completion_zsh.md)	 - Generate the autocompletion script for zsh
+
+###### Auto generated by spf13/cobra on 2-Jan-2025
diff --git a/docs/nsc_completion_bash.md b/docs/nsc_completion_bash.md
@@ -0,0 +1,57 @@
+## nsc completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(nsc completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	nsc completion bash > /etc/bash_completion.d/nsc
+
+#### macOS:
+
+	nsc completion bash > $(brew --prefix)/etc/bash_completion.d/nsc
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+nsc completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### Options inherited from parent commands
+
+```
+  -H, --all-dirs string       sets --config-dir, --data-dir, and --keystore-dir to the same value
+      --config-dir string     nsc config directory
+      --data-dir string       nsc data store directory
+  -i, --interactive           ask questions for various settings
+      --keystore-dir string   nsc keystore directory
+  -K, --private-key string    Key used to sign. Can be specified as role (where applicable),
+                              public key (private portion is retrieved)
+                              or file path to a private key or private key 
+```
+
+### SEE ALSO
+
+* [nsc completion](nsc_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 2-Jan-2025