fix(docs): fixed cli usage docs

docs/tools/tools-cli.rst

@@ -1,578 +1,582
 .. _tools-cli:
 
 |RCT| CLI
 ---------
 
 The commands available with |RCT| can be split into three categories:
 
 - Remotely executable commands that can be run from your local machine once you
   have your connection details to |RCE| configured.
 - Locally executable commands the can be run on the server to carry out
   general maintenance.
 - Local configuration commands used to help set up your |RCT| configuration.
 
 
+.. _tools-rhodecode-list-instance:
+
+rhodecode-list-instances
+------------------------
+
+Use this command to list the instance details configured in the
+:file:`/etc/rhodecode/conf/.rhoderc` file.
+
+.. code-block:: bash
+
+   $ ./rcstack cli cmd rhodecode-list-instances --config=/etc/rhodecode/conf/.rhoderc
+   [instance:production] - Config only
+   API-HOST: https://some.url.com
+   API-KEY:  some.auth.token
+
+   [instance:development] - Config only
+   API-HOST: http://some.ip.address
+   API-KEY:  some.auth.token
+
+
 rhodecode-tools
 ---------------
 
 Use |RCT| to setup automation, run the indexer, and install extensions for
 your |RCE| instances. Options:
 
 .. rst-class:: dl-horizontal
 
     \ - -apihost <api_host>
         Set the API host value.
 
     \ - -apikey <apikey_value>
         Set the API key value.
 
     \-c, - -config <config_file>
         Create a configuration file. The default file is created
         in ``~/.rhoderc``
 
     \ - -save-config
         Save the configuration file.
 
     \ - -show-config
         Show the current configuration values.
 
     \ - -format {json,pretty}
         Set the formatted representation.
 
 Example usage:
 
 .. code-block:: bash
 
    $ rhodecode-tools --apikey=key --apihost=http://rhodecode.server \
        --save-config
 
 rhodecode-api
 -------------
 
 The RhodeCode API lets you connect to |RCE| and carry out management tasks from a
 remote machine, for more information about the API, see the :ref:`api`. To
 pass arguments on the command-line use the ``method:option`` syntax.
 
 Example usage:
 
 .. code-block:: bash
 
     # Run the get_repos API call and sample output
     $ rhodecode-api --instance-name=enterprise-1 create_repo \
         repo_name:brand-new repo_type:hg description:repo-desc
 
     {
       "error": null,
       "id": 1110,
       "result": {
         "msg": "Created new repository `brand-new`",
         "success": true,
         "task": null
       }
     }
 
 Options:
 
 .. rst-class:: dl-horizontal
 
     \ - -api-cache-only
         Requires a cache to be present when running this call
 
     \ - -api-cache-rebuild
         Replaces existing cached values with new ones from server
 
     \ - -api-cache <PATH>
         Use a special cache dir to read responses from instead of the server
 
     \ - -api-cert-verify
          Verify the endpoint ssl certificate
 
     \ - -api-cert <PATH>
          Path to alternate CA bundle.
 
     \ - -apihost <api_host>
         Set the API host value.
 
     \ - -apikey <apikey_value>
         Set the API key value.
 
     \ - -instance-name <instance-id>
         Set the instance name
 
     \-I, - -install-dir <DIR>
         Location of application instances
 
     \-c, - -config <.rhoderc-file>
         Location of the :file:`.rhoderc`
 
     \-F, - -format {json,pretty}
         Set the formatted representation.
 
     \-h, - -help
         Show help messages.
 
     \-v, - -verbose
         Enable verbose messaging
 
 rhodecode-cleanup-gists
 -----------------------
 
 Use this to delete gists within |RCE|. Options:
 
 .. rst-class:: dl-horizontal
 
     \-c, - -config <config_file>
         Set the file path to the configuration file. The default file is
         :file:`/home/{user}/.rhoderc`
 
     \ - -corrupted
         Remove gists with corrupted metadata.
 
     \ - -dont-ask
         Remove gists without asking for confirmation.
 
     \-h, - -help
         Show help messages. current configuration values.
 
     \ - -instance-name <instance-id>
         Set the instance name.
 
     \-R, - -repo-dir
         Set the repository file path.
 
     \ - -version
         Display your |RCT| version.
 
 Example usage:
 
 .. code-block:: bash
 
     # Clean up gists related to an instance
     $ rhodecode-cleanup-gists --instance-name=enterprise-1
     Scanning for gists in /home/brian/repos/.rc_gist_store...
     preparing to remove [3] found gists
 
     # Clean up corrupted gists in an instance
     $ rhodecode-cleanup-gists --instance-name=enterprise-1 --corrupted
     Scanning for gists in /home/brian/repos/.rc_gist_store...
     preparing to remove [2] found gists
     the following gists will be archived:
       * EXPIRED: BAD METADATA        | /home/brian/repos/.rc_gist_store/5
       * EXPIRED: BAD METADATA        | /home/brian/repos/.rc_gist_store/8FtC
     are you sure you want to archive them? [y/N]: y
     removing gist /home/brian/repos/.rc_gist_store/5
     removing gist /home/brian/repos/.rc_gist_store/8FtCKdcbRKmEvRzTVsEt
 
+
 rhodecode-cleanup-repos
 -----------------------
 
 Use this to manage |repos| and |repo| groups within |RCE|. Options:
 
 .. rst-class:: dl-horizontal
 
     \-c, - -config <config_file>
         Set the file path to the configuration file. The default file is
         :file:`/home/{user}/.rhoderc`.
 
     \-h, - -help
         Show help messages. current configuration values.
 
     \ - -interactive
         Enable an interactive prompt for each repository when deleting.
 
     \ - -include-groups
         Remove repository groups.
 
     \ - -instance-name <instance-id>
         Set the instance name.
 
     \ - -list-only
         Display repositories selected for deletion.
 
     \ - -older-than <str>
         Delete repositories older that a specified time.
         You can use the following suffixes; d for days, h for hours,
         m for minutes, s for seconds.
 
     \-R, - -repo-dir
         Set the repository file path
 
 Example usage:
 
 .. code-block:: bash
 
-    # Cleaning up repos using tools installed with RCE 350 and above
-    $ ~/.rccontrol/enterprise-4/profile/bin/rhodecode-cleanup-repos \
-        --instance-name=enterprise-4 --older-than=1d
-    Scanning for repositories in /home/brian/repos...
-    preparing to remove [2] found repositories older than 1 day, 0:00:00 (1d)
+
+    # create a .rhoderc file in your host config directory (in :file:`config/_shared/.rhoderc`):
+
+    [instance:rcstack-instance]
+    api_host = http://rhodecode:10020
+    api_key = <API_KEY>
+    repo_dir = /var/opt/rhodecode_repo_store
+
+    # Run rcstack cli
+    ./rcstack cli cmd rhodecode-cleanup-repos --instance-name=rcstack-instance --config=/etc/rhodecode/conf/.rhoderc
+
+    checking if config files needs bootstrapping
+    Scanning for repositories in /var/opt/rhodecode_repo_store...
 
     the following repositories will be deleted completely:
-    * REMOVED: 2015-08-05 00:23:18 | /home/brian/repos/rm__20150805_002318_831
-    * REMOVED: 2015-08-04 01:22:10 | /home/brian/repos/rm__20150804_012210_336
+    * REMOVED: 2015-08-05 00:23:18 | /var/opt/rhodecode_repo_store/rm__20150805_002318_831
+    * REMOVED: 2015-08-04 01:22:10 | /var/opt/rhodecode_repo_store/rm__20150804_012210_336
     are you sure you want to remove them? [y/N]:
 
     # Clean up repos older than 1 year
-    # If using virtualenv and pre RCE 350 tools installation
-    (venv)$ rhodecode-cleanup-repos --instance-name=enterprise-1 \
-        --older-than=365d
+    ./rcstack cli cmd rhodecode-cleanup-repos --instance-name=rcstack-instance --config=/etc/rhodecode/conf/.rhoderc --older-than=365d
 
-    Scanning for repositories in /home/brian/repos...
+    checking if config files needs bootstrapping
+    Scanning for repositories in /var/opt/rhodecode_repo_store...
     preparing to remove [343] found repositories older than 365 days
 
     # clean up repos older than 3 days
-    # If using virtualenv and pre RCE 350 tools installation
-    (venv)$ rhodecode-cleanup-repos --instance-name=enterprise-1 \
-        --older-than=3d
-    Scanning for repositories in /home/brian/repos...
+    ./rcstack cli cmd rhodecode-cleanup-repos --instance-name=rcstack-instance --config=/etc/rhodecode/conf/.rhoderc --older-than=3d
+
+    checking if config files needs bootstrapping
+    Scanning for repositories in /var/opt/rhodecode_repo_store...
     preparing to remove [3] found repositories older than 3 days
 
 .. _tools-config:
 
 rhodecode-config
 ----------------
 
 Use this to create or update a |RCE| configuration file on the local machine.
 
 .. rst-class:: dl-horizontal
 
     \- -filename </path/to/config_file>
         Set the file path to the |RCE| configuration file.
 
     \- -show-defaults
         Display the defaults set in the |RCE| configuration file.
 
     \- -update
         Update the configuration with the new settings passed on the command
         line.
 
 .. code-block:: bash
 
     # Create a new config file
     $ rhodecode-config --filename=dev.ini
     Wrote new config file in /Users/user/dev.ini
 
     # Update config value for given section:
     $ rhodecode-config --update --filename=prod.ini [handler_console]level=INFO
 
     $ rhodecode-config --filename=dev.ini --show-defaults
     lang=en
     cpu_number=4
     uuid=<function <lambda> at 0x10d86ac08>
     license_token=ff1e-aa9c-bb66-11e5
     host=127.0.0.1
     here=/Users/brian
     error_aggregation_service=None
     database_url=sqlite:///%(here)s/rhodecode.db?timeout=30
     git_path=git
     http_server=waitress
     port=5000
 
 .. _tools-rhodecode-extensions:
 
 rhodecode-extensions
 --------------------
 
 The `rcextensions` since version 4.14 are now shipped together with |RCE| please check
 the using :ref:`integrations-rcextensions` section.
 
 
 rhodecode-gist
 --------------
 
 Use this to create, list, show, or delete gists within |RCE|. Options:
 
 .. rst-class:: dl-horizontal
 
     \ - -api-cache-only
         Requires a cache to be present when running this call
 
     \ - -api-cache-rebuild
         Replaces existing cached values with new ones from server
 
     \ - -api-cache PATH
         Use a special cache dir to read responses from instead of the server
 
     \ - -api-cert-verify
          Verify the endpoint ssl certificate
 
     \ - -api-cert PATH
          Path to alternate CA bundle.
 
     \ - -apihost <api_host>
         Set the API host value.
 
     \ - -apikey <apikey_value>
         Set the API key value.
 
     \-c, - -config <config_file>
         Create a configuration file.
         The default file is created in :file:`~/.rhoderc`
 
     \ - -create <gistname>
         create the gist
 
     \-d, - -description <str>
         Set gist description
 
     \ - -delete <gistid>
         Delete the gist
 
     \-f, - -file
         Specify the filename The file extension will enable syntax highlighting.
 
     \-F, - -format {json,pretty}
         Set the formatted representation.
 
     \ - -help
         Show help messages.
 
     \-I, - -install-dir <DIR>
         Location of application instances
 
     \ - -instance-name <instance-id>
         Set the instance name.
 
     \ - -list
         Display instance gists.
 
     \-l, --lifetime <minutes>
         Set the gist lifetime. The default value is (-1) forever
 
     \ - -show <gistname>
         Show the content of the gist
 
     \-o, - -open
         After creating Gist open it in browser
 
     \-p, - -private
         Create a private gist
 
     \ - -version
          Display your |RCT| version.
 
 Example usage:
 
 .. code-block:: bash
 
     # List the gists in an instance
     (venv)brian@ubuntu:~$ rhodecode-gist --instance-name=enterprise-1 list
     {
       "error": null,
       "id": 7102,
       "result": [
         {
           "access_id": "2",
           "content": null,
           "created_on": "2015-01-19T12:52:26.494",
           "description": "A public gust",
           "expires": -1.0,
           "gist_id": 2,
           "type": "public",
           "url": "http://127.0.0.1:10003/_admin/gists/2"
         },
         {
           "access_id": "7gs6BsSEC4pKUEPLz5AB",
           "content": null,
           "created_on": "2015-01-19T11:27:40.812",
           "description": "Gist testing API",
           "expires": -1.0,
           "gist_id": 1,
           "type": "private",
           "url": "http://127.0.0.1:10003/_admin/gists/7gs6BsSEC4pKUEPLz5AB"
         }
       ]
     }
 
     # delete a particular gist
     # You use the access_id to specify the gist to delete
     (venv)brian@ubuntu:~$ rhodecode-gist delete 2  --instance-name=enterprise-1
     {
       "error": null,
       "id": 6284,
       "result": {
         "gist": null,
         "msg": "deleted gist ID:2"
       }
     }
 
     # cat a file and pipe to new gist
     # This is if you are using virtualenv
     (venv)$ cat ~/.rhoderc | rhodecode-gist --instance-name=enterprise-1 \
         -d '.rhoderc copy' create
 
     {
       "error": null,
       "id": 5374,
       "result": {
         "gist": {
           "access_id": "7",
           "content": null,
           "created_on": "2015-01-26T11:31:58.774",
           "description": ".rhoderc copy",
           "expires": -1.0,
           "gist_id": 7,
           "type": "public",
           "url": "http://127.0.0.1:10003/_admin/gists/7"
         },
         "msg": "created new gist"
       }
     }
 
     # Cat a file and pipe to gist
-    # in RCE 3.5.0 tools and above
-    $ cat ~/.rhoderc | ~/.rccontrol/{instance-id}/profile/bin/rhodecode-gist \
-       --instance-name=enterprise-4 -d '.rhoderc copy' create
+
+    $ cat ~/.rhoderc | ./rcstack cli cmd rhodecode-gist --instance-name=rcstack-instance --config=/etc/rhodecode/conf/.rhoderc -d '.rhoderc copy' create
     {
       "error": null,
       "id": 9253,
       "result": {
         "gist": {
           "access_id": "4",
           "acl_level": "acl_public",
           "content": null,
           "created_on": "2015-08-20T05:54:11.250",
           "description": ".rhoderc copy",
           "expires": -1.0,
           "gist_id": 4,
           "modified_at": "2015-08-20T05:54:11.250",
           "type": "public",
           "url": "http://127.0.0.1:10000/_admin/gists/4"
         },
         "msg": "created new gist"
       }
     }
 
 
 rhodecode-index
 ---------------
 
 More detailed information regarding setting up the indexer is available in
 the :ref:`indexing-ref` section. Options:
 
 .. rst-class:: dl-horizontal
 
     \ - -api-cache-only
         Requires a cache to be present when running this call
 
     \ - -api-cache-rebuild
         Replaces existing cached values with new ones from server
 
     \ - -api-cache PATH
         Use a special cache dir to read responses from instead of the server
 
     \ - -api-cert-verify
          Verify the endpoint ssl certificate
 
     \ - -api-cert PATH
          Path to alternate CA bundle.
 
     \ - -apihost <api_host>
         Set the API host value.
 
     \ - -apikey <apikey_value>
         Set the API key value.
 
     \-c, --config <config_file>
         Create a configuration file.
         The default file is created in :file:`~/.rhoderc`
 
     \ - -create-mapping <PATH>
          Creates an example mapping configuration for indexer.
 
     \-F, - -format {json,pretty}
          Set the formatted representation.
 
     \-h, - -help
          Show help messages.
 
     \ - -instance-name <instance-id>
         Set the instance name
 
     \-I, - -install-dir <DIR>
         Location of application instances
 
     \-m, - -mapping <file_name>
          Parse the output to the .ini mapping file.
 
     \ - -optimize
          Optimize index for performance by amalgamating multiple index files
          into one. Greatly increases incremental indexing speed.
 
     \-R, - -repo-dir <DIRECTORY>
          Location of repositories
 
     \ - -source <PATH>
          Use a special source JSON file to feed the indexer
 
     \ - -version
          Display your |RCT| version.
 
 Example usage:
 
 .. code-block:: bash
 
-    # Run the indexer
-    $ ~/.rccontrol/enterprise-4/profile/bin/rhodecode-index \
-        --instance-name=enterprise-4
+    # Create the indexing mapping file
+    $ ./rcstack cli cmd rhodecode-index --instance-name=rcstack-instance --config=/etc/rhodecode/conf/.rhoderc --create-mapping search_mapping.ini
 
-    # Run indexer based on search_mapping.ini file
-    # This is using pre-350 virtualenv
-    (venv)$ rhodecode-index --instance-name=enterprise-1
+    # Run the indexer
+    $ ./rcstack cli cmd rhodecode-index --instance-name=rcstack-instance --config=/etc/rhodecode/conf/.rhoderc
+
+    # Run indexer based on search_mapping.ini file using rhodecode-tools virtualenv
+    (venv)$ rhodecode-index --instance-name=rcstack-instance
 
     # Index from the command line without creating
     # the .rhoderc file
-    $ rhodecode-index --apikey=key --apihost=http://rhodecode.server \
-        --instance-name=enterprise-2 --save-config
-
-    # Create the indexing mapping file
-    $ ~/.rccontrol/enterprise-4/profile/bin/rhodecode-index \
-        --create-mapping search_mapping.ini --instance-name=enterprise-4
-
-.. _tools-rhodecode-list-instance:
-
-rhodecode-list-instances
-------------------------
-
-Use this command to list the instance details configured in the
-:file:`~/.rhoderc` file.
-
-.. code-block:: bash
-
-   $ .rccontrol/enterprise-1/profile/bin/rhodecode-list-instances
-   [instance:production] - Config only
-   API-HOST: https://some.url.com
-   API-KEY:  some.auth.token
-
-   [instance:development] - Config only
-   API-HOST: http://some.ip.address
-   API-KEY:  some.auth.token
+    $ rhodecode-index --apikey=key --apihost=http://rhodecode.server --instance-name=rcstack-instance --save-config
 
 
 .. _tools-setup-config:
 
 rhodecode-setup-config
 ----------------------
 
 Use this command to create the ``~.rhoderc`` file required by |RCT| to access
 remote instances.
 
 .. rst-class:: dl-horizontal
 
     \- -instance-name <name>
         Specify the instance name in the :file:`~/.rhoderc`
 
     \api_host <hostname>
         Create a configuration file. The default file is created
         in ``~/.rhoderc``
 
     \api_key <auth-token>
         Create a configuration file. The default file is created
         in ``~/.rhoderc``
 
 
 .. code-block:: bash
 
     (venv)$ rhodecode-setup-config --instance-name=tea api_host=URL api_key=xyz
     Config not found under /Users/username/.rhoderc, creating a new one
     Wrote new configuration into /Users/username/.rhoderc