~~ Licensed to the Apache Software Foundation (ASF) under one or more
~~ contributor license agreements.  See the NOTICE file distributed with
~~ this work for additional information regarding copyright ownership.
~~ The ASF licenses this file to You under the Apache License, Version 2.0
~~ (the "License"); you may not use this file except in compliance with
~~ the License.  You may obtain a copy of the License at
~~
~~     http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing, software
~~ distributed under the License is distributed on an "AS IS" BASIS,
~~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
~~ See the License for the specific language governing permissions and
~~ limitations under the License.
~~
Command Line Interface

  Ambari Client implements a convenient command line interface for
  administrators to manage the full life of Hadoop clusters. The CLI
  is a thin client, which is implemented using Ambari REST APIs. By
  design, there is a close mapping between CLI and REST APIs and the
  logic is implemented on by server.

  General syntax of the CLI command is as follows, 

  * Ambari commands are divided into multiple command categories
  typically named after the resources they operate on e.g. cluster,
  node, stack etc.

  * Each command starts with command category followed by one of the
  commands in that category, followed by one or more options available
  for the command e.g.

    * ambari \[command_category\] \[command_name\] \[command_options\]

  * Command options can follow in any order. Options are prefixed with "-". 

  * Each option would has at most one value associated with it. The value
  is either a string, e.g. -name "MyCluster", or a key=value pair,
  e.g. -role rolename="hostname1, hostname[10-20]"

  * Certain command options can be repeated multiple times on the
  command line, they are marked accordingly using the tag
  <<[REPEATABLE]>>.

  * All the required options are marked as <<[REQUIRED]>>

  * Generic commands do not have any category associated with them
    e.g. help, version

  []

  Ambari Commands

  * <<Cluster commands>>

    * ambari cluster \{create | update | list | get | delete | rename | stack | 
    nodes\}

  * <<Stack commands>>

    * ambari stack \{create | update | list | get | delete | history \}

  * <<Node commands>>

    * ambari nodes \{list | get\}

  * <<Configuration commands>>

    * ambari configure

    * ambari add-user

  * <<Server commands>>

    * ambari controller

    * ambari agent

  * <<Generic commands>>

    * ambari help

    * ambari version


Cluster Commands

  * <<ambari cluster  create>> 

    * Submit the cluster creation request to Ambari. It may take some
    time to bring the cluster to the desired state and hence the
    cluster state should be checked either via the <<list>> command or
    the <<-wait>> option should be used to wait for the cluster to
    reach the goal state.

    * <<Options:>>

      * <<-name>> [ NAME ] <<[REQUIRED]>>

      * <<-stack>> [ STACK NAME ]  <<[REQUIRED]>>

        * Name of the user defined stack defining cluster configuration

      * <<-stack_revision>> [ INTEGER ]

        * Revision of the stack. If not specified latest one is used.

      * <<-stack-file>> [ FILENAME]

        * Update the stack with the same name as the cluster using the
        given file and use the updated stack for creating the new
        cluster. This option is mutually exclusive with <<-stack>> and
        <<-stack_revision>>

      * <<-nodes>> [node_range_exp1, node_range_exp2]  <<[REQUIRED]>>

        * Specify range of nodes associated with the cluster. One or
        more node range expressions can be specified separated by
        commas. If the user does not bind roles to specific nodes
        using the <<-role>> option, Ambari will assign the roles to
        nodes based on the nodes' attributes. If user wants to view
        the role to nodes association generated by Ambari, use
        <<-dry_run>> option

      * <<-desc>> [ DESCRIPTION ]

        * Ambari will add default description

      * <<-goalstate>> [ACTIVE]

        * Default is INACTIVE

      * <<-components>> [component-1, component-2, component-3]

        * By default all the components will be activated upon cluster
        activation.  If user specifies specific ones then only those
        will be activated upon cluster activation

      * <<-role>>  rolename=[node_range_exp1, node_range_exp2, …] 
      <<[REPEATABLE]>>

        * One or more -role options can be used to specify the
        association of nodes to various roles. Nodes not explicitly
        associated with any role will be associated with various roles
        based on node attributes.

      * <<-dry_run>>

        * Execute the command without actually making the changes effective. 

      * <<-wait>>

        * Optionally wait for cluster to get to goal state. The progress of
        activating the cluster will be printed to the user.

  []

  * <<ambari cluster update>> 

    * It updates the cluster definition. All the options except name
    are OPTIONAL

    * <<Options:>>

      * <<-name>>  [ NAME ] <<[REQUIRED]>> 

      * <<-desc>>   [ DESCRIPTION ]

      * <<-stack>> [ STACK NAME ]   

      * <<-stack_revision>> [ INTEGER ]

        * Revision of the stack. If not specified latest one is used.

      * <<-stack-file>> [ FILENAME]

        * Update the stack with the same name as the cluster using the
        given file and use the updated stack in the updated
        cluster. This option is mutually exclusive with <<-stack>> and
        <<-stack_revision>>

      * <<-goalstate>> [ACTIVE/INACTIVE/ATTIC]

      * <<-components>> [component, component, component]    

        * Specify the list of desired active components that will be run
        when the cluster is active.

      * <<-nodes>>  [node_range_exp1, node_range_exp2]

        * Specify range of nodes associated with cluster. Ambari
        controller will figure out the changes and accordingly
        allocate/deallocate the nodes.

      * <<-role>>  rolename=[node_exp1, node_exp2, …]  <<[REPEATABLE]>>

        * Change the nodes associated with each role. The nodes will be
        re-deployed and re-configured appropriately. If nodes are not assigned
        to a role, Ambari will automatically assign them.

      * <<-dry-run>>

        * This will show the details of the changes being made to
        cluster definition without actually submitting them to Ambari
        controller

      * <<-wait>>

        * Wait for cluster to get to desired goal state. The progress of
        activating the cluster will be printed to the user.

  []

  * <<ambari cluster list>> 

    * List clusters. In a non-verbose mode, list cluster will return
    the list of cluster names.

    * <<Options:>>

      * <<-state>> [cluster_state]

        * Optionally specify the cluster state to list the cluster(s)
        in the specified state.

      * <<-verbose>>

        * This option will provide verbose cluster information, which includes
        the name, creating user, state, and current number of nodes.

  []

  * <<ambari cluster get>> 

    * Get the detailed cluster information displayed.

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

        * Name of the cluster

  []

  * <<ambari cluster delete>>

    * Delete the cluster. It deactivates the cluster. Controller in
    the background would free all the associated nodes and then remove
    the cluster definition at the end.

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>> 

      * <<-wait>>

        * Optionally wait for cluster to be deleted. The progress of deleting
        the cluster will be displayed to the user.

  []

  * <<ambari cluster rename>> 

    * Renames the cluster

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>> 

      * <<-newname>> [NEW NAME] <<[REQUIRED]>>

  []

  * <<ambari cluster stack>>

    * It displays the stack associated with the cluster. The
    <<-expand>> option provides the derived stack configuration as
    generated by recursively expanding the parent stack.

    * <<Options:>>

      * <<-name>> [CLUSTER_NAME] <<[REQUIRED]>>

        * Cluster name

      * <<-file>> [Local File Path]

        * Optionally stores the configuration to local file path. If
        not specified it displays it on the console.

      * <<-expand>>

        * Expand the stack by inline the parent stack into it.

  [] 

  * <<ambari cluster nodes>> 

    * List the nodes associated with specified cluster

    * <<Options:>>

      * <<-name>> [CLUSTER_NAME] <<[REQUIRED]>> 

        * Cluster name

      * <<-alive>> [true/false]

        * Only list the nodes that are alive (or dead). Alive nodes
        are ones regularly heart beating with Ambari controller. If
        this option is not specified then all nodes are returned.

      * <<-role>> [ROLE_NAME] 

        * Only list the nodes that are associated with the given role. If
        it is not given, all nodes are listed.

  []

Stack Commands

  * <<ambari stack create>> 

    * Add or update the stack. If stack exists, it will be
    updated to create new revision else new stack is created.
   

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

        * Name of the stack.

      * <<-location>> [FILE_PATH/URL] <<[REQUIRED]>>

        * Specify local file path or the URL from where stack (in
        XML format) is to be imported into Ambari

  []

  * <<ambari stack update>>

    * Update the stack. Only the properties set in file will be updated.

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

        * Name of the stack.

      * <<-location>> [FILE_PATH/URL] <<[REQUIRED]>>

        * Specify local file path or the URL from where stack (in
        XML format) is to be imported into Ambari

  []

  * <<ambari stack list>> 

    * List all the stacks. In non-verbose mode, just lists the stacks' names.

    * <<Options:>>

      * <<-name>> [STACK_NAME]

        * Optionally specify the stack name to list the specific one

      * <<-verbose>>

        * Lists the stack's name, current revision, parent stack, and the 
        date it was last modified.

      * <<-tree>>

        * Optionally ask for the derivation hierarchy

  [] 

  * <<ambari stack get>> 

    * Get the stack document in JSON format

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

      * <<-revision>> [NUMBER]

        * Optionally specify revision number else returns latest one

      * <<-file>> [Local File Path]

        * Optionally stores the configuration to local file path. If
        not specified it displays it on the console.

  []

  * <<ambari stack delete>> 

    * Delete the stack.

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

        * Name of the stack.

  []

  * <<ambari stack history>>

    * List all the revisions of a specified stack

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

        * Name of the stack.

      * <<-tree>>

        * Optionally ask for the derivation hierarchy

  []

Node Commands 

  * <<ambari node list>>

    * Lists the nodes being managed by Ambari. In non-verbose mode, just lists
    the full host names.

    * <<Options:>>

      * <<-verbose>>

        * Optionally verbose option will display the nodes' name, cluster, 
        current state, and roles.

      * <<-allocated>> [true/false]

        * Only include the nodes that allocated (or unallocated) to any
        cluster.  If not specified, both allocated and free nodes are
        included.

      * <<-alive>> [true/false]

        * Only include nodes that are alive (or dead). If not specified,
        implies both alive and dead nodes.

  []

  * <<ambari node get>>

    * All of the information about the node is displayed including the
    node name, machine attributes, node state, associated cluster,
    list of roles and the current state of the servers.

    * <<Options:>>

      * <<-name>> [NAME] <<[REQUIRED]>>

        * Node name

  []

Configuration Commands

  * <<ambari configure>>

    * Configures Ambari on this machine by re-writing the configuration file.

    * <<Options:>>

      * <<-agent-password>> [PASSWORD]

        * Set the password for the Ambari agent to authenticate to the 
          controller.

      * <<-controller>> [CONTROLLER URL]

        * Set the URL for the Ambari controller REST API.

  * <<ambari add-user>>

    * Add a new user as an Ambari administrator.

    * <<Options:>>

      * <<-user>> [USER NAME] [REQUIRED]

        * Add the given username to the database of authorized administrators.

      * <<-kerberos>>

        * The user should authenticate using Kerberos.

      * <<-password>> [PASSWORD]

        * The user should provide the given password when authenticating.

Server Commands

  * <<ambari controller>>

    * Start the Ambari controller on this machine

    * <<Options:>>

      * <<-autostart>> [BOOLEAN]

        * In addition to starting the server, update the system to
          (not) restart the controller when the system reboots.

  * <<ambari agent>>

    * Start the Ambari agent on this machine

    * <<Options:>>

      * <<-autostart>> [BOOLEAN]

        * In addition to starting the server, update the system to
          (not) restart the agent when the system reboots.

Generic Commands

  * <<ambari help>>

    * Provides the CLI help

  * <<ambari version>>

    * Ambari CLI version