From 5dd55b33b42b2d9e4a159626d03cb6f5e9cad645 Mon Sep 17 00:00:00 2001 From: Lev Berman Date: Wed, 16 Sep 2015 17:38:42 +0300 Subject: [PATCH] Describe the possibilities of identifying entities by names --- README.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/README.md b/README.md index 12c2218..d431840 100644 --- a/README.md +++ b/README.md @@ -81,6 +81,17 @@ Or unset it using: clc data-center unset-default ``` +### Identify entities by ID or by name + +There is a great deal of commands that depend on the instances of certain entities, such as `server`, `group`, `network`. +A common pattern for specyfing such entities in the command line is `---id`, like `--server-id` or `--load-balancer-id`. + +Alternatively, a name of an entity can be specified (the common pattern is `---name`). This approach has some important subtleties to mention: + +* You can't specify both an ID and a name for the same entity. +* If there is more than one entity with the specified name, an error occurs. +* Autocomplete, if turned on, works for names and does **not** work for IDs. See [the Autocomplete section](#autocomplete-for-entity-names) for details. + ### Enjoy the tool Below are some examples of CLI commands so that you can faster get to use it efficiently. @@ -168,6 +179,16 @@ Only v3 support is provided because previous versions do not support custom auto To turn on autocomplete execute `.\powershell3_autocomplete.ps1`. You can find the file in the release tarball for Windows. +### Autocomplete for entity names + +Entity names is a special item in the autocomplete list because options are fetched from the server. Therefore such kind of autocomplete only works under certain circumstances and the process may take a relatively long time. +Below are the things you should be aware of: + +* The functionality does not work until the user has been authenticated. Authentication is needed to perform API requests. +* Since options are generated on the fly as the user enters a command, an entity name lookup for the data-center-dependent commands is only made within the default data center. If there is no default set, no options are to appear. +* In bash, a waiting indicator in the form of dot rotation is shown for the time options are being fetched after the Tab has been pressed. Windows PowerShell does not support such kind of interaction: in it, the input is simply blocked until the options have arrived. +* A cache is implemented to avoid making long subsequent requests to the server. The cache entry lifetime is 30 seconds. + ## Getting Help Explore the available resources, commands, options and other useful guidance using the `--help` option: