github.com/jbking/gohan@v0.0.0-20151217002006-b41ccf1c2a96/docs/source/commands.rst (about)

     1  ===================
     2  Gohan Commands
     3  ===================
     4  
     5  Run ``gohan -h`` to list available commands
     6  
     7  .. code-block:: shell
     8  
     9    NAME:
    10       gohan - Gohan
    11  
    12    USAGE:
    13       gohan [global options] command [command options] [arguments...]
    14  
    15    VERSION:
    16       0.0.0
    17  
    18    COMMANDS:
    19       validate, v          Validate Json Schema file
    20       init-db, id          Init DB
    21       convert, conv        Convert DB
    22       server, srv          Run API Server
    23       help, h              Shows a list of commands or help for one command
    24  
    25    GLOBAL OPTIONS:
    26       --version, -v        print the version
    27       --help, -h           show help
    28  
    29  
    30  -----------------
    31  Validate
    32  -----------------
    33  
    34  .. code-block:: shell
    35  
    36    NAME:
    37       validate - Validate Json Schema file
    38  
    39    USAGE:
    40       command validate [command options] [arguments...]
    41  
    42    DESCRIPTION:
    43  
    44  
    45    OPTIONS:
    46       --schema, -s '../schema/core.json'   Json schema path
    47       --json, -i '../example/example.json' json path
    48  
    49  
    50  -----------------
    51  CLI Client
    52  -----------------
    53  
    54  You can use gohan client command to connect to gohan.
    55  
    56  Gohan client will show quick help for sub command for current
    57  server schema.
    58  
    59  Configuration
    60  =============
    61  
    62  Gohan CLI Client is configured though environment variables. Configuration can be divided into few sections.
    63  
    64  You can use default configuraion for client with:
    65  :code:`source ./etc/gohan_client.rc`
    66  
    67  Keystone
    68  --------
    69  
    70  To configure keystone access for Gohan Client CLI, only few options should be set (they are compatible with those
    71  from rackspace/gophercloud:
    72  
    73  * :code:`OS_AUTH_URL` - keystone url
    74  * :code:`OS_USERNAME` - keystone username
    75  * :code:`OS_PASSWORD` - keystone password
    76  * :code:`OS_TENANT_NAME` or :code:`OS_TENANT_ID` - keystone tenant name or id
    77  * :code:`OS_DOMAIN_NAME` or :code:`OS_DOMAIN_ID` - keystone domain name or id (for keystone v3 only)
    78  * :code:`OS_TOKEN_ID` - token ID used to authenticate requests
    79  
    80  Endpoint
    81  --------
    82  
    83  Gohan enpoint url can be specified directly or Gohan Client can get it from configured keystone.
    84  
    85  To specify endpoint directly, just set :code:`GOHAN_ENDPOINT_URL` to proper url.
    86  
    87  When using keystone:
    88  
    89  * :code:`GOHAN_SERVICE_NAME` - Gohan service name in keystone
    90  * :code:`GOHAN_REGION` - Gohan region name in keystone
    91  
    92  **Note:** setting all above options will result in using :code:`GOHAN_ENDPOINT_URL`!
    93  
    94  Schemas
    95  -------
    96  
    97  Gohan CLI Client is fetching available schemas from Gohan endpoint and can cache them in temp file for performance:
    98  
    99  * :code:`GOHAN_SCHEMA_URL` - Gohan schema url
   100  * :code:`GOHAN_CACHE_SCHEMAS` - should cache schemas (default - true)
   101  * :code:`GOHAN_CACHE_TIMEOUT` - how long cache is valid, uses 1h20m10s format (default - 5m)
   102  * :code:`GOHAN_CACHE_PATH` - where to store cache schemas (default - :code:`/tmp/.cached_gohan_schemas`)
   103  
   104  Usage
   105  =====
   106  
   107  Usage can be briefly described with:
   108  
   109  :code:`gohan client schema_id command [arguments...] [resource_identifier]`
   110  
   111  Each part of above command is described below.
   112  
   113  Schema_id
   114  ---------
   115  
   116  :code:`schema_id` determines which resource type we want to manage.
   117  
   118  If used :code:`schema_id` is not defined in Gohan, Gohan CLI Client will return :code:`Command not found` error.
   119  
   120  Command
   121  -------
   122  
   123  Commands are identical for each resources:
   124  
   125  * :code:`list` - List all resources
   126  * :code:`show` - Show resource details
   127  * :code:`create` - Create resource
   128  * :code:`set` - Update existing resource
   129  * :code:`delete` - Delete resource
   130  
   131  Arguments
   132  ---------
   133  
   134  Arguments should be specified in :code:`--name value` format.
   135  
   136  Passing JSON null value: :code:`--name "<null>"`
   137  
   138  Passing JSON not null value: :code:`--name '{"name": [{"name": "value"}, {"name": "value"}]}'`
   139  
   140  **Common arguments**
   141  
   142  In addition to resource related commands, some formatting commands are available:
   143  
   144  * :code:`--output-format [json/table]` - specifies in which format resoults should be shown
   145  
   146    - :code:`json`, e.g:
   147  
   148      .. code-block:: javascript
   149  
   150        {
   151          "name": "Resource name",
   152          "description": "Resource very long and meaningful description",
   153          "some_list": [
   154            "list_element_1",
   155            "list_element_2"
   156          ]
   157        }
   158      ..
   159  
   160    - :code:`table`, e.g:
   161  
   162      .. code-block:: shell
   163  
   164        +-------------+--------------------------------------+
   165        |    FIELD    |               TYPE                   |
   166        +-------------+--------------------------------------+
   167        | name        | Resource name                        |
   168        | description | Resource description                 |
   169        | some_list   | ["list_element_1", "list_element_2"] |
   170        +-------------+--------------------------------------+
   171  
   172  * :code:`--verbosity [0-3]` - specifies how much information Gohan Client should show - handy for dubugging
   173  
   174    - :code:`0` - no additional debug information is shown
   175    - :code:`1` - Sent request url and method is shown
   176    - :code:`2` - same as level :code:`1` + request & response body
   177    - :code:`3` - same as level :code:`2` + used auth token
   178  
   179  Resource identifier
   180  -------------------
   181  
   182  Some commands (:code:`show, set, delete`) are executed on one resource only. To identify whis reource,
   183  it's name or id could be used:
   184  
   185  .. code-block:: shell
   186  
   187    gohan client network show network-id
   188    gohan client network show "Network Name"
   189    gohan client subnet create --network "Network Name"
   190    gohan client subnet create --network network-id
   191    gohan client subnet create --network_id network-id