github.com/sl1pm4t/consul@v1.4.5-0.20190325224627-74c31c540f9c/website/source/docs/commands/kv/get.html.markdown.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: KV Get"
     4  sidebar_current: "docs-commands-kv-get"
     5  ---
     6  
     7  # Consul KV Get
     8  
     9  Command: `consul kv get`
    10  
    11  The `kv get` command is used to retrieve the value from Consul's KV
    12  store at the given key name. If no key exists with that name, an error is
    13  returned. If a key exists with that name but has no data, nothing is returned.
    14  A key name or prefix is required.
    15  
    16  ## Usage
    17  
    18  Usage: `consul kv get [options] [KEY_OR_PREFIX]`
    19  
    20  #### API Options
    21  
    22  <%= partial "docs/commands/http_api_options_client" %>
    23  <%= partial "docs/commands/http_api_options_server" %>
    24  
    25  #### KV Get Options
    26  
    27  * `-base64` - Base 64 encode the value. The default value is false.
    28  
    29  * `-detailed` - Provide additional metadata about the key in addition to the
    30    value such as the ModifyIndex and any flags that may have been set on the key.
    31    The default value is false.
    32  
    33  * `-keys` - List keys which start with the given prefix, but not their values.
    34    This is especially useful if you only need the key names themselves. This
    35    option is commonly combined with the -separator option. The default value is
    36    false.
    37  
    38  * `-recurse` - Recursively look at all keys prefixed with the given path. The
    39    default value is false.
    40  
    41  * `-separator=<string>` - String to use as a separator for recursive lookups. The 
    42    default value is "/", and only used when paired with the `-keys` flag. This will 
    43    limit the prefix of keys returned, only up to the given separator.
    44  
    45  ## Examples
    46  
    47  To retrieve the value for the key named "redis/config/connections" in the
    48  KV store:
    49  
    50  ```
    51  $ consul kv get redis/config/connections
    52  5
    53  ```
    54  
    55  This will return the original, raw value stored in Consul. To view detailed
    56  information about the key, specify the "-detailed" flag. This will output all
    57  known metadata about the key including ModifyIndex and any user-supplied
    58  flags:
    59  
    60  ```
    61  $ consul kv get -detailed redis/config/connections
    62  CreateIndex      336
    63  Flags            0
    64  Key              redis/config/connections
    65  LockIndex        0
    66  ModifyIndex      336
    67  Session          -
    68  Value            5
    69  ```
    70  
    71  If the key with the given name does not exist, an error is returned:
    72  
    73  ```
    74  $ consul kv get not-a-real-key
    75  Error! No key exists at: not-a-real-key
    76  ```
    77  
    78  To treat the path as a prefix and list all keys which start with the given
    79  prefix, specify the "-recurse" flag:
    80  
    81  ```
    82  $ consul kv get -recurse redis/
    83  redis/config/connections:5
    84  redis/config/cpu:128
    85  redis/config/memory:512
    86  ```
    87  
    88  Or list detailed information about all pairs under a prefix:
    89  
    90  ```
    91  $ consul kv get -recurse -detailed redis
    92  CreateIndex      336
    93  Flags            0
    94  Key              redis/config/connections
    95  LockIndex        0
    96  ModifyIndex      336
    97  Session          -
    98  Value            5
    99  
   100  CreateIndex      472
   101  Flags            0
   102  Key              redis/config/cpu
   103  LockIndex        0
   104  ModifyIndex      472
   105  Session          -
   106  Value            128
   107  
   108  CreateIndex      471
   109  Flags            0
   110  Key              redis/config/memory
   111  LockIndex        0
   112  ModifyIndex      471
   113  Session          -
   114  Value            512
   115  ```
   116  
   117  To just list the keys which start with the specified prefix, use the "-keys"
   118  option instead. This is more performant and results in a smaller payload:
   119  
   120  ```
   121  $ consul kv get -keys redis/config/
   122  redis/config/connections
   123  redis/config/cpu
   124  redis/config/memory
   125  ```
   126  
   127  By default, the `-keys` operation uses a separator of "/", meaning it will not
   128  recurse beyond that separator. You can choose a different separator by setting
   129  `-separator="<string>"`.
   130  
   131  ```
   132  $ consul kv get -keys -separator="c" redis
   133  redis/c
   134  ```
   135  
   136  Alternatively, you can disable the separator altogether by setting it to the
   137  empty string:
   138  
   139  ```
   140  $ consul kv get -keys -separator="" redis
   141  redis/config/connections
   142  redis/config/cpu
   143  redis/config/memory
   144  ```
   145  
   146  To list all keys at the root, simply omit the prefix parameter:
   147  
   148  ```
   149  $ consul kv get -keys
   150  memcached/
   151  redis/
   152  ```