From da777b2786e9bc9e2e0173018a0edff11ffad4c0 Mon Sep 17 00:00:00 2001
From: AJ <aj@alt>
Date: Tue, 17 Sep 2024 02:18:25 +0100
Subject: [PATCH] Deployed 2f36e93f with MkDocs version: 1.5.3

---
 404.html                 |  131 +-
 advanced/index.html      |  131 +-
 arguments/index.html     |  131 +-
 autocomplete/index.html  |  139 +-
 changelog/index.html     |  131 +-
 commands/index.html      |  131 +-
 documenting/index.html   |  131 +-
 exceptions/index.html    |  131 +-
 index.html               |  131 +-
 migration/index.html     |  131 +-
 options/index.html       |  131 +-
 parameters/index.html    |  131 +-
 quickstart/index.html    |  131 +-
 search/search_index.json |    2 +-
 sitemap.xml.gz           |  Bin 127 -> 127 bytes
 testing/index.html       |  133 +-
 utilities/index.html     | 2960 --------------------------------------
 whyclikt/index.html      |  131 +-
 18 files changed, 201 insertions(+), 4736 deletions(-)
 delete mode 100755 utilities/index.html

diff --git a/404.html b/404.html
index ba3539b4..4f0be6f2 100755
--- a/404.html
+++ b/404.html
@@ -2129,7 +2129,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2138,111 +2138,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="/utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="/utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="/utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2353,10 +2248,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2367,8 +2262,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2458,10 +2353,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2472,8 +2367,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2626,10 +2521,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2640,8 +2535,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/advanced/index.html b/advanced/index.html
index 79a9b685..1ba9eb62 100755
--- a/advanced/index.html
+++ b/advanced/index.html
@@ -2387,7 +2387,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2396,111 +2396,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2611,10 +2506,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2625,8 +2520,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2716,10 +2611,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2730,8 +2625,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2884,10 +2779,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2898,8 +2793,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/arguments/index.html b/arguments/index.html
index 005ec3e9..6c391047 100755
--- a/arguments/index.html
+++ b/arguments/index.html
@@ -2207,7 +2207,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2216,111 +2216,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2431,10 +2326,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2445,8 +2340,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2536,10 +2431,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2550,8 +2445,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2704,10 +2599,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2718,8 +2613,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/autocomplete/index.html b/autocomplete/index.html
index 01a98b25..3239c6ee 100755
--- a/autocomplete/index.html
+++ b/autocomplete/index.html
@@ -13,7 +13,7 @@
       
       
       
-        <link rel="prev" href="../utilities/">
+        <link rel="prev" href="../testing/">
       
       
         <link rel="next" href="../exceptions/">
@@ -2121,111 +2121,6 @@
       
   
   
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" >
-        
-          
-          <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Utilities
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
     
   
   
@@ -2238,10 +2133,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" checked>
         
           
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2252,8 +2147,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_11">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_10">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2530,10 +2425,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2544,8 +2439,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2635,10 +2530,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2649,8 +2544,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2803,10 +2698,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2817,8 +2712,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/changelog/index.html b/changelog/index.html
index d34aa687..0a796125 100755
--- a/changelog/index.html
+++ b/changelog/index.html
@@ -2138,7 +2138,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2147,111 +2147,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2362,10 +2257,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2376,8 +2271,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2467,10 +2362,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2481,8 +2376,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2637,10 +2532,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" checked>
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2651,8 +2546,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/commands/index.html b/commands/index.html
index 0f712db5..e482b9b6 100755
--- a/commands/index.html
+++ b/commands/index.html
@@ -2270,7 +2270,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2279,111 +2279,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2494,10 +2389,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2508,8 +2403,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2599,10 +2494,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2613,8 +2508,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2767,10 +2662,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2781,8 +2676,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/documenting/index.html b/documenting/index.html
index d85a7c05..714217c9 100755
--- a/documenting/index.html
+++ b/documenting/index.html
@@ -2318,7 +2318,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2327,111 +2327,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2542,10 +2437,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2556,8 +2451,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2647,10 +2542,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2661,8 +2556,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2815,10 +2710,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2829,8 +2724,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/exceptions/index.html b/exceptions/index.html
index 71d33d70..79ffa285 100755
--- a/exceptions/index.html
+++ b/exceptions/index.html
@@ -2138,7 +2138,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2147,111 +2147,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2364,10 +2259,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" checked>
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2378,8 +2273,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2536,10 +2431,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2550,8 +2445,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2704,10 +2599,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2718,8 +2613,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/index.html b/index.html
index c1c1052a..6515586a 100755
--- a/index.html
+++ b/index.html
@@ -2136,7 +2136,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2145,111 +2145,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2360,10 +2255,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2374,8 +2269,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2465,10 +2360,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2479,8 +2374,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2633,10 +2528,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2647,8 +2542,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/migration/index.html b/migration/index.html
index f7d9ebe1..3603ee99 100755
--- a/migration/index.html
+++ b/migration/index.html
@@ -2136,7 +2136,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2145,111 +2145,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2360,10 +2255,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2374,8 +2269,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2465,10 +2360,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2479,8 +2374,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2635,10 +2530,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" checked>
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" checked>
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2649,8 +2544,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="true">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/options/index.html b/options/index.html
index a46b8049..1b94f81b 100755
--- a/options/index.html
+++ b/options/index.html
@@ -2534,7 +2534,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2543,111 +2543,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2758,10 +2653,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2772,8 +2667,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2863,10 +2758,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2877,8 +2772,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -3031,10 +2926,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -3045,8 +2940,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/parameters/index.html b/parameters/index.html
index a26b8201..50a5b473 100755
--- a/parameters/index.html
+++ b/parameters/index.html
@@ -2351,7 +2351,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2360,111 +2360,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2575,10 +2470,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2589,8 +2484,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2680,10 +2575,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2694,8 +2589,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2848,10 +2743,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2862,8 +2757,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/quickstart/index.html b/quickstart/index.html
index 2587cdb0..d77cd610 100755
--- a/quickstart/index.html
+++ b/quickstart/index.html
@@ -2232,7 +2232,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2241,111 +2241,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2456,10 +2351,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2470,8 +2365,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2561,10 +2456,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2575,8 +2470,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2729,10 +2624,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2743,8 +2638,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/search/search_index.json b/search/search_index.json
index 83ff870f..ba4cab90 100755
--- a/search/search_index.json
+++ b/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"<p>Clikt (pronounced \u201cclicked\u201d) is a multiplatform Kotlin library that makes writing command line interfaces simple and intuitive. It\u2019s the \u201cCommand Line Interface for Kotlin\u201d.</p> <p>It is designed to make the process of writing command line tools effortless while supporting a wide variety of use cases and allowing advanced customization when needed.</p> <p>Clikt has:</p> <ul> <li>arbitrary nesting of commands</li> <li>composable, type safe parameter values</li> <li>generation of help output and shell autocomplete scripts</li> <li>multiplatform packages for JVM, Node.js, and native Linux, Windows and macOS </li> </ul> <p>What does it look like? Here\u2019s a complete example of a simple Clikt program:</p> <pre><code>class Hello : CliktCommand() {\n    val count: Int by option().int().default(1).help(\"Number of greetings\")\n    val name: String by option().prompt(\"Your name\").help(\"The person to greet\")\n\n    override fun run() {\n        repeat(count) {\n            echo(\"Hello $name!\")\n        }\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Hello().main(args)\n</code></pre> <p>And here\u2019s what it looks like when run:</p> <p></p> <p>The help page is generated for you:</p> <p></p> <p>Errors are also taken care of:</p> <p></p>"},{"location":"#installation","title":"Installation","text":"<p>Clikt is distributed through Maven Central.</p> <pre><code>dependencies {\n   implementation(\"com.github.ajalt.clikt:clikt:5.0.0\")\n\n   // optional support for rendering markdown in help messages\n   implementation(\"com.github.ajalt.clikt:clikt-markdown:5.0.0\")\n}\n</code></pre> <p>There is also a smaller core module available. See the docs for details.</p>"},{"location":"#if-youre-using-maven-instead-of-gradle-use-artifactidclikt-jvmartifactid","title":"If you\u2019re using Maven instead of Gradle, use <code>&lt;artifactId&gt;clikt-jvm&lt;/artifactId&gt;</code>","text":""},{"location":"#multiplatform","title":"Multiplatform","text":"<p>Clikt supports most multiplatform targets. See the docs  for more information about functionality supported on each target. You\u2019ll need to use Gradle 6 or newer.</p>"},{"location":"#snapshots","title":"Snapshots","text":"Snapshot builds are also available <p> You'll need to add the Sonatype snapshots repository:   <pre><code>repositories {\n    maven {\n        url = uri(\"https://oss.sonatype.org/content/repositories/snapshots/\")\n    }\n}\n</code></pre> </p>"},{"location":"#api-reference","title":"API Reference","text":"<ul> <li>Commands and Exceptions</li> <li>Options</li> <li>Arguments</li> <li>Parameter Type Conversions</li> <li>Output Formatting</li> </ul>"},{"location":"advanced/","title":"Advanced Patterns","text":""},{"location":"advanced/#common-options-with-subcommands","title":"Common Options With Subcommands","text":"<p>In some cases, you will have multiple subcommands that all share a common set of options. For example, you may have an option for a config file, or an output directory, or some API credentials. There are several ways to structure your commands to avoid repeating the option declarations in each subcommand.</p>"},{"location":"advanced/#defining-common-options-on-the-root-command","title":"Defining Common Options on the Root Command","text":"<p>You can define your options on the root command and pass down the information via the context. With this design, you\u2019ll have to specify the common options before the subcommand name on the command line.</p> ExampleUsage 1Usage 2 <pre><code>class Config(val token: String, val hostname: String)\n\nclass MyApi : CliktCommand() {\n    private val token by option(help=\"api token to use for requests\").default(\"...\")\n    private val hostname by option(help=\"base url for requests\").default(\"example.com\")\n\n    override fun run() {\n        currentContext.obj = Config(token, hostname)\n    }\n}\n\nclass Store : CliktCommand() {\n    private val file by option(help=\"file to store\").file(canBeDir = false)\n    private val config by requireObject&lt;Config&gt;()\n    override fun run() {\n        myApiStoreFile(config.token, config.hostname, file)\n    }\n}\n\nclass Fetch : CliktCommand() {\n    private val outdir by option(help=\"directory to store file in\").file(canBeFile = false)\n    private val config by requireObject&lt;Config&gt;()\n    override fun run() {\n        myApiFetchFile(config.token, config.hostname, outdir)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = MyApi().subcommands(Store(), Fetch()).main(args)\n</code></pre> <pre><code>$ ./myapi --hostname=https://example.com store file.txt\n</code></pre> <pre><code>$ ./myapi --hostname=https://example.com fetch --outdir=./out\n</code></pre>"},{"location":"advanced/#defining-common-options-in-a-group","title":"Defining Common Options in a Group","text":"<p>Instead of defining your common options on the root command, you can instead define them in an OptionGroup which you include in each subcommand. This allows you to specify all options after the subcommand name.</p> ExampleUsage 1Usage 2 <pre><code>class CommonOptions: OptionGroup(\"Standard Options:\") {\n    val token by option(help=\"api token to use for requests\").default(\"...\")\n    val hostname by option(help=\"base url for requests\").default(\"example.com\")\n}\n\nclass MyApi : NoOpCliktCommand()\n\nclass Store : CliktCommand() {\n    private val commonOptions by CommonOptions()\n    private val file by option(help=\"file to store\").file(canBeDir = false)\n    override fun run() {\n        myApiStoreFile(commonOptions.token, commonOptions.hostname, file)\n    }\n}\n\nclass Fetch : CliktCommand() {\n    private val commonOptions by CommonOptions()\n    private val outdir by option(help=\"directory to store file in\").file(canBeFile = false)\n    override fun run() {\n        myApiFetchFile(commonOptions.token, commonOptions.hostname, outdir)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = MyApi().subcommands(Store(), Fetch()).main(args)\n</code></pre> <pre><code>$ ./myapi store --hostname=https://example.com file.txt\n</code></pre> <pre><code>$ ./myapi fetch --hostname=https://example.com --outdir=./out\n</code></pre>"},{"location":"advanced/#defining-common-options-in-a-base-class","title":"Defining Common Options in a Base Class","text":"<p>A third design to share options is to define the common options in a base class that all the subcommands inherit from.</p> ExampleUsage 1Usage 2 <pre><code>abstract class MyApiSubcommand : CliktCommand() {\n    val token by option(help = \"api token to use for requests\").default(\"...\")\n    val hostname by option(help = \"base url for requests\").default(\"example.com\")\n}\n\nclass MyApi : NoOpCliktCommand()\n\nclass Store : MyApiSubcommand() {\n    private val file by option(help = \"file to store\").file(canBeDir = false)\n    override fun run() {\n        myApiStoreFile(token, hostname, file)\n    }\n}\n\nclass Fetch : MyApiSubcommand() {\n    private val outdir by option(help = \"directory to store file in\").file(canBeFile = false)\n    override fun run() {\n        myApiFetchFile(token, hostname, outdir)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = MyApi().subcommands(Store(), Fetch()).main(args)\n</code></pre> <pre><code>$ ./myapi store --hostname=https://example.com file.txt\n</code></pre> <pre><code>$ ./myapi fetch --hostname=https://example.com --outdir=./out\n</code></pre>"},{"location":"advanced/#command-aliases","title":"Command Aliases","text":"<p>Clikt allows commands to alias command names to sequences of tokens. This allows you to implement common patterns like allowing the user to invoke a command by typing a prefix of its name, or user-defined aliases like the way you can configure git to accept <code>git ci</code> as an alias for <code>git commit</code>.</p> <p>To implement command aliases, override <code>CliktCommand.aliases</code> in your command. This function is called once at the start of parsing, and returns a map of aliases to the tokens that they alias to.</p> <p>To implement git-style aliases:</p> ExampleUsage 1Usage 2 <pre><code>class Repo : NoOpCliktCommand() {\n    // You could load the aliases from a config file etc.\n    override fun aliases(): Map&lt;String, List&lt;String&gt;&gt; = mapOf(\n            \"ci\" to listOf(\"commit\"),\n            \"cm\" to listOf(\"commit\", \"-m\")\n    )\n}\n\nclass Commit: CliktCommand() {\n    val message by option(\"-m\").default(\"\")\n    override fun run() {\n        echo(\"Committing with message: $message\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Repo().subcommands(Commit()).main(args)\n</code></pre> <pre><code>$ ./repo ci -m 'my message'\nCommitting with message: my message\n</code></pre> <pre><code>$ ./repo cm 'my message'\nCommitting with message: my message\n</code></pre> <p>Note</p> <p>Aliases are not expanded recursively: none of the tokens that an alias expands to will be expanded again, even if they match another alias.</p> <p>You also use this functionality to implement command prefixes:</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand() {\n    override fun aliases(): Map&lt;String, List&lt;String&gt;&gt; {\n        val prefixCounts = mutableMapOf&lt;String, Int&gt;().withDefault { 0 }\n        val prefixes = mutableMapOf&lt;String, List&lt;String&gt;&gt;()\n        for (name in registeredSubcommandNames()) {\n            if (name.length &lt; 3) continue\n            for (i in 1..name.lastIndex) {\n                val prefix = name.substring(0..i)\n                prefixCounts[prefix] = prefixCounts.getValue(prefix) + 1\n                prefixes[prefix] = listOf(name)\n            }\n        }\n        return prefixes.filterKeys { prefixCounts.getValue(it) == 1 }\n    }\n}\n\nclass Foo: CliktCommand() {\n    override fun run() {\n        echo(\"Running Foo\")\n    }\n}\n\nclass Bar: CliktCommand() {\n    override fun run() {\n        echo(\"Running Bar\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Foo(), Bar()).main(args)\n</code></pre> <pre><code>$ ./tool ba\nRunning Bar\n</code></pre>"},{"location":"advanced/#token-normalization","title":"Token Normalization","text":"<p>To prevent ambiguities in parsing, aliases are only supported for command names. However, there\u2019s another way to modify user input that works on more types of tokens. You can set <code>transformToken</code> on the command\u2019s context, which will be called for each option and command name that\u2019s input. This can be used to implement case-insensitive parsing, for example:</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    init {\n        context { transformToken = { it.lowercase() } }\n    }\n\n    val name by option()\n    override fun run() = echo(\"Hello $name!\")\n}\n</code></pre> <pre><code>$ ./hello --NAME=Clikt\nHello Clikt!\n</code></pre>"},{"location":"advanced/#replacing-stdin-and-stdout","title":"Replacing stdin and stdout","text":"<p>By default, functions like <code>CliktCommand.main</code> and <code>option().prompt()</code> read from stdin and write to stdout. If you want to use Clikt in an environment where the standard streams aren\u2019t available, you can set your own implementation of a <code>TerminalInterface</code> when customizing the command context.</p> <pre><code>object MyInterface : TerminalInterface {\n    override val info: TerminalInfo\n        get() = TerminalInfo(/* ... */)\n\n    override fun completePrintRequest(request: PrintRequest) {\n        if (request.stderr) MyOutputStream.writeError(request.text)\n        else MyOutputStream.write(request.text)\n    }\n\n    override fun readLineOrNull(hideInput: Boolean): String? {\n        return if (hideInput) MyInputStream.readPassword()\n        else MyInputStream.readLine()\n    }\n}\n\nclass CustomCLI : NoOpCliktCommand() {\n    init { context { terminal = Terminal(terminalInterface = MyInterface ) } }\n}\n</code></pre> <p>Tip</p> <p>If you want to log the output, you can use Mordant\u2019s <code>TerminalRecorder</code>. That\u2019s how test is implemented!</p>"},{"location":"advanced/#command-line-argument-files-argfiles","title":"Command Line Argument Files (\u201c@argfiles\u201d)","text":"<p>Similar to <code>javac</code>, Clikt supports loading command line parameters from a file using the \u201c@argfile\u201d syntax. You can pass any file path to a command prefixed with <code>@</code>, and the file will be expanded into the command line parameters. This can be useful on operating systems like Windows that have command line length limits.</p> <p>If you create a file named <code>cliargs</code> with content like this:</p> <pre><code>--number 1\n--name='jane doe' --age=30\n./file.txt\n</code></pre> <p>You can call your command with the contents of the file like this:</p> <pre><code>$ ./tool @cliargs\n</code></pre> <p>Which is equivalent to calling it like this:</p> <pre><code>$ ./tool --number 1 --name='jane doe' --age=30 ./file.txt\n</code></pre> <p>You can use any file path after the <code>@</code>, and can specify multiple @argfiles:</p> <pre><code>$ ./tool @../config/args @C:\\\\Program\\ Files\\\\Tool\\\\argfile\n</code></pre> <p>If you have any options with names that start with <code>@</code>, you can still use <code>@argfiles</code>, but values on the command line that match an option will be parsed as that option, rather than an <code>@argfile</code>, so you\u2019ll have to give your files a different name.</p>"},{"location":"advanced/#preventing-argfile-expansion","title":"Preventing @argfile expansion","text":"<p>If you want to use a value starting with <code>@</code> as an argument without expanding it, you have three options:</p> <ol> <li>Pass it after a <code>--</code>, which disables expansion for everything that occurs after it.</li> <li>Escape it with <code>@@</code>. The first <code>@</code> will be removed and the rest used as the argument value. For example, <code>@@file</code> will parse as the string <code>@file</code></li> <li>Disable @argfile expansion entirely by setting <code>Context.readArgumentFile = null</code></li> </ol>"},{"location":"advanced/#file-format","title":"File format","text":"<ul> <li>Normal shell quoting and escaping rules apply. </li> <li>Line breaks are treated as word separators, and can be used where you would normally use a space   to separate parameters.</li> <li>Line breaks can occur within quotes, and will be included in the quoted value.</li> <li>@argfiles can contain other @argfile arguments, which will be expanded recursively.</li> <li>An unescaped <code>#</code> character outside of quotes is treated as a line comment: it and the rest of the   line are skipped. You can pass a literal <code>#</code> by escaping it with <code>\\#</code> or quoting it with <code>'#'</code>.</li> <li>If a <code>\\</code> occurs at the end of a line, the next line is trimmed of leading whitespace and the two   lines are concatenated.</li> </ul>"},{"location":"advanced/#managing-shared-resources","title":"Managing Shared Resources","text":"<p>You might need to open a resource like a file or a network connection in one command, and use it in its subcommands.</p> <p>The typical way to manage a resource is with the <code>use</code> function:</p> <pre><code>class MyCommand : CliktCommand() {\n    private val file by option().file().required()\n\n    override fun run() {\n        file.bufferedReader().use { reader -&gt;\n            // use the reader\n        }\n    }\n}\n</code></pre> <p>But if you need to share the resource with subcommands, the <code>use</code> function will exit and close the resource before the subcommand is called. Instead, use the context\u2019s registerCloseable function (for <code>kotlin.AutoCloseable</code>) or registerJvmCloseable function (for <code>java.lang.AutoCloseable</code>) to:</p> <pre><code>class MyCommand : CliktCommand() {\n    private val file by option().file().required()\n\n    override fun run() {\n        currentContext.obj = currentContext.registerJvmCloseable(file.bufferedReader())\n    }\n}\n</code></pre> <p>You can register as many closeables as you need, and they will all be closed when the command and its subcommands have finished running. If you need to manage a resource that isn\u2019t <code>AutoClosable</code>, you can use callOnClose.</p>"},{"location":"advanced/#custom-exit-status-codes","title":"Custom exit status codes","text":"<p>Clikt will normally exit your program with a status code of 0 for a normal execution, or 1 if there\u2019s an error. If you want to use a different value, you can <code>throw ProgramResult(statusCode)</code>. If you use <code>CliktCommand.main</code>, that exception will be caught and <code>exitProcess</code> will be called with the value of <code>statusCode</code>.</p> <p>You could also call <code>exitProcess</code> yourself, but the ProgramResult has a couple of advantages:</p> <ul> <li><code>ProgramResult</code> is easier to test. Exiting the process makes unit tests difficult to run.</li> <li><code>ProgramResult</code> works on all platforms. <code>exitProcess</code> is only available on the JVM.</li> </ul>"},{"location":"advanced/#custom-run-function-signature","title":"Custom run function signature","text":"<p>Clikt provides a few command base classes that have different run function signatures. CliktCommand has <code>fun run()</code>, while SuspendingCliktCommand has <code>suspend fun run()</code>. If you want a run function with a different signature, you can define your own base class the inherits from BaseCliktCommand and use the CommandLineParser methods to parse and run the command.</p> <p>For example, if you want a command that uses a Flow to emit multiple value for each run, you could implement it like this:</p> ExampleUsage <pre><code>abstract class FlowCliktCommand : BaseCliktCommand&lt;FlowCliktCommand&gt;() {\n    abstract fun run(): Flow&lt;String&gt;\n}\n\nclass MyFlowCommand : FlowCliktCommand() {\n    val opt by option().required()\n    val arg by argument().int()\n\n    override fun run(): Flow&lt;String&gt; = flow {\n        emit(opt)\n        emit(arg.toString())\n    }\n}\n\nclass MyFlowSubcommand : FlowCliktCommand() {\n    val arg by argument().multiple()\n\n    override fun run(): Flow&lt;String&gt; = flow {\n        arg.forEach { emit(it) }\n    }\n}\n\nfun FlowCliktCommand.parse(argv: Array&lt;String&gt;): Flow&lt;String&gt; {\n    val flows = mutableListOf&lt;Flow&lt;String&gt;&gt;()\n    CommandLineParser.parseAndRun(this, argv.asList()) { flows += it.run() }\n    return flow { flows.forEach { emitAll(it) } }\n}\n\nfun FlowCliktCommand.main(argv: Array&lt;String&gt;): Flow&lt;String&gt; {\n    return CommandLineParser.mainReturningValue(this) { parse(argv) }\n}\n\nsuspend fun main(args: Array&lt;String&gt;) {\n    val command = MyFlowCommand().subcommands(MyFlowSubcommand())\n    val resultFlow: Flow&lt;String&gt; = command.main(args)\n    resultFlow.collect {\n        command.echo(it)\n    }\n}\n</code></pre> <pre><code>$ ./command --opt=foo 11 my-flow-subcommand bar baz\nfoo\n11\nbar\nbaz\n</code></pre> <p>There are a number of steps here, so let\u2019s break it down:</p> <ol> <li>Define a base class <code>FlowCliktCommand</code> that inherits from BaseCliktCommand and has an abstract    <code>run</code> function that returns a <code>Flow</code>.</li> <li>Define your commands that inherit from <code>FlowCliktCommand</code> and implement your <code>run</code> function.</li> <li>Define an extension function <code>parse</code> that uses CommandLineParser.parseAndRun to parse the    command and run the <code>run</code> function.</li> <li>Define an extension function <code>main</code> that uses CommandLineParser.main to run the <code>parse</code>    function and handle any exceptions it might throw.</li> <li>In your <code>main</code> function, call <code>main</code> on your command, and collect the results of the <code>Flow</code>.</li> </ol> <p>If you want to customize the behavior even further, see the next section.</p>"},{"location":"advanced/#custom-run-behavior","title":"Custom run behavior","text":"<p>If you want to customize how or when subcommands are run, you can do so by defining a custom base class like in the previous section, but instead of using <code>CommandLineParser.parseAndRun</code>, you can call your command\u2019s <code>run</code> functions manually.</p> <p>For example, if you want commands to return status codes, and you want to stop running commands as soon as one of them returns a non-zero status code, you could implement it like this:</p> ExampleUsage <pre><code>abstract class StatusCliktCommand : BaseCliktCommand&lt;StatusCliktCommand&gt;() {\n    abstract fun run(): Int\n}\n\nclass ParentCommand : StatusCliktCommand() {\n    override val allowMultipleSubcommands: Boolean = true\n    override fun run(): Int {\n        echo(\"Parent\")\n        return 0\n    }\n}\n\nclass SuccessCommand : StatusCliktCommand() {\n    override fun run(): Int {\n        echo(\"Success\")\n        return 0\n    }\n}\n\nclass FailureCommand : StatusCliktCommand() {\n    override fun run(): Int {\n        echo(\"Failure\")\n        return 1001\n    }\n}\n\nfun StatusCliktCommand.parse(argv: Array&lt;String&gt;): Int {\n    val parseResult = CommandLineParser.parse(this, argv.asList())\n    parseResult.invocation.flatten().use { invocations -&gt;\n        for (invocation in invocations) {\n            val status = invocation.command.run()\n            if (status != 0) {\n                return status\n            }\n        }\n    }\n    return 0\n}\n\nfun StatusCliktCommand.main(argv: Array&lt;String&gt;) {\n    val status = CommandLineParser.mainReturningValue(this) { parse(argv) }\n    exitProcess(status)\n}\n\nfun main(argv: Array&lt;String&gt;) {\n    ParentCommand().subcommands(SuccessCommand(), FailureCommand()).main(argv)\n}\n</code></pre> <pre><code>$ ./command success failure success\nParent\nSuccess\nFailure\n\n$ echo $?\n1001\n</code></pre> <p>The steps here are similar to the previous section, but instead of using CommandLineParser.parseAndRun, we use CommandLineParser.parse, then call <code>run</code> on each command invocation manually, and stop when one of them returns a non-zero status code.</p>"},{"location":"advanced/#core-module","title":"Core Module","text":"<p>Clikt normally uses Mordant for rendering output and interacting with the system, but there are some  cases where you might want to use Clikt without Mordant. For these cases, Clikt has a core module that doesn\u2019t have any dependencies.</p> <p>Replace your Clikt dependency with the core module:</p> <pre><code>dependencies {\n    implementation(\"com.github.ajalt.clikt:clikt-core:$cliktVersion\")\n}\n</code></pre> <p>The CliktCommand class is only available in the full module, so you\u2019ll need to use CoreCliktCommand (or CoreNoOpCliktCommand) instead. The <code>CoreCliktCommand</code> has the same API as <code>CliktCommand</code>, but it doesn\u2019t have any of these features built in:</p> <ul> <li>Text wrapping, formatting, markdown, or color support</li> <li>argument files</li> <li>environment variables</li> <li><code>main</code> exiting the process with a status code</li> <li>printing to stderr</li> <li>prompt options</li> <li>The test function</li> </ul> <p>Most of those features can be added by setting the appropriate properties on the command\u2019s context. Here\u2019s an example of setting all of them using Java APIs, but you only need to set the ones you\u2019ll use:</p> <pre><code>abstract class MyCoreCommand : CoreCliktCommand() {\n    init {\n        context {\n            readArgumentFile = {\n                try {\n                    Path(it).readText()\n                } catch (e: IOException) {\n                    throw FileNotFound(it)\n                }\n            }\n            readEnvvar = { System.getenv(it) }\n            exitProcess = { System.exit(it) }\n            echoMessage = { context, message, newline, err -&gt;\n                val writer = if (err) System.err else System.out\n                if (newline) {\n                    writer.println(message)\n                } else {\n                    writer.print(message)\n                }\n            }\n        }\n    }\n}\n</code></pre>"},{"location":"advanced/#multiplatform-support","title":"Multiplatform Support","text":"<p>Clikt supports the following platforms:</p>"},{"location":"advanced/#jvm","title":"JVM","text":"<p>There are some JVM-only extensions available such as file and path parameter types.</p>"},{"location":"advanced/#desktop-native-linux-windows-and-macos","title":"Desktop native (Linux, Windows, and macOS)","text":""},{"location":"advanced/#javascript-and-wasmjs","title":"JavaScript and WasmJS","text":"<p>All functionality is supported on Node.js.</p> <p>In the browser, the default terminal only outputs to the browser\u2019s developer console, which is probably not what you want. You can define your own TerminalInterface, or you can call parse instead of main and handle output yourself.</p>"},{"location":"advanced/#ios","title":"iOS","text":""},{"location":"advanced/#watchos-tvos-and-wasmwasi","title":"watchOS, tvOS and WasmWasi","text":"<p>These platforms are not supported by the markdown module, but all other functionality is available.</p>"},{"location":"arguments/","title":"Arguments","text":"<p>Arguments are declared and customized similarly to options, but are provided on the command line positionally instead of by name. Arguments are declared with <code>argument()</code>, and the order that they are declared defines the order that they must be provided on the command line.</p>"},{"location":"arguments/#basic-arguments","title":"Basic Arguments","text":"<p>By default, <code>argument</code> takes a single <code>String</code> value which is required to be provided on the command line.</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    val name by argument()\n    override fun run() {\n        echo(\"Hello $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello Foo\nHello Foo!\n</code></pre> <p>Arguments appear in the usage string, but listed in the help page unless you set their <code>help</code> value. It\u2019s usually clearer to document arguments in the command help.</p> ExampleHelp Output <pre><code>class Cp : CliktCommand(\n    help = \"Copy &lt;source&gt; to &lt;dest&gt;, or multiple &lt;source&gt;(s) to directory &lt;dest&gt;.\"\n) {\n    private val source by argument().file(mustExist = true).multiple()\n    private val dest by argument().file()\n    override fun run() {\n        // ...\n    }\n}\n</code></pre> <pre><code>Usage: cp [&lt;options&gt;] [&lt;source&gt;]... &lt;dest&gt;\n\n  Copy &lt;source&gt; to &lt;dest&gt;, or multiple &lt;source&gt;(s) to directory &lt;dest&gt;.\n\nOptions:\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"arguments/#variadic-arguments","title":"Variadic Arguments","text":"<p>Like options, arguments can take any fixed number of values, which you can change with functions like <code>pair</code> and <code>triple</code>. Unlike options, arguments can also take a variable (or unlimited) number of values. This is common with file path arguments, since they are frequently expanded with a glob pattern on the command line.</p> <p>Variadic arguments are declared with <code>multiple</code>. You can declare any number of arguments with fixed numbers of values, but only one variadic argument in a command.</p> ExampleUsage <pre><code>class Copy : CliktCommand() {\n    val source: List&lt;Path&gt; by argument().path(mustExist = true).multiple()\n    val dest: Path by argument().path(canBeFile = false)\n    override fun run() {\n        echo(\"Copying files $source to $dest\")\n    }\n}\n</code></pre> <pre><code>$ ./copy file.* out/\nCopying files [file.txt, file.md] to out/\n</code></pre> <p>You can also use <code>unique</code> to discard duplicates:</p> <pre><code>val source: Set&lt;Path&gt; by argument().path(mustExist = true).multiple().unique()\n</code></pre>"},{"location":"arguments/#option-like-arguments-using-","title":"Option-Like Arguments (Using <code>--</code>)","text":"<p>Clikt normally parses any value that starts with punctuation as an option, which allows users to intermix options and arguments. However, sometimes you need to pass a value that starts with punctuation to an argument. For example, you might have a file named <code>-file.txt</code> that you want to use as an argument.</p> <p>Clikt supports the POSIX convention of using <code>--</code> to force all following values to be treated as arguments. Any values before the <code>--</code> will be parsed normally.</p> ExampleUsage 1Usage 2 <pre><code>class Touch : CliktCommand() {\n    val verbose by option().flag()\n    val files by argument().multiple()\n    override fun run() {\n        if (verbose) echo(files.joinToString(\"\\n\"))\n    }\n}\n</code></pre> <pre><code>$ ./touch --foo.txt\nUsage: touch [&lt;options&gt;] [&lt;files&gt;]...\n\nError: no such option: \"--foo.txt\".\n</code></pre> <pre><code>$ ./touch --verbose -- --foo.txt bar.txt\n--foo.txt\nbar.txt\n</code></pre>"},{"location":"autocomplete/","title":"Shell Autocomplete","text":"<p>Clikt includes built-in support for generating autocomplete scripts for bash, zsh and fish shells.</p> Example <pre><code>$ ./repo &lt;TAB&gt;&lt;TAB&gt;\ncommit clone pull\n\n$ ./repo -&lt;TAB&gt;\n--config -h --help --repo-home --verbose\n\n$./repo --repo-home ./g&lt;TAB&gt;\n./git ./got ./good\n</code></pre>"},{"location":"autocomplete/#enabling-completion","title":"Enabling Completion","text":"<p>Clikt handles autocomplete by generating a shell script that defines the completion. You generate the script once each time your CLI changes, and load it each time your start your shell. </p>"},{"location":"autocomplete/#with-an-environment-variable","title":"With an environment variable","text":"<p>You can generate the completion script by invoking your program with a special environment variable.</p> <p>You can set the variable name manually with by overriding the <code>autoCompleteEnvvar</code> property in your command. By default, it\u2019s your command\u2019s name capitalized, with <code>-</code> replaced with <code>_</code>, and prefixed with another <code>_</code>. So if your command name is <code>my-command</code>, the variable would be <code>_MY_COMMAND_COMPLETE=bash</code>, <code>_MY_COMMAND_COMPLETE=zsh</code>, or <code>_MY_COMMAND_COMPLETE=fish</code>, depending on your current shell.</p> <p>For example to activate bash autocomplete for this command:</p> <pre><code>class MyProgram: CliktCommand() {\n    // ...\n}\n</code></pre> <p>You can generate the completion script and save it to a file like this:</p> <pre><code>$ _MY_PROGRAM_COMPLETE=bash ./my-program &gt; ~/my-program-completion.sh\n</code></pre>"},{"location":"autocomplete/#with-an-option","title":"With an option","text":"<p>If you\u2019d prefer not to use environment variables, you can add a special option to your command with the <code>completionOption</code> function. Invoking your program with this option will generate the completion script:</p> Example 1Example 2Usage <pre><code>class MyCommand: CliktCommand() {\n    init {\n        completionOption()\n    }\n    // ...\n}\n</code></pre> <pre><code>class MyCommand: CliktCommand() {\n    //..\n}\n\nfun main(args: Array&lt;String&gt;) = MyCommand().completionOption().main(args)\n</code></pre> <pre><code>$ ./my-command --generate-completion=bash &gt; ~/my-program-completion.sh\n</code></pre>"},{"location":"autocomplete/#with-a-subcommand","title":"With a subcommand","text":"<p>A third option is to add a subcommand that will generate the completion when invoked.</p> Example 1Example 2Usage <pre><code>class MyCommand: CliktCommand() {\n    init {\n        subcommands(CompletionCommand())\n    }\n    // ...\n}\n</code></pre> <pre><code>class MyCommand: CliktCommand() {\n    //..\n}\n\nfun main(args: Array&lt;String&gt;) = MyCommand().subcommands(CompletionCommand()).main(args)\n</code></pre> <pre><code>$ ./my-command generate-completion bash &gt; ~/my-program-completion.sh\n</code></pre>"},{"location":"autocomplete/#manually","title":"Manually","text":"<p>Finally, if none of the built-in methods work for you, you can generate the completion script yourself with the CompletionGenerator.</p> Example <pre><code>class MyCommand: CliktCommand() {\n    override fun run() {\n        echo(CompletionGenerator.generateCompletionForCommand(this, \"bash\"))\n    }\n}\n</code></pre>"},{"location":"autocomplete/#using-the-generated-script","title":"Using the generated script","text":"<p>Once you\u2019ve generated the completion script, source the file to activate completion:</p> <pre><code>$ source ~/my-program-completion.sh\n</code></pre> <p>You can add that source command to your startup script so that completion is always available. For example, with bash:</p> <pre><code>$ echo source ~/my-program-completion.sh &gt;&gt; ~/.bashrc\n</code></pre> <p>You\u2019ll need to regenerate the completion script any time your command structure changes.</p>"},{"location":"autocomplete/#supported-functionality","title":"Supported Functionality","text":""},{"location":"autocomplete/#bash-and-zsh","title":"Bash and Zsh","text":"<p>Currently subcommand, option, and command alias names can be completed, as well as values for options and arguments. <code>choice</code> parameters are completed with their possible values. Other parameter types are completed as file or directory names. <code>Context.allowInterspersedArgs</code> is supported.</p>"},{"location":"autocomplete/#fish","title":"Fish","text":"<p>Fish\u2019s completion mechanism is more limited that Bash\u2019s. Subcommands can be completed, options can be completed as long as they start with a <code>-</code>. Completion suggestions for positional arguments are the union of all positional arguments. Other advanced Clikt features are not supported. </p>"},{"location":"autocomplete/#customizing-completions","title":"Customizing Completions","text":"<p>There is built-in completion for values for <code>choice</code> parameters, and for parameters converted with <code>file</code> and <code>path</code>.</p> <p>You can add completion for other parameters with the <code>completionCandidates</code> parameter to <code>option()</code> and <code>argument()</code>. The value can be one of the following:</p> <ul> <li><code>None</code>: The default. The parameter\u2019s values will not be completed.</li> <li><code>Path</code>: Completions will be filesystem paths.</li> <li><code>Hostname</code>: Completions will be read from the system\u2019s hosts file.</li> <li><code>Username</code>: Completions will be taken from the system\u2019s users.</li> <li><code>Fixed</code>: Completions are given as a fixed set of strings.</li> <li><code>Custom</code>: Completions are generated from a custom script.</li> </ul>"},{"location":"autocomplete/#custom-completion-candidates","title":"<code>Custom</code> completion candidates","text":"<p>The <code>Custom</code> type takes a block that returns code to add to the script which generates completions for the given parameter.</p> <p>If you just want to call another script or binary that prints all possible completion words to stdout, you can use fromStdout.</p> <p>Both Bash and ZSH scripts use Bash\u2019s Programmable Completion system (ZSH via a comparability layer). The string returned from [generator] should be the body of a function that will be passed to <code>compgen -F</code>.</p> <p>Specifically, you should set the variable <code>COMPREPLY</code> to the completion(s) for the current word being typed. The word being typed can be retrieved from the <code>COMP_WORDS</code> array at index <code>COMP_CWORD</code>.</p> Example with fromStdoutExample with full script <pre><code>class Hello: CliktCommand() {\n    // This example uses `echo`, but you would use your own binary\n    // or script that prints the completions.\n    val name by option(completionCandidates =\n        CompletionCandidates.Custom.fromStdout(\"echo completion1 completion2\")\n    )\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>class Hello: CliktCommand() {\n    // This is identical to the previous example\n    val name by option(completionCandidates = CompletionCandidates.Custom {\n        \"\"\"\n        WORDS=${'$'}(echo completion1 completion2)\n        COMPREPLY=(${'$'}(compgen -W \"${'$'}WORDS\" -- \"${'$'}{COMP_WORDS[${'$'}COMP_CWORD]}\"))\n        \"\"\".trimIndent()\n    })\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre>"},{"location":"autocomplete/#limitations","title":"Limitations","text":"<p>Token Normalization is not supported.</p> <p>If you have arguments that occur after a <code>multiple</code> argument, those arguments won\u2019t be autocompleted. Partial command lines are ambiguous in those situations, and Clikt assumes that you\u2019re trying to complete the <code>multiple</code> argument rather than the later ones.</p> <p>Bash must be at least version 3, or Zsh must be at least version 4.1.</p>"},{"location":"changelog/","title":"Change Log","text":""},{"location":"changelog/#500","title":"5.0.0","text":""},{"location":"changelog/#added","title":"Added","text":"<ul> <li>Publish <code>iosArm64</code> and <code>iosX64</code> targets.</li> <li>Added <code>NoSuchArgument</code> exception that is thrown when too many arguments were given on the command line. Previously, a less specific <code>UsageError</code> was thrown instead.</li> <li>Added <code>CommandLineParser.tokenize</code> that splits a string into argv tokens.</li> <li>Added <code>CommandLineParser</code> that provides functions for parsing and finalizing commands manually for more control.</li> <li>Added <code>Context.invokedSubcommands</code> that contains all subcommands of the current command that are going to be invoked when <code>allowMultipleSubcommands</code> is <code>true</code>.</li> <li>Added <code>SuspendingCliktCommand</code> that has a <code>suspend fun run</code> method, allowing you to use coroutines in your commands.</li> <li>Added <code>ChainedCliktCommand</code> that allows you to return a value from your <code>run</code> method and pass it to the next command in the chain.</li> <li>Added <code>Context.data</code> as an alternative to <code>obj</code> that allows you to store more than one object in the context.</li> <li>Added <code>Context.echoer</code> to customize how <code>echo</code> messages are printed.</li> <li>Added <code>CompletionGenerator</code> to manually generate completions for a command.</li> <li>Added <code>Context.exitProcess</code> which you can use to prevent the process from exiting during tests.</li> <li>Added core module that supports watchOS, tvOS, and wasmWasi targets and has no dependencies.</li> <li>Added more options to <code>CliktCommand.test</code> to control the terminal interactivity. (#517)</li> <li>Added <code>associate{}</code>, <code>associateBy{}</code>, and <code>associateWith{}</code> transforms for options that allow you to convert the keys and values of the map.  (#529)</li> <li>Added support for aliasing options to other options. (#535)</li> <li>Added <code>limit</code> and <code>ignoreCase</code> parameters to <code>option().split()</code>. (#541)</li> <li>Support calling <code>--help</code> on subcommands when parents have required parameters.</li> </ul>"},{"location":"changelog/#changed","title":"Changed","text":"<ul> <li>In a subcommand with and an <code>argument()</code> with <code>multiple()</code> or <code>optional()</code>, the behavior is now the same regardless of the value of <code>allowMultipleSubcommands</code>: if a token matches a subcommand name, it\u2019s now treated as a subcommand rather than a positional argument.</li> <li>Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.</li> <li>Breaking Change: Moved the following parameters from <code>CliktCommand</code>\u2019s constructor; override the corresponding properties instead:</li> </ul> removed parameter replacement property <code>help</code> <code>fun help</code> <code>epilog</code> <code>fun helpEpilog</code> <code>invokeWithoutSubcommand</code> <code>val invokeWithoutSubcommand</code> <code>printHelpOnEmptyArgs</code> <code>val printHelpOnEmptyArgs</code> <code>helpTags</code> <code>val helpTags</code> <code>autoCompleteEnvvar</code> <code>val autoCompleteEnvvar</code> <code>allowMultipleSubcommands</code> <code>val allowMultipleSubcommands</code> <code>treatUnknownOptionsAsArgs</code> <code>val treatUnknownOptionsAsArgs</code> <code>hidden</code> <code>val hiddenFromHelp</code> - The following methods on <code>CliktCommand</code> have been renamed: <code>commandHelp</code> -&gt; <code>help</code>, <code>commandHelpEpilog</code> -&gt; <code>epilog</code>. The old names are deprecated. - Breaking Change: <code>CliktCommand.main</code> and <code>CliktCommand.parse</code> are now extension functions rather than methods. - Breaking Change: <code>Context.obj</code> and <code>Context.terminal</code>, and <code>OptionTransformContext.terminal</code> are now extension functions rather than properties. - Breaking Change: The <code>RenderedSection</code> and <code>DefinitionRow</code> classes have moved to <code>AbstractHelpFormatter</code>. - Markdown support in the help formatter is no longer included by default. To enable it, include the <code>:clikt-markdown</code> dependency and call <code>yourCommand.installMordantMarkdown()</code> before parsing. - Updated Kotlin to 2.0.0"},{"location":"changelog/#fixed","title":"Fixed","text":"<ul> <li>Fixed excess arguments not being reported when <code>allowMultipleSubcommands=true</code> and a subcommand has excess arguments followed by another subcommand.</li> <li>Commands with <code>printHelpOnEmptyArgs=true</code> will no longer print help if an option has a value from an environment variable or value source.  (#382)</li> </ul>"},{"location":"changelog/#deprecated","title":"Deprecated","text":"<ul> <li>Deprecated <code>Context.originalArgv</code>. It will now always return an empty list. If your commands need an argv, you can pass it to them before you run them, or set in on the new <code>Context.data</code> map.</li> <li>Deprecated <code>Context.expandArgumentFiles</code>. Use <code>Context.argumentFileReader</code> instead.</li> <li>Renamed the following <code>Context</code> fields to be more consistent. The old names are deprecated.</li> </ul> old name new name <code>Context.envvarReader</code> <code>Context.readEnvvar</code> <code>Context.correctionSuggestor</code> <code>Context.suggestTypoCorrection</code> <code>Context.argumentFileReader</code> <code>Context.readArgumentFile</code> <code>Context.tokenTransformer</code> <code>Context.transformToken</code>"},{"location":"changelog/#removed","title":"Removed","text":"<ul> <li>Removed previously deprecated experimental annotations.</li> <li>Removed <code>MordantHelpFormatter.graphemeLength</code></li> <li>Removed <code>TermUi</code></li> </ul>"},{"location":"changelog/#440","title":"4.4.0","text":""},{"location":"changelog/#added_1","title":"Added","text":"<ul> <li>Publish <code>linuxArm64</code> and <code>wasmJs</code> targets.</li> </ul>"},{"location":"changelog/#430","title":"4.3.0","text":""},{"location":"changelog/#added_2","title":"Added","text":"<ul> <li>Added <code>limit</code> parameter to <code>option().counted()</code> to limit the number of times the option can be used. You can either clamp the value to the limit, or throw an error if the limit is exceeded. (#483)</li> <li>Added <code>Context.registerClosable</code> and <code>Context.callOnClose</code> to allow you to register cleanup actions that will be called when the command exits. (#395)</li> </ul>"},{"location":"changelog/#fixed_1","title":"Fixed","text":"<ul> <li>Fixed <code>unrecognized modifier 'i'</code> that happened on tab-completion when using sub command aliases. Thanks to @hick209 for the contribution. (#500)</li> <li>Make sure auto complete script works on zsh, fixing the error <code>complete:13: command not found: compdef</code>. Thanks to @hick209 for the contribution. (#499)</li> </ul>"},{"location":"changelog/#422","title":"4.2.2","text":""},{"location":"changelog/#changed_1","title":"Changed","text":"<ul> <li>Options and arguments can now reference option groups in their <code>defaultLazy</code> and other finalization blocks. They can also freely reference each other, including though chains of references. (#473)</li> <li>Updated Kotlin to 1.9.21 (#472)</li> </ul>"},{"location":"changelog/#421","title":"4.2.1","text":""},{"location":"changelog/#added_3","title":"Added","text":"<ul> <li>Added <code>toString</code> implementations to options and arguments. (#434)</li> <li>Added <code>CliktCommand.test</code> overload that takes a vararg of <code>String</code>s as the command line arguments. Thanks to @sschuberth for the contribution (#451)</li> </ul>"},{"location":"changelog/#fixed_2","title":"Fixed","text":"<ul> <li>Update Mordant dependency to fix crashes on native targets and GraalVM (#447)</li> </ul>"},{"location":"changelog/#420","title":"4.2.0","text":""},{"location":"changelog/#added_4","title":"Added","text":"<ul> <li>Added <code>requireConfirmation</code> parameter to <code>option().prompt()</code> (#426)</li> <li>Added <code>CliktCommand.terminal</code> extension for accessing the terminal from a command.</li> <li>Added <code>includeSystemEnvvars</code>, <code>ansiLevel</code>, <code>width</code>, and <code>height</code> parameters to all <code>CliktCommand.test</code> overloads.</li> </ul>"},{"location":"changelog/#deprecated_1","title":"Deprecated","text":"<ul> <li>Deprecated <code>CliktCommand.prompt</code>, use <code>CliktCommand.terminal.prompt</code> or <code>Prompt</code> instead.</li> <li>Deprecated <code>CliktCommand.confirm</code>, use <code>YesNoPrompt</code> instead.</li> </ul>"},{"location":"changelog/#fixed_3","title":"Fixed","text":"<ul> <li>Fixed incorrect error message when a <code>defaultLazy</code> option referenced a <code>required</code> option. (#430)</li> </ul>"},{"location":"changelog/#410","title":"4.1.0","text":""},{"location":"changelog/#added_5","title":"Added","text":"<ul> <li>Added <code>MordantHelpFormatter.renderAttachedOptionValue</code> that you can override to change how option values are shown, e.g. if you want option to show as <code>--option &lt;value&gt;</code> instead of <code>--option=&lt;value&gt;</code>. (#416)</li> <li>Added <code>option().optionalValueLazy{}</code>, which work like <code>optionalValue()</code> but the default value is computed lazily. (#381)</li> </ul>"},{"location":"changelog/#changed_2","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.9.0</li> <li><code>PrintMessage</code>, <code>PrintHelpMessage</code> and <code>PrintCompletionMessage</code> now default to exiting with a status code 0, which is the behavior they had in 3.x. (#419)</li> </ul>"},{"location":"changelog/#400","title":"4.0.0","text":""},{"location":"changelog/#added_6","title":"Added","text":"<ul> <li>Added <code>Context.errorEncountered</code> which is true if parsing has continued after an error was encountered.</li> <li><code>option().help{\"\"}</code> and <code>argument().help{\"\"}</code> extensions that set the parameter\u2019s help text lazily, with access to the current context so that you can add colors.</li> </ul>"},{"location":"changelog/#changed_3","title":"Changed","text":"<ul> <li><code>Option.optionHelp</code> and <code>Argument.argumentHelp</code>, <code>CliktCommand.commandHelp</code>, and <code>CliktCommand.commandHelpEpilog</code> are now methods that take the context as an argument, and the <code>help</code> parameter to <code>copy</code> is now a <code>helpGetter</code> lambda. <code>CliktCommand.shortHelp</code> now takes the context as an argument.</li> <li>The <code>message</code> method on <code>TransformContext</code> interfaces is now an extension.</li> </ul>"},{"location":"changelog/#deprecated_2","title":"Deprecated","text":"<ul> <li>Deprecated <code>CliktCommand.commandHelp</code> and <code>commandHelpEpilog</code> properties in favor of the methods with the same name.</li> </ul>"},{"location":"changelog/#400-rc","title":"4.0.0-RC","text":""},{"location":"changelog/#added_7","title":"Added","text":"<ul> <li>You can now use markdown in your help strings, including tables and lists. Clikt uses the Mordant library for rendering.</li> <li>Help output and error messages now include colors by default. You can disable this or customize the styling by configuring the <code>context.terminal</code></li> <li>Added <code>Option.varargValues()</code> to create an option that accepts a variable number of values</li> <li>Added <code>Option.optionalValue()</code> to create an option whose value is optional.</li> <li>Added <code>obj</code> setter to context builder as an alternative to <code>currentContext.obj</code></li> <li>Added <code>boolean()</code> parameter type conversions.</li> <li>Added <code>uint()</code> and <code>ulong()</code> parameter type conversions.</li> <li>Added <code>nullableFlag()</code> parameter transformation.</li> <li>Added <code>CliktCommand.test</code> extension for testing your commands and their output</li> <li>Clikt will now report multiple errors if they occur via the new <code>MultiUsageError</code> exception, rather than just reporting the first error. (#367)</li> <li>Added <code>CliktCommand.allHelpParams()</code>, which can be overridden to change which parameters are displayed in help output</li> <li>Added <code>Context.argumentFileReader</code> which allows custom loading of argument files</li> <li>Added <code>Context.allowGroupedShortOptions</code> which can disable parsing <code>-abc</code> as <code>-a -b -c</code></li> <li>Options named <code>-?</code> or <code>/?</code> are now supported</li> <li>Added <code>option(eager=true)</code> to create an eager option that takes values</li> <li>Added <code>option(acceptsUnattachedValue=false)</code> to force the option to only accept values like <code>--option=1</code> and not <code>--option 1</code></li> <li>Added <code>CliktCommand.test()</code> that captures the output of a command and does not exit the process.</li> </ul>"},{"location":"changelog/#removed_1","title":"Removed","text":"<ul> <li>Removed <code>CliktConsole</code>. Mordant is now used for all input and output. If you were defining a custom console, instead define a mordant <code>TerminalInterface</code> and set it on your context\u2019s <code>Terminal</code>.</li> <li>Removed <code>TermUi.echo</code>, <code>TermUi.prompt</code>, and <code>TermUi.confirm</code>. Use the equivalent methods on your <code>CliktCommand</code>, or use mordant\u2019s prompts directly.</li> <li>Removed legacy JS publications. Now only the JS/IR artifacts are published.</li> <li>Removed <code>CliktHelpFormatter</code>. Use <code>MordantHelpFormatter</code> instead.</li> <li>Removed <code>FlagOption</code> and <code>EagerOption</code> classes. All options are now implemented as transformations on <code>OptionWithValues</code>. <code>FlagOption</code> is now <code>OptionWithValues&lt;Boolean, Boolean, Boolean&gt;</code>.</li> </ul>"},{"location":"changelog/#changed_4","title":"Changed","text":"<ul> <li><code>prompt</code> and <code>confirm</code> are now implemented with mordant\u2019s prompt functionality, and the method parameters have changed to match mordant\u2019s</li> <li>When using <code>treatUnknownOptionsAsArgs</code>, grouped short options like <code>-abc</code> will be treated as an argument rather than reporting an error as long as they don\u2019t match any short options in the command. (#340)</li> <li>Clikt no longer automatically calls <code>trimIndent</code> on strings passed to <code>help</code>. Call <code>trimIndent</code> or <code>trimMargin</code> yourself if necessary.</li> <li><code>Context.Builder.helpOptionNames</code> now accepts any iterable rather than just a set.</li> <li><code>CliktCommand.echo</code> and <code>prompt</code> are now public. (#407)</li> <li>Internally, all options are implemented transformations on <code>OptionWithValues</code>, rather than using separate classes for each option type. </li> <li>Some Localization strings have changed, removed <code>Localization.aborted()</code>, added <code>Localization.argumentsMetavar()</code></li> <li><code>Context.Builder.helpFormatter</code> is now a lambda that takes the current context as an argument</li> <li>Exceptions have been reworked so that all exceptions thrown by Clikt are subclasses of <code>CliktError</code>.</li> <li><code>CliktError</code> now includes <code>statusCode</code> and <code>printError</code> properties.</li> <li>The constructor of <code>UsageError</code> and its subclasses no longer takes a <code>context</code> parameter. The context is now inferred automatically.</li> <li><code>UsageError.formatUsage</code> now takes the localization and formatter as arguments</li> </ul>"},{"location":"changelog/#fixed_4","title":"Fixed","text":"<ul> <li>When parsing a command line with more than one error, Clikt will now always report the error that occurs earliest if it can\u2019t report them all (#361)</li> <li>When <code>treatUnknownOptionsAsArgs</code> is true, grouped unknown short options will now be treated as arguments rather than reporting an error.</li> </ul>"},{"location":"changelog/#354","title":"3.5.4","text":""},{"location":"changelog/#fixed_5","title":"Fixed","text":"<ul> <li>Revert jvm jars to target Java 8</li> </ul>"},{"location":"changelog/#353","title":"3.5.3","text":""},{"location":"changelog/#changed_5","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.8.22</li> </ul>"},{"location":"changelog/#fixed_6","title":"Fixed","text":"<ul> <li>Context is now set properly on NoSuchOption exceptions when thrown from subcommands. (#399)</li> <li>When <code>treatUnknownOptionsAsArgs</code> is true, grouped unknown short options will now be treated as arguments rather than reporting an error.</li> </ul>"},{"location":"changelog/#352","title":"3.5.2","text":""},{"location":"changelog/#changed_6","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.8.10</li> </ul>"},{"location":"changelog/#fixed_7","title":"Fixed","text":"<ul> <li>Fix <code>CliktCommand.prompt</code> on NodeJS targets that would hang due to KT-55817 (#387)</li> </ul>"},{"location":"changelog/#351","title":"3.5.1","text":""},{"location":"changelog/#changed_7","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.7.20</li> </ul>"},{"location":"changelog/#fixed_8","title":"Fixed","text":"<ul> <li>Support unicode in environment variable values on Native Windows. (#362)</li> <li>Support environment variables for options in a mutually exclusive options group. (#384)</li> </ul>"},{"location":"changelog/#350","title":"3.5.0","text":""},{"location":"changelog/#added_8","title":"Added","text":"<ul> <li>Added <code>hidden</code> parameter to <code>CliktCommand</code>, which will prevent the command from being displayed as a subcommand in help output  (#353)</li> <li>Publish artifacts for the <code>macosArm64</code> target. Note that this target is not tested on CI. (#352)</li> </ul>"},{"location":"changelog/#changed_8","title":"Changed","text":"<ul> <li>Default values for arguments will now be included in help output when <code>showDefaultValues=true</code> is set on your help formatter (#357)</li> </ul>"},{"location":"changelog/#fixed_9","title":"Fixed","text":"<ul> <li>Fix flags and other options with defaults not being usable in <code>mutuallyExclusiveOptions</code> (#349)</li> <li>Fix <code>CompletionCommand</code> generating completion for itself (#355)</li> </ul>"},{"location":"changelog/#342","title":"3.4.2","text":""},{"location":"changelog/#deprecated_3","title":"Deprecated","text":"<ul> <li><code>TermUi.echo</code>, <code>TermUi.prompt</code>, and <code>TermUi.confirm</code>. Use the equivalent methods on <code>CliktCommand</code> instead. (#344)</li> </ul>"},{"location":"changelog/#341","title":"3.4.1","text":""},{"location":"changelog/#added_9","title":"Added","text":"<ul> <li>Added <code>obj</code> setter to context builder as an alternative to <code>currentContext.obj</code></li> <li>Added <code>option().boolean()</code> and <code>argument().boolean()</code></li> <li><code>uint()</code> and <code>ulong()</code> parameter type conversions.</li> <li><code>CliktCommand.test</code> extension for testing your commands and their output</li> </ul>"},{"location":"changelog/#changed_9","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.6.20</li> </ul>"},{"location":"changelog/#340","title":"3.4.0","text":""},{"location":"changelog/#changed_10","title":"Changed","text":"<ul> <li><code>unique()</code> now works with any option with a list type, not just <code>multiple()</code> options (#332)</li> <li>Updated Kotlin to 1.6.10</li> </ul>"},{"location":"changelog/#fixed_10","title":"Fixed","text":"<ul> <li>Fixed co-occurring option groups returning null when all options in the group are defined in environment variables (#330)</li> </ul>"},{"location":"changelog/#330","title":"3.3.0","text":""},{"location":"changelog/#added_10","title":"Added","text":"<ul> <li>Added <code>default</code> parameter to <code>argument().multiple()</code> (#305)</li> <li><code>Context.originalArgv</code> that allows you to read the command line arguments from within a command\u2019s <code>run</code> (#290)</li> <li><code>context { envarReader = {...} }</code> to set a custom function to read from environment variables (#299)</li> </ul>"},{"location":"changelog/#changed_11","title":"Changed","text":"<ul> <li><code>defaultLazy</code> values can now reference other parameters, as long the referenced parameters do not also reference other parameters</li> <li>You can now call <code>CliktCommand.context</code> multiple times on the same command, and all builder blocks will be applied </li> <li>Validate values entered to a <code>prompt</code> option, and show another prompt if the validation fails (#288)</li> <li>Updated kotlin to 1.5.31</li> </ul>"},{"location":"changelog/#fixed_11","title":"Fixed","text":"<ul> <li>Report error when excess arguments are given to a command with <code>allowMultipleSubcommands=true</code> (#303)</li> </ul>"},{"location":"changelog/#320","title":"3.2.0","text":""},{"location":"changelog/#added_11","title":"Added","text":"<ul> <li><code>InputStream.isCliktParameterDefaultStdin</code> and <code>OutputStream.isCliktParameterDefaultStdout</code> to check if the streams returned from <code>inputStream</code>/<code>outputStream</code> options are proxying stdin/stdout (#272)</li> </ul>"},{"location":"changelog/#changed_12","title":"Changed","text":"<ul> <li>Make parameters of <code>mutuallyExclusiveOptions</code> covariant to allow validation without explicit type annotations. (#265)</li> <li>Updated kotlin to 1.5.0</li> </ul>"},{"location":"changelog/#fixed_12","title":"Fixed","text":"<ul> <li>Reading from an option or argument property on a command that hasn\u2019t been invoked will now always throw an <code>IllegalStateException</code></li> </ul>"},{"location":"changelog/#310","title":"3.1.0","text":""},{"location":"changelog/#added_12","title":"Added","text":"<ul> <li>Added <code>required()</code> and <code>defaultLazy()</code> for nullable flag options like <code>switch()</code>. (#240)</li> <li>Added support for generating autocomplete scripts for Fish shells (#189)</li> <li>Added <code>CompletionCommand</code> and <code>CliktCommand.completionOption()</code> that will print an autocomplete script when invoked, as an alternative to using environment variables.</li> </ul>"},{"location":"changelog/#changed_13","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.4.21</li> <li><code>@argfiles</code> now allow line breaks in quoted values, which are included in the value verbatim. You can now end lines with <code>\\</code> to concatenate them with the following line. (#248)</li> </ul>"},{"location":"changelog/#301","title":"3.0.1","text":""},{"location":"changelog/#deprecated_4","title":"Deprecated","text":"<ul> <li>Deprecated calling <code>echo</code> with <code>err</code> or <code>lineSeparator</code> but no <code>message</code>. </li> </ul>"},{"location":"changelog/#300","title":"3.0.0","text":""},{"location":"changelog/#added_13","title":"Added","text":"<ul> <li>Clikt\u2019s JS target now supports both NodeJS and Browsers. (#198)</li> <li>Default values for switch options are now shown in the help. Help text can be customized using the <code>defaultForHelp</code> argument, similar to normal options. (#205)</li> <li>Added <code>FlagOption.convert</code> (#208)</li> <li>Added ability to use unicode NEL character (<code>\\u0085</code>) to manually break lines in help output (#214)</li> <li>Added <code>help(\"\")</code> extension to options and arguments as an alternative to passing the help as an argument (#207)</li> <li>Added <code>valueSourceKey</code> parameter to <code>option</code></li> <li>Added <code>check()</code> extensions to options and arguments as an alternative to <code>validate()</code></li> <li>Added <code>prompt</code> and <code>confirm</code> functions to <code>CliktCommand</code> that call the <code>TermUi</code> equivalents with the current console.</li> <li>Added <code>echo()</code> overload with no parameters to CliktCommand that prints a newline by itself.</li> <li>Added localization support. You can set an implementation of the <code>Localization</code> interface on your context with your translations. (#227)</li> </ul>"},{"location":"changelog/#fixed_13","title":"Fixed","text":"<ul> <li>Hidden options will no longer be suggested as possible typo corrections. (#202)</li> <li>Options and Arguments with <code>multiple(required=true)</code> will now show as required in help output. (#212)</li> <li>Multiple short lines in a help text paragraph no longer appear dedented (#215)</li> </ul>"},{"location":"changelog/#changed_14","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.4.0</li> <li><code>Argument.help</code> and <code>Option.help</code> properties have been renamed to <code>argumentHelp</code> and <code>optionHelp</code>, respectively. The <code>help</code> parameter names to <code>option()</code> and <code>argument()</code> are unchanged.</li> <li><code>commandHelp</code> and <code>commandHelpEpilog</code> properties on <code>CliktCommand</code> are now <code>open</code>, so you can choose to override them instead of passing <code>help</code> and <code>epilog</code> to the constructor.</li> <li>Replaced <code>MapValueSource.defaultKey</code> with <code>ValueSource.getKey()</code>, which is more customizable.</li> <li><code>Option.metavar</code>, <code>Option.parameterHelp</code>, <code>OptionGroup.parameterHelp</code> and <code>Argument.parameterHelp</code> properties are now functions.</li> <li>Changed constructor parameters of <code>CliktHelpFormatter</code>. Added <code>localization</code> and removed <code>usageTitle</code>, <code>optionsTitle</code>, <code>argumentsTitle</code>, <code>commandsTitle</code>, <code>optionsMetavar</code>, and <code>commandMetavar</code>. Those strings are now defined on equivalently named functions on <code>Localization</code>.</li> </ul>"},{"location":"changelog/#removed_2","title":"Removed","text":"<ul> <li>Removed <code>envvarSplit</code> parameter from <code>option()</code> and <code>convert()</code>. Option values from environment variables are no longer split automatically. (#177)</li> <li>Removed public constructors from the following classes: <code>ProcessedArgument</code>, <code>OptionWithValues</code>, <code>FlagOption</code>, <code>CoOccurringOptionGroup</code>, <code>ChoiceGroup</code>, <code>MutuallyExclusiveOptions</code>.</li> <li><code>MissingParameter</code> exception replaced with <code>MissingOption</code> and <code>MissingArgument</code></li> <li>Removed <code>Context.helpOptionMessage</code>. Override <code>Localization.helpOptionMessage</code> and set it on your context instead.</li> </ul>"},{"location":"changelog/#deprecated_5","title":"Deprecated","text":"<ul> <li><code>@ExperimentalCompletionCandidates</code> and <code>@ExperimentalValueSourceApi</code> annotations. These APIs no longer require an opt-in.</li> </ul>"},{"location":"changelog/#280","title":"2.8.0","text":""},{"location":"changelog/#added_14","title":"Added","text":"<ul> <li>Added <code>error</code> parameter to <code>PrintMessage</code> and <code>PrintHelpMessage</code>. When <code>true</code>, <code>CliktCommand.main</code> will exit with status code 1. (#187)</li> </ul>"},{"location":"changelog/#changed_15","title":"Changed","text":"<ul> <li>When <code>printHelpOnEmptyArgs</code> is <code>true</code> and no arguments are present, or when <code>invokeWithoutSubcommand</code> is <code>false</code> and no subcommand is present, <code>CliktCommand.main</code> will now exit with status code 1 rather than 0. </li> <li><code>restrictTo</code> now works with any <code>Comparable</code> value, not just <code>Number</code>.</li> <li><code>CliktCommand.main</code> now accepts <code>Array&lt;out String&gt;</code>, not just <code>Array&lt;String&gt;</code>. (#196)</li> </ul>"},{"location":"changelog/#fixed_14","title":"Fixed","text":"<ul> <li>Fixed option values being reset when calling multiple subcommands with <code>allowMultipleSubcommands=true</code> (#190)</li> </ul>"},{"location":"changelog/#271","title":"2.7.1","text":""},{"location":"changelog/#fixed_15","title":"Fixed","text":"<ul> <li>Fixed NPE thrown in some cases when using <code>defaultByName</code> (#179)</li> </ul>"},{"location":"changelog/#270","title":"2.7.0","text":""},{"location":"changelog/#added_15","title":"Added","text":"<ul> <li>Ability to use custom program exit status codes via <code>ProgramResult</code>.</li> <li><code>inputStream</code> and <code>outputStream</code> conversions for options and arguments. (#157 and #159)</li> <li><code>splitPair</code>, <code>toMap</code>, and <code>associate</code> extensions on <code>option</code>. (#166)</li> <li><code>treatUnknownOptionsAsArgs</code> parameter to <code>CliktCommand</code>. (#152)</li> <li><code>defaultByName</code> function for <code>groupChoice</code> and <code>groupSwitch</code> options. (#171)</li> </ul>"},{"location":"changelog/#changed_16","title":"Changed","text":"<ul> <li>Update Kotlin to 1.3.71</li> <li>Improved command name inference. Now, a class like <code>MyAppCommand</code> will infer its <code>commandName</code> as <code>my-app</code> rather than <code>myappcommand</code>. You can still specify the name manually as before. (#168)</li> </ul>"},{"location":"changelog/#fixed_16","title":"Fixed","text":"<ul> <li>Correctly parse short options with attached values that contain <code>=</code></li> </ul>"},{"location":"changelog/#260","title":"2.6.0","text":""},{"location":"changelog/#added_16","title":"Added","text":"<ul> <li><code>registeredSubcommands</code>, <code>registeredOptions</code>, <code>registeredArguments</code>, and <code>registeredParameterGroups</code> methods on <code>CliktCommand</code>.</li> <li>Ability to read default option values from configuration files and other sources. Support for Java property files is built in on JVM, see the <code>json</code> sample for an example of reading from other formats.</li> <li><code>allowMultipleSubcommands</code> parameter to <code>CliktCommand</code> that allows you to pass multiple subcommands in the same call. (docs)</li> <li>Errors from typos in subcommand names will now include suggested corrections. Corrections for options and subcommands are now based on a Jaro-Winkler similarity metric, and can be customized with <code>Context.correctionSuggestor</code></li> </ul>"},{"location":"changelog/#changed_17","title":"Changed","text":"<ul> <li>Update Kotlin to 1.3.70</li> <li><code>convert</code> can be called more than once on the same option or argument, including after calls to conversion functions like <code>int</code> and <code>file</code>.</li> <li><code>CliktCommand.toString</code> now includes the class name</li> <li>Reverted automatic <code>~</code> expansion in <code>file()</code> and <code>path()</code> introduced in 2.5.0. If you need this behavior, you can implement it with code like <code>convert { /* expand tidle */ }.file()</code> </li> </ul>"},{"location":"changelog/#deprecated_6","title":"Deprecated","text":"<ul> <li><code>wrapValue</code> is now deprecated, since <code>convert</code> can be used in its place instead.</li> </ul>"},{"location":"changelog/#250","title":"2.5.0","text":""},{"location":"changelog/#added_17","title":"Added","text":"<ul> <li>Clikt is now available as a Kotlin Multiplatform Project, supporting JVM, NodeJS, and native Windows, Linux, and macOS.</li> <li><code>eagerOption {}</code> function to more easily register eager options.</li> <li>Eager options can now be added to option groups in help out by passing a value for <code>groupName</code> when creating them. </li> <li><code>canBeSymlink</code> parameter to <code>file()</code> and <code>path()</code> conversions that can be used to disallow symlinks</li> <li><code>CliktCommand.eagerOption</code> to simplify creating custom eager options</li> </ul>"},{"location":"changelog/#changed_18","title":"Changed","text":"<ul> <li>The parameter names of <code>file()</code> and <code>path()</code> conversions have changed. The existing names are deprecated, and can be converted to the new usages with an IntelliJ inspection. Note that if you are calling these functions with unnamed arguments (e.g. <code>file(true, false)</code>), you\u2019ll need to add argument names in order to remove the deprecation warning.</li> </ul>"},{"location":"changelog/#deprecated_7","title":"Deprecated","text":"<ul> <li>The <code>CliktCommand.context</code> property has been deprecated in favor of the new name, <code>currentContext</code>, to avoid confusion with the <code>CliktCommand.context{}</code> method.</li> <li><code>NoRunCliktCommand</code> was renamed to <code>NoOpCliktCommand</code>. The existing class is deprecated. (#130)</li> </ul>"},{"location":"changelog/#fixed_17","title":"Fixed","text":"<ul> <li><code>file()</code> and <code>path()</code> conversions will now properly expand leading <code>~</code> in paths to the home directory for <code>mustExist</code>, <code>canBeFile</code>, and <code>canBeDir</code> checks. The property value is unchanged, and can still begin with a <code>~</code>. (#131)</li> </ul>"},{"location":"changelog/#240","title":"2.4.0","text":""},{"location":"changelog/#added_18","title":"Added","text":"<ul> <li><code>CompletionCandidates.Fixed</code> now has a secondary convenience constructor that take a <code>vararg</code> of <code>String</code>s</li> <li><code>CompletionCadidates.Custom</code>, which allows you to call other binaries or write a script to generate completions. This class is currently experimental. (#79)</li> <li><code>Option.wrapValue</code> and <code>Argument.wrapValue</code> to make it easier to reuse existing conversion functions.</li> <li><code>ignoreCase</code> parameter to <code>choice()</code> and <code>enum()</code> conversion functions.</li> </ul>"},{"location":"changelog/#changed_19","title":"Changed","text":"<ul> <li><code>option()</code> and <code>argument()</code> now take optional <code>completionCandidates</code> parameters to override how completion is generated. The constructor and <code>copy</code> functions of <code>OptionsWithValues</code> and <code>ProcessedArgument</code> have changed to support default values.</li> <li>The overloads of <code>findObject</code> (1 2) that take a default value have been renamed <code>findOrSetObject</code>. The existing names are marked with <code>@Deprecated</code>, and IntelliJ can convert your call sites automatically. (#110)</li> <li><code>enum()</code> parameters now accept case-insensitive values by default. You change this behavior by passing <code>ignoreCase = false</code> to <code>enum()</code> (#115)</li> </ul>"},{"location":"changelog/#fixed_18","title":"Fixed","text":"<ul> <li><code>groupChoice</code> help output now includes the choices in the help output metavar</li> <li><code>TermUi.edit*</code> functions could freeze on certain editors (#99, thanks @iampravikant and @sebokopter)</li> <li>Shell completion can now handle command names with dashes. (#104)</li> <li>Arguments with <code>=</code> in them could be incorrectly interpreted as options (#106)</li> </ul>"},{"location":"changelog/#230","title":"2.3.0","text":""},{"location":"changelog/#added_19","title":"Added","text":"<ul> <li><code>option().groupSwitch()</code>, which works like <code>groupChoice()</code>, but uses a <code>switch()</code> option rather than a <code>choice()</code> option.</li> <li><code>UsageError</code> now has a <code>statusCode</code> parameter (which defaults to 1). If you\u2019re using <code>ClicktCommand.main</code>, the value of <code>statusCode</code> will be passed to <code>exitProcess</code>. </li> </ul>"},{"location":"changelog/#changed_20","title":"Changed","text":"<ul> <li>Shell completion code is now printed by throwing a <code>PrintCompletionMessage</code> (a subclass of <code>PrintMessage</code>) rather than calling <code>echo</code> directly.</li> </ul>"},{"location":"changelog/#220","title":"2.2.0","text":""},{"location":"changelog/#added_20","title":"Added","text":"<ul> <li>Added <code>enum()</code> conversion for options and arguments. (#84)</li> </ul>"},{"location":"changelog/#changed_21","title":"Changed","text":"<ul> <li>There are now several ways of preventing @-file expansion</li> </ul>"},{"location":"changelog/#fixed_19","title":"Fixed","text":"<ul> <li>Help output missing items when no help text is specified. (#85)</li> <li>Help output not grouping options in groups passed to <code>groupChoice</code>. (#88)</li> </ul>"},{"location":"changelog/#210","title":"2.1.0","text":""},{"location":"changelog/#added_21","title":"Added","text":"<ul> <li>Ability to prevent rewrapping individual paragraphs in help output.</li> <li>Added parameter <code>required</code> to <code>Option.multiple()</code> to require at least one instance of the option on the command line.</li> </ul>"},{"location":"changelog/#changed_22","title":"Changed","text":"<ul> <li><code>CliktCommand.toString()</code> now includes the names and values of all parameters and subcommands.</li> </ul>"},{"location":"changelog/#fixed_20","title":"Fixed","text":"<ul> <li>Create subcommand context when <code>helpOptionNames</code> is empty. (#64)</li> </ul>"},{"location":"changelog/#200","title":"2.0.0","text":""},{"location":"changelog/#added_22","title":"Added","text":"<ul> <li>Bash autocomplete script generation. A property named <code>completionCandidates</code> has been added to <code>Argument</code> and <code>Option</code> interfaces, and corresponding parameters have been added to the various implementation constructors, as well as the <code>convert</code> functions. You can use this to control the values autocomplete that will be suggested.</li> <li><code>option().split()</code>, and the corresponding <code>OptionWithValues.valueSplit</code>.</li> <li>Marking options as deprecated with <code>option().deprecated()</code></li> <li>You can manually set the pattern to split envvars on by passing a pattern to the <code>envvarSplit</code> parameter of <code>option()</code></li> <li>Option groups, mutually exclusive groups, co-occurring groups, and choice options with groups</li> <li>Support for Command line argument files a.k.a. \u201c@-files\u201d</li> </ul>"},{"location":"changelog/#changed_23","title":"Changed","text":"<ul> <li>If multiple <code>--</code> tokens are present on the command line, all subsequent occurrences after the first are now parsed as positional arguments. Previously, subsequent <code>--</code> tokens were skipped.  </li> <li>The <code>PlaintextHelpFormatter</code> has been replaced with <code>CliktHelpFormatter</code>, which is more customizable. See the docs for more info, or the new sample for an example of customizing help output to use ANSI colors.</li> <li>Some of the properties and constructor parameters for <code>OptionWithValues</code> and <code>ProcessedArgument</code> have changed.</li> <li>The <code>OptionDelegate</code> interface has changed, and <code>GroupableOption</code> and <code>ParameterHolder</code> interfaces have been added to work with option groups.</li> <li>Parameter validation now occurs after all parameter delegates have set their values, so the lambdas passed to <code>validate</code> may reference other parameters. </li> </ul>"},{"location":"changelog/#170","title":"1.7.0","text":""},{"location":"changelog/#added_23","title":"Added","text":"<ul> <li><code>printHelpOnEmptyArgs</code> parameter to <code>CliktCommand</code> constructor. (#41)</li> </ul>"},{"location":"changelog/#fixed_21","title":"Fixed","text":"<ul> <li>Usage errors now correctly print subcommand names. (#47)</li> <li>Arguments with <code>multiple(required=true)</code> now report an error if no argument is given on the command line. (#36)</li> </ul>"},{"location":"changelog/#160","title":"1.6.0","text":""},{"location":"changelog/#added_24","title":"Added","text":"<ul> <li><code>.multiple().unique()</code> modifier for options and arguments.</li> </ul>"},{"location":"changelog/#fixed_22","title":"Fixed","text":"<ul> <li>Support multi-line input when redirecting stdin</li> </ul>"},{"location":"changelog/#150","title":"1.5.0","text":""},{"location":"changelog/#added_25","title":"Added","text":"<ul> <li>Ability to use alternate output streams rather than stdin and stdout by setting <code>Context.console</code> or by passing a console to <code>TermUI</code> functions.</li> </ul>"},{"location":"changelog/#140","title":"1.4.0","text":""},{"location":"changelog/#added_26","title":"Added","text":"<ul> <li><code>path()</code> type for parameter values</li> </ul>"},{"location":"changelog/#changed_24","title":"Changed","text":"<ul> <li>Clikt now targets JVM 8 bytecode</li> <li>Responses to <code>TermUi.confirm()</code> are now case-insensitive</li> </ul>"},{"location":"changelog/#130","title":"1.3.0","text":""},{"location":"changelog/#added_27","title":"Added","text":"<ul> <li><code>defaultLazy</code> extension for options and arguments</li> </ul>"},{"location":"changelog/#changed_25","title":"Changed","text":"<ul> <li><code>main</code> now prints messages to stderr instead of stdout</li> </ul>"},{"location":"changelog/#fixed_23","title":"Fixed","text":"<ul> <li>Parameter help messages are now wrapped more consistently</li> </ul>"},{"location":"changelog/#120","title":"1.2.0","text":""},{"location":"changelog/#added_28","title":"Added","text":"<ul> <li>Default parameter to <code>option().default()</code></li> </ul>"},{"location":"changelog/#changed_26","title":"Changed","text":"<ul> <li>Treat tokens with unknown prefixes as arguments (this makes it easier   to pass in file paths without using <code>--</code>).</li> </ul>"},{"location":"changelog/#110","title":"1.1.0","text":""},{"location":"changelog/#added_29","title":"Added","text":"<ul> <li><code>List&lt;String&gt;</code> overloads to <code>CliktCommand.parse</code> and <code>main</code></li> <li><code>err</code> parameter to <code>TermUi.echo</code></li> <li><code>error</code> property to <code>Abort</code></li> </ul>"},{"location":"commands/","title":"Commands","text":"<p>Clikt supports arbitrarily nested commands. You can add one command as a child of another with the <code>subcommands</code> function, which can be called either in an <code>init</code> block, or on an existing instance.</p>"},{"location":"commands/#executing-nested-commands","title":"Executing Nested Commands","text":"<p>For commands with no children, <code>run</code> is called whenever the command line is parsed (unless parsing is aborted from an error or an option like <code>--help</code>).</p> <p>If a command has children, this isn\u2019t the case. Instead, its <code>run</code> is called only if a child command is invoked, just before the subcommand\u2019s <code>run</code>. If a parent command is called without specifying a subcommand, the help page is printed and <code>run</code> is not called.</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    val verbose by option().flag(\"--no-verbose\")\n    override fun run() {\n        echo(\"Verbose mode is ${if (verbose) \"on\" else \"off\"}\")\n    }\n}\n\nclass Execute : CliktCommand() {\n    override fun run() {\n        echo(\"executing\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  --verbose / --no-verbose\n  -h, --help                Show this message and exit\n\nCommands:\n  execute\n</code></pre> <pre><code>$ ./tool --verbose execute\nVerbose mode is on\nexecuting\n</code></pre>"},{"location":"commands/#customizing-command-name","title":"Customizing Command Name","text":"<p>The default name for subcommands is inferred as a lowercase name from the command class name. You can also set a name manually in the <code>CliktCommand</code> constructor.</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    override fun run()= Unit\n}\n\nclass Execute : CliktCommand(name = \"RUN-ME\") {\n    override fun run() {\n        echo(\"executing\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool RUN-ME\nexecuting\n</code></pre> <pre><code>$ ./tool -h\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  -h, --help  Show this message and exit\n\nCommands:\n  RUN-ME\n</code></pre>"},{"location":"commands/#passing-parameters","title":"Passing Parameters","text":"<p>When calling subcommands, the position of options and arguments on the command line affect which command will parse them. A parameter is parsed by a command if it occurs after the command name, but before any other command names.</p> ExampleUsage <pre><code>class Tool : CliktCommand() {\n    override fun help(context: Context) = \"A tool that runs\"\n    val verbose by option().flag(\"--no-verbose\")\n    override fun run() = Unit\n}\n\nclass Execute : CliktCommand() {\n    override fun help(context: Context) = \"Execute the command\"\n    val name by option()\n    override fun run() = Unit\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\n  A tool that runs\n\nOptions:\n  --verbose / --no-verbose\n  -h, --help                Show this message and exit\n\nCommands:\n  execute  Execute the command\n</code></pre> <p>If you instead execute <code>--help</code> after the subcommand, the subcommand\u2019s help is printed:</p> <pre><code>$ ./tool execute --help\nUsage: execute [&lt;options&gt;]\n\n  Execute the command\n\nOptions:\n  --name &lt;text&gt;\n  -h, --help   Show this message and exit\n</code></pre> <p>But executing <code>./tool --help execute</code>, with the option before the subcommand, will cause the parent\u2019s help option to be invoked, printing out <code>Tool</code>\u2019s help page as if you just typed <code>./tool --help</code>.</p>"},{"location":"commands/#nested-handling-and-contexts","title":"Nested Handling And Contexts","text":"<p>Normally nested command are independent of each other: a child can\u2019t access its parent\u2019s parameters. This makes composing commands much easier, but what if you want to pass information to a child command? You can do so with the command\u2019s <code>Context</code>.</p> <p>Every time the command line is parsed, each command creates a new context object for itself that is linked to its parent\u2019s context. <code>Context</code> objects have a number of properties that can be used to customize command line parsing. Although each command creates its own context, the configuration is inherited from the parent context.</p> <p><code>Context</code> objects also have a [<code>data</code>][Context.data] map and <code>obj</code> property that hold objects that can be accessed from child commands.</p> ExampleUsage <pre><code>data class MyConfig(var verbose: Boolean = false)\n\nclass Tool : CliktCommand() {\n    val verbose by option().flag(\"--no-verbose\")\n    val config by findOrSetObject { MyConfig() }\n    override fun run() {\n        config.verbose = if (verbose) \"on\" else \"off\"\n    }\n}\n\nclass Execute : CliktCommand() {\n    val config by requireObject&lt;MyConfig&gt;()\n    override fun run() {\n        echo(\"Verbose mode is ${config.verbose}\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool --verbose execute\nVerbose mode is on\n</code></pre> <p>The <code>findObject</code>, <code>findOrSetObject</code>, and <code>requireObject</code> functions will walk up the context tree until they find a <code>obj</code> with the given type. If no such object exists, they will either return <code>null</code>, throw an exception, or create an instance of the object and store it on the command\u2019s context, depending on which function you use. If you need more than one object, you can pass a <code>key</code> to these functions, and they\u2019ll look for an object with that key and type in the context\u2019s <code>data</code> map.</p> <p>Keep in mind that the <code>findOrSetObject</code> property is lazy and won\u2019t set the Context\u2019s <code>obj</code> until its value is accessed. If you need to set an object for subcommands without accessing the property, you should use <code>currentContext.findOrSetObject</code>, or set <code>currentContext.obj</code> or <code>Context.Builder.obj</code> directly, instead.</p> Eager initialization with findOrSetObjectEager initialization with currentContext.objEager initialization with context builder <pre><code>class Tool : CliktCommand() {\n    override fun run() {\n        // runs eagerly\n        currentContext.findOrSetObject { MyConfig() }\n    }\n}\n</code></pre> <pre><code>class Tool : CliktCommand() {\n    override fun run() {\n        // runs eagerly, won't look for parent contexts\n        currentContext.obj = MyConfig()\n    }\n}\n</code></pre> <pre><code>Tool().context {\n    // runs eagerly, won't look for parent contexts\n    obj = MyConfig()\n}\n</code></pre> <p>Tip</p> <p>If you need to share resources that need to be cleaned up, you can use <code>currentContext.registerCloseable</code></p>"},{"location":"commands/#running-parent-command-without-children","title":"Running Parent Command Without Children","text":"<p>Normally, if a command has children, <code>run</code> is not called unless a child command is invoked on the command line. Instead, <code>--help</code> is called on the parent. If you want to change this behavior to always call <code>run()</code> on the parent, you can do so by setting <code>invokeWithoutSubcommand</code> to <code>true</code>. The <code>Context</code> will then have information on the subcommand that is about to be invoked, if there is one.</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    override val invokeWithoutSubcommand = true\n    override fun run() {\n        val subcommand = currentContext.invokedSubcommand\n        if (subcommand == null) {\n            echo(\"invoked without a subcommand\")\n        } else {\n            echo(\"about to run ${subcommand.name}\")\n        }\n    }\n}\n\nclass Execute : CliktCommand() {\n    override fun run() {\n        echo(\"running subcommand\")\n    }\n}\n</code></pre> <pre><code>$ ./tool\ninvoked without a subcommand\n</code></pre> <pre><code>$./tool execute\nabout to run execute\nrunning subcommand\n</code></pre>"},{"location":"commands/#customizing-contexts","title":"Customizing Contexts","text":"<p>Contexts have a number of properties that can be customized, and which are inherited by child commands. You can change these properties with the <code>context</code> builder function, which can be called in an <code>init</code> block, or on a command instance.</p> <p>For example, you can change the name of help option. These definitions are equivalent:</p> Version 1Version 2Usage <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        context { helpOptionNames = setOf(\"/help\") }\n    }\n}\nfun main(args: Array&lt;String&gt;) = Cli()\n</code></pre> <pre><code>class Cli : NoOpCliktCommand()\nfun main(args: Array&lt;String&gt;) = Cli()\n    .context { helpOptionNames = setOf(\"/help\") }\n    .main(args)\n</code></pre> <pre><code>$ ./cli --help\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  -h, --help  print the help\n</code></pre>"},{"location":"commands/#printing-the-help-message-when-no-arguments-are-given","title":"Printing the Help Message When No Arguments Are Given","text":"<p>Normally, if a command is called with no values on the command line, a usage error is printed if there are required parameters, or <code>run</code> is called if there aren\u2019t any.</p> <p>You can change this behavior by passing overriding <code>printHelpOnEmptyArgs = true</code> in your command. This will cause a help message to be printed when no values are provided on the command line, regardless of the parameters in your command.</p> ExampleUsage <pre><code>class Cli : CliktCommand() {\n    override val printHelpOnEmptyArgs = true\n    val arg by argument()\n    override fun run() { echo(\"Command ran\") }\n}\n</code></pre> <pre><code>$ ./cli\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  -h, --help  print the help\n</code></pre>"},{"location":"commands/#warnings-and-other-messages","title":"Warnings and Other Messages","text":"<p>When you want to show information to the user, you\u2019ll usually want to use the functions for printing to stdout directly.</p> <p>However, there\u2019s another mechanism that can be useful when writing reusable parameter code: command messages. These messages are buffered during parsing and printed all at once immediately before a command\u2019s <code>run</code> is called. They are not printed if there are any errors in parsing. This type of message is used by Clikt for <code>deprecating options</code>.</p> <p>You can issue a command message by calling <code>CliktCommand.issueMessage</code> or with the <code>message</code> function available in the context of parameter transformers.</p> ExampleUsage 1Usage 2 <pre><code>class Cli : CliktCommand() {\n    // This will print the warning when the option is given, but not if there are errors\n    val opt by option().validate {\n        if (it.isEmpty()) message(\"Empty strings are not recommended\")\n    }\n    override fun run() {\n        echo(\"command run\")\n    }\n}\n</code></pre> <pre><code>$ ./cli --opt=''\nEmpty strings are not recommended\ncommand run\n</code></pre> <pre><code>$ ./cli --opt='' --oops\nError: no such option: \"--oops\".\n</code></pre> <p>You can disable automatic message printing on the command\u2019s context:</p> ExampleUsage <pre><code>class Cli : CliktCommand() {\n    init { context { printExtraMessages = false } }\n    val opt by option().validate {\n        if (it.isEmpty()) message(\"Empty strings are not recommended\")\n    }\n    override fun run() {\n        echo(\"command run\")\n    }\n}\n</code></pre> <pre><code>$ ./cli --opt=''\ncommand run\n</code></pre>"},{"location":"commands/#chaining-and-repeating-subcommands","title":"Chaining and Repeating Subcommands","text":"<p>Some command line interfaces allow you to call more than one subcommand at a time. For example, you might do something like <code>gradle clean build publish</code> to run the <code>clean</code> task, then the <code>build</code> task, then the <code>publish</code> task, which are all subcommands of <code>gradle</code>.</p> <p>To do this with Clikt, override <code>allowMultipleSubcommands = true</code> in your command.</p> ExampleUsage <pre><code>class Compiler: CliktCommand() {\n    override val allowMultipleSubcommands = true\n    override fun run() {\n        echo(\"Running compiler\")\n    }\n}\n\nclass Clean: CliktCommand() {\n    val force by option().flag()\n    override fun run() {\n        echo(\"Cleaning (force=$force)\")\n    }\n}\n\nclass Build: CliktCommand() {\n    val file by argument().file()\n    override fun run() {\n        echo(\"Building $file\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Compiler().subcommands(Clean(), Build()).main(args)\n</code></pre> <pre><code>$ ./compiler clean --force build main.kt\nRunning compiler\nCleaning (force=true)\nBuilding main.kt\n</code></pre> <p>The parent command will <code>run</code> once, and each subcommand will <code>run</code> once each time they\u2019re called.</p> <p>Warning</p> <p>Enabling <code>allowMultipleSubcommands</code> will disable <code>allowInterspersedArgs</code> on the command and all its subcommands. If both were allowed to be enabled at the same time, then not all command lines could be parsed unambiguously.</p> <p>Subcommands of a command with <code>allowMultipleSubcommands=true</code> can themselves have subcommands, but cannot have <code>allowMultipleSubcommands=true</code>.</p>"},{"location":"commands/#command-pipelines","title":"Command pipelines","text":"<p>If you have multiple subcommands you might want to pass the output of one subcommand to the next. For example, the ImageMagick tool lets you apply a series of transformations to an image by invoking multiple subcommands.</p> <p>To do this with Clikt, you could pass your output through the <code>Context.obj</code>, but another option is to use a ChainedCliktCommand, which allows you to return values from your <code>run</code> function that will be passed to the next subcommand.</p> <p>In this example, we\u2019ll write simple text editing pipeline that takes an initial string, and then applies a series of transformations to it, printing the final result:</p> ExampleUsage <pre><code>class EditText : ChainedCliktCommand&lt;String&gt;() {\n    override val allowMultipleSubcommands: Boolean = true\n    val text by argument()\n    override fun run(value: String): String = text\n}\n\nclass RepeatText : ChainedCliktCommand&lt;String&gt;(\"repeat\") {\n    val count by option().int().default(1)\n    override fun run(value: String): String {\n        return value.repeat(count)\n    }\n}\n\nclass UppercaseText : ChainedCliktCommand&lt;String&gt;(\"uppercase\") {\n    override fun run(value: String): String {\n        return value.uppercase()\n    }\n}\n\nclass ReplaceText : ChainedCliktCommand&lt;String&gt;(\"replace\") {\n    val oldValue by argument()\n    val newValue by argument()\n    override fun run(value: String): String {\n        return value.replace(oldValue, newValue)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) {\n    val command = EditText()\n        .subcommands(RepeatText(), UppercaseText(), ReplaceText())\n    val result = command.main(args, \"\")\n    command.echo(result)\n}\n</code></pre> <pre><code>$ ./edit-text 'hello ' uppercase repeat --count=3 replace H Y\nYELLO YELLO YELLO\n</code></pre>"},{"location":"documenting/","title":"Documenting Scripts","text":"<p>Clikt takes care of creating formatted help messages for commands. There are a number of ways to customize the default behavior. You can also implement your own <code>HelpFormatter</code> and set it on the command\u2019s context.</p>"},{"location":"documenting/#help-texts","title":"Help Texts","text":"<p>You can add help text to commands and parameters. For parameters, you can pass a <code>help</code> string or  use the <code>help()</code> extension. For commands, you can override the <code>help</code> and <code>helpEpilog</code> methods.</p> ExampleAlternate styleHelp output <pre><code>class Hello : CliktCommand() {\n    override fun help(context: Context) = \"\"\"\n    This script prints &lt;name&gt; &lt;count&gt; times.\n\n    &lt;count&gt; must be a positive number, and defaults to 1.\n    \"\"\".trimIndent()\n    val count by option(\"-c\", \"--count\", metavar=\"count\", help=\"number of greetings\")\n        .int().default(1)\n    val name by argument(help=\"The name to greet\")\n    override fun run() = repeat(count) { echo(\"Hello $commandName!\") }\n}\n</code></pre> <pre><code>class Hello : CliktCommand() {\n    override fun help(context: Context): String {\n        val style = context.theme.info\n        return \"\"\"\n        This script prints ${style(\"&lt;name&gt;\")} ${style(\"&lt;count&gt;\")} times.\n\n        ${style(\"&lt;count&gt;\")} must be a positive number, and defaults to 1.\n        \"\"\".trimIndent()\n    }\n\n    val count by option(\"-c\", \"--count\", metavar=\"count\").int().default(1)\n        .help { theme.success(\"number of greetings\") }\n    val name by argument()\n        .help(\"The name to greet\")\n    override fun run() = repeat(count) { echo(\"Hello $name!\") }\n}\n</code></pre> <pre><code>$ ./hello --help\nUsage: hello [&lt;options&gt;] &lt;name&gt;\n\n  This script prints &lt;name&gt; &lt;count&gt; times.\n\n  &lt;count&gt; must be a positive number, and defaults to 1.\n\nOptions:\n  -c, --count &lt;count&gt; number of greetings\n  -h, --help          Show this message and exit\n</code></pre> <p>Option names and metavars will appear in help output even if no help string is specified for them. On the other hand, arguments only appear in the usage string. It is possible to add a help string to arguments which will be added to the help page, but the Unix convention is to just describe arguments in the command help.</p>"},{"location":"documenting/#markdown-in-help-texts","title":"Markdown in help texts","text":"<p>You can configure Clikt to use Mordant to render Markdown in help texts. You can use all the normal markdown features, such as lists, tables, and even hyperlinks if your terminal supports them.</p> <p>First, add the <code>:clitk-markdown</code> dependency to your project:</p> <pre><code>dependencies {\n   implementation(\"com.github.ajalt.clikt:clikt-markdown:$cliktVersion\")\n}\n</code></pre> <p>And install the markdown help formatter on your command:</p> <pre><code>val command = MyCommand().installMordantMarkdown()\n</code></pre> <p>Then you can use markdown in your help strings:</p> ExampleHelp output <pre><code>class Tool : NoOpCliktCommand() {\n    init {\n        installMordantMarkdown()\n    }\n    val option by option().help {\n        \"\"\"\n        | This | is | a | table |\n        | ---- | -- | - | ----- |\n        | 1    | 2  | 3 | 4     |\n\n        - This is\n        - a list\n\n        ```\n        You can\n            use code blocks\n        ```\n        \"\"\".trimIndent()\n    }\n}\n</code></pre> <pre><code>Usage: tool [&lt;options&gt;]\n\nOptions:\n  --option=&lt;text&gt;  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                   \u2502 This \u2502 is \u2502 a \u2502 table \u2502\n                   \u255e\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561\n                   \u2502 1    \u2502 2  \u2502 3 \u2502 4     \u2502\n                   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n                    \u2022 This is\n                    \u2022 a list\n\n                   \u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n                   \u2502You can            \u2502\n                   \u2502    use code blocks\u2502\n                   \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n  -h, --help       Show this message and exit\n</code></pre>"},{"location":"documenting/#manual-line-breaks","title":"Manual Line Breaks","text":"<p>If you want to insert a line break manually without preformatting the entire paragraph, you can use the Unicode Next Line (NEL) character. You can type a NEL with the unicode literal <code>\\u0085</code>.</p> <p>Clikt will treat NEL similarly to how <code>&lt;br&gt;</code> behaves in HTML: The NEL will be replaced with a line break in the output, and the paragraph will still be wrapped to the terminal width.</p> ExampleHelp output <pre><code>class Tool : NoOpCliktCommand() {\n    val option by option()\n        .help(\"This help will be at least two lines.\\u0085(this will start a new line)\")\n}\n</code></pre> <pre><code>Usage: tool\n\nOptions:\n  --option    This help will be at least\n              two lines.\n              (this will start a new\n              line)\n  -h, --help  Show this message and exit\n</code></pre> <p>Tip</p> <p>In raw multiline strings (which do not parse escape sequences), you\u2019ll need to insert the NEL with a string template such as <code>${\"\\u0085\"}</code>.</p>"},{"location":"documenting/#subcommand-short-help","title":"Subcommand Short Help","text":"<p>Subcommands are listed in the help page based on their name. They have a short help string which is the first line of their help.</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand()\n\nclass Execute : NoOpCliktCommand() {\n    override fun help(context: Context) = \"\"\"\n        Execute the command.\n\n        The command will be executed.\n        \"\"\".trimIndent()\n}\n\nclass Abort : NoOpCliktCommand() {\n    override fun help(context: Context) = \"Kill any running commands.\"\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  -h, --help  Show this message and exit\n\nCommands:\n  execute  Execute the command.\n  abort    Kill any running commands.\n</code></pre>"},{"location":"documenting/#help-option-customization","title":"Help Option Customization","text":"<p>Clikt adds a help option to every command automatically. It uses the names <code>-h</code> and <code>--help</code> and prints the command\u2019s help message when invoked. </p>"},{"location":"documenting/#changing-the-help-option-names","title":"Changing the help option names","text":"<p>Any help option name that conflicts with another option is not used for the help option. If the help option has no unique names, it is not added.</p> <p>You can change the help option\u2019s name and help message on the command\u2019s context:</p> ExampleUsage <pre><code>class HelpLocalization: Localization {\n    override fun helpOptionMessage(): String = \"show the help\"\n}\n\nclass Tool : NoOpCliktCommand() {\n    init {\n        context {\n            helpOptionNames = setOf(\"/help\")\n            localization = HelpLocalization()\n        }\n    }\n}\n</code></pre> <pre><code>$ ./tool /help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  /help  show the help\n</code></pre> <p>If you don\u2019t want a help option to be added, you can set <code>helpOptionNames = emptySet()</code></p>"},{"location":"documenting/#changing-the-help-option-behavior","title":"Changing the help option behavior","text":"<p>If you want to run some code when the help option is invoked, or change its behavior, you can define the option yourself. The default help option is an eager option that throws a PrintHelpMessage, so if you wanted to log some information when the help option is invoked, you could do something like this:</p> ExampleExample 2Usage <pre><code>class CustomHelpCommand : TestCommand() {\n    init {\n        eagerOption(\"-h\", \"--help\", help=\"Show this message and exit\") {\n            echo(\"about to print help\")\n            throw PrintHelpMessage(context)\n        }\n    }\n}\n</code></pre> <pre><code>// If you want to use the help message from the localization, you can register an option\n// with eager=true and use the lazy `help` method.\nclass CustomHelpCommand : TestCommand() {\n    init {\n        registerOption(\n            option(\"-h\", \"--help\", eager=true).flag()\n                .help { context.localization.helpOptionMessage() }\n                .validate {\n                    if(it) {\n                        echo(\"about to print help\")\n                        throw PrintHelpMessage(context)\n                    }\n                }\n        )\n    }\n}\n</code></pre> <pre><code>$ ./tool --help\nabout to print help\nUsage: custom-help [&lt;options&gt;]\n\nOptions:\n  -h, --help  Show this message and exit\n</code></pre> <p>Warning</p> <p>Eager options can\u2019t reference other options or arguments, since they\u2019re evaluated before parsing the rest of the command line.</p>"},{"location":"documenting/#default-values-in-help","title":"Default Values in Help","text":"<p>You can configure the help formatter to show default values in the help output by passing <code>showDefaultValues = true</code> to the <code>MordantHelpFormatter</code>. By default, the string value of the default value will be shown. You can show a different value by passing the value you want to show to the <code>defaultForHelp</code> parameter of <code>default</code>.</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand() {\n    init {\n        context {\n            helpFormatter = { MordantHelpFormatter(it, showDefaultValues = true) }\n        }\n    }\n\n    val a by option(help = \"this is optional\").default(\"value\")\n    val b by option(help = \"this is also optional\").default(\"value\", defaultForHelp=\"chosen for you\")\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  --a &lt;text&gt;    this is optional (default: value)\n  --b &lt;text&gt;    this is also optional (default: chosen for you)\n</code></pre>"},{"location":"documenting/#required-options-in-help","title":"Required Options in Help","text":"<p>By default, <code>required</code> options are displayed the same way as other options. The help formatter includes two different ways to show that an option is required.</p>"},{"location":"documenting/#required-option-marker","title":"Required Option Marker","text":"<p>You can pass a character to the <code>requiredOptionMarker</code> argument of the <code>MordantHelpFormatter</code>.</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand() {\n    init {\n        context {\n            helpFormatter = { MordantHelpFormatter(it, requiredOptionMarker = \"*\") }\n        }\n    }\n\n    val option by option(help = \"this is optional\")\n    val required by option(help = \"this is required\").required()\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  --option &lt;text&gt;    this is optional\n* --required &lt;text&gt;  this is required\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"documenting/#required-option-tag","title":"Required Option Tag","text":"<p>You can also show a tag for required options by passing <code>showRequiredTag = true</code> to the <code>MordantHelpFormatter</code>.</p> ExampleUsage <pre><code>class Tool : CliktCommand() {\n    init {\n        context {\n            helpFormatter = { MordantHelpFormatter(it, showRequiredTag = true) }\n        }\n    }\n\n    val option by option(help = \"this is optional\")\n    val required by option(help = \"this is required\").required()\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  --option &lt;text&gt;    this is optional\n  --required &lt;text&gt;  this is required (required)\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"documenting/#grouping-options-in-help","title":"Grouping Options in Help","text":"<p>You can group options into separate help sections by using OptionGroup and importing groups.provideDelegate. The name of the group will be shown in the output. You can also add an extra help message to be shown with the group. Groups can\u2019t be nested.</p> ExampleUsage <pre><code>import com.github.ajalt.clikt.parameters.groups.provideDelegate\n\nclass UserOptions : OptionGroup(\n        name = \"User Options\",\n        help = \"Options controlling the user\"\n) {\n    val name by option(help = \"user name\")\n    val age by option(help = \"user age\").int()\n}\n\nclass Tool : NoOpCliktCommand() {\n    val userOptions by UserOptions()\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: cli [&lt;options&gt;]\n\nUser Options:\n\n  Options controlling the user\n\n  --name &lt;text&gt;  user name\n  --age &lt;int&gt;    user age\n\nOptions:\n  -h, --help  Show this message and exit\n</code></pre>"},{"location":"documenting/#suggesting-corrections-for-mistyped-parameters","title":"Suggesting Corrections for Mistyped Parameters","text":"<p>When an option or subcommand is mistyped, Clikt will suggest corrections that are similar to the typed value.</p> Mistyped OptionMistyped Subcommand <pre><code>$ ./cli --sise=5\nError: no such option: \"--sise\". Did you mean \"--size\"?\n</code></pre> <pre><code>$ ./cli building\nUsage: cli [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nError: no such subcommand: \"building\". Did you mean \"build\"?\n</code></pre> <p>By default, Clikt will suggest corrections of any similar option or subcommand name based on a similarity metric. You can customize the suggestions by setting <code>suggestTypoCorrection</code> on your command\u2019s context.</p> <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        context {\n            // Only suggest corrections that start with the entered value\n            suggestTypoCorrection = { enteredValue, possibleValues -&gt;\n                possibleValues.filter { it.startsWith(enteredValue) }\n            }\n        }\n    }\n}\n</code></pre>"},{"location":"documenting/#localization","title":"Localization","text":"<p>You can localize error messages by implementing <code>Localization</code> and setting the <code>localization</code> property on your context.</p> ExampleUsage <pre><code>class CursiveLocalization : Localization {\n    override fun usageTitle() = \"\ud835\udcb0\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52:\"\n    override fun optionsTitle() = \"\ud835\udcaa\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8\"\n    override fun optionsMetavar() = \"\ud835\udc5c\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8\"\n    override fun helpOptionMessage() = \"\ud835\udcae\ud835\udcbd\ud835\udc5c\ud835\udccc \ud835\udcc9\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc2\ud835\udc52\ud835\udcc8\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52 \ud835\udcb6\ud835\udcc3\ud835\udcb9 \ud835\udc52\ud835\udccd\ud835\udcbe\ud835\udcc9\"\n\n    // ... override the rest of the strings here\n}\n\nclass I18NTool : NoOpCliktCommand() {\n    override fun help(context: Context) = \"\ud835\udcaf\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc9\ud835\udc5c\ud835\udc5c\ud835\udcc1 \ud835\udcbe\ud835\udcc8 \ud835\udcbe\ud835\udcc3 \ud835\udcb8\ud835\udcca\ud835\udcc7\ud835\udcc8\ud835\udcbe\ud835\udccb\ud835\udc52\"\n    init { context { localization = CursiveLocalization() } }\n}\n</code></pre> <pre><code>$ ./i18ntool --help\n\ud835\udcb0\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52: i18ntool [&lt;\ud835\udc5c\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8&gt;]\n\n  \ud835\udcaf\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc9\ud835\udc5c\ud835\udc5c\ud835\udcc1 \ud835\udcbe\ud835\udcc8 \ud835\udcbe\ud835\udcc3 \ud835\udcb8\ud835\udcca\ud835\udcc7\ud835\udcc8\ud835\udcbe\ud835\udccb\ud835\udc52\n\n\ud835\udcaa\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8:\n  -h, --help  \ud835\udcae\ud835\udcbd\ud835\udc5c\ud835\udccc \ud835\udcc9\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc2\ud835\udc52\ud835\udcc8\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52 \ud835\udcb6\ud835\udcc3\ud835\udcb9 \ud835\udc52\ud835\udccd\ud835\udcbe\ud835\udcc9\n</code></pre>"},{"location":"exceptions/","title":"Exception Handling","text":"<p>Clikt uses exceptions internally to signal that processing has ended early for any reason. This includes incorrect command line usage, or printing a help page.</p>"},{"location":"exceptions/#where-are-exceptions-handled","title":"Where are Exceptions Handled?","text":"<p>When you call <code>CliktCommand.main</code>, it will parse the command line and catch any <code>CliktError</code> exceptions. If it catches one, it will then print out the error\u2019s message and exit the process with the error\u2019s <code>statusCode</code>. The message is printed to stderr or stdout depending on the error\u2019s <code>printError</code> property.</p> <p>For exceptions raised by Clikt, <code>PrintMessage</code> and <code>PrintHelpMessage</code> have a <code>statusCode</code> of 0 and print to stdout. Other exceptions have a <code>statusCode</code> of 1 and print to stderr.</p> <p>Any other types of exceptions indicate a programming error, and are not caught by <code>main</code>. However, <code>convert</code> and the other parameter transformations will wrap exceptions thrown inside them in a <code>UsageError</code>, so if you define a custom transformation, you don\u2019t have to worry about an exception escaping to the user.</p>"},{"location":"exceptions/#handling-exceptions-manually","title":"Handling Exceptions Manually","text":"<p><code>CliktCommand.main</code> is just a <code>try</code>/<code>catch</code> block surrounding <code>CliktCommand.parse</code>, so if you don\u2019t want exceptions to be caught, you can call <code>parse</code> wherever you would normally call <code>main</code>.</p> <p>Tip</p> <p>You can use echoFormattedHelp to print the help or error message to any exception, or getFormattedHelp to get the help message as a string.</p> <pre><code>fun main(args: Array&lt;String&gt;) {\n    val cli = Cli()\n    try {\n        cli.parse(args)\n    } catch (e: CliktError) {\n        cli.echoFormattedHelp(e)\n        exitProcess(e.statusCode)\n    }\n}\n</code></pre>"},{"location":"exceptions/#which-exceptions-exist","title":"Which Exceptions Exist?","text":"<p>All exceptions thrown by Clikt are subclasses of <code>CliktError</code>.</p> <p>The following subclasses exist:</p> <ul> <li><code>Abort</code> : The command should exit immediately with the given <code>statusCode</code> without printing any messages.</li> <li><code>PrintMessage</code> : The exception\u2019s message should be printed.</li> <li><code>PrintHelpMessage</code> : The help page for the exception\u2019s command should be printed.</li> <li><code>PrintCompletionMessage</code> : Shell completion code for the command should be printed.</li> <li><code>UsageError</code> : The command line was incorrect in some way. All the following exceptions subclass from this. These exceptions are automatically augmented with extra information about the current parameter, if possible.</li> <li><code>MultiUsageError</code> : Multiple <code>UsageError</code>s occurred. The <code>errors</code> property contains the list of the errors.</li> <li><code>ProgramResult</code> : The program should exit with the <code>statusCode</code> from this exception.</li> <li><code>BadParameterValue</code> : A parameter was given the correct number of values, but of invalid format or type.</li> <li><code>MissingOption</code> and <code>MissingArgument</code>: A required parameter was not provided.</li> <li><code>NoSuchOption</code> : An option was provided that does not exist.</li> <li><code>NoSuchSubcommand</code> : A subcommand was called that does not exist.</li> <li><code>IncorrectOptionValueCount</code> : An option was supplied but the number of values supplied to the option was incorrect.</li> <li><code>IncorrectArgumentValueCount</code> : An argument was supplied but the number of values supplied was incorrect.</li> <li><code>MutuallyExclusiveGroupException</code> : Multiple options in a mutually exclusive group were supplied when the group is restricted to a single value.</li> <li><code>FileNotFound</code> : A required configuration file or @-file was not found.</li> <li><code>InvalidFileFormat</code> : A configuration file or @-file failed to parse correctly.</li> </ul>"},{"location":"migration/","title":"Upgrading to Newer Releases","text":"<p>See the [changelog] for a full list of changes in each release. This guide contains information on the most significant changes that may require updating to your code.</p>"},{"location":"migration/#upgrading-to-50","title":"Upgrading to 5.0","text":""},{"location":"migration/#some-methods-like-main-are-now-extensions","title":"some methods like <code>main</code> are now extensions","text":"<p>The <code>CliktCommand.main</code> and <code>CliktCommand.parse</code> methods are now extension functions, so you\u2019ll need to import them.</p> <pre><code>+ import com.github.ajalt.clikt.core.main\nfun main(args: Array&lt;String&gt;) = MyCommand().main(args)\n</code></pre> <p><code>Context.obj</code> and <code>Context.terminal</code>, and <code>OptionTransformContext.terminal</code> are also now extensions.</p> <pre><code>+ import com.github.ajalt.clikt.core.obj\n+ import com.github.ajalt.clikt.core.terminal\n\nfun main() {\n    val ctx = MyCommand().currentContext\n    ctx.terminal.info(ctx.obj)\n}\n</code></pre>"},{"location":"migration/#cliktcommand-constructor-no-longer-takes-most-parameters","title":"<code>CliktCommand</code> constructor no longer takes most parameters","text":"<p>All parameters of the <code>CliktCommand</code> except for <code>name</code> have been moved to open properties.</p> In 5.0In 4.0 <pre><code>class MyCommand : CliktCommand(name=\"mycommand\") {\n    override fun help(context: Context) = \"command help\"\n    override fun helpEpilog(context: Context) = \"command epilog\"\n    override val invokeWithoutSubcommand = true\n    override val printHelpOnEmptyArgs = true\n    override val helpTags = mapOf(\"tag\" to \"value\")\n    override val autoCompleteEnvvar = \"MYCOMMAND_COMPLETE\"\n    override val allowMultipleSubcommands = true\n    override val treatUnknownOptionsAsArgs = true\n    override val hiddenFromHelp = true\n}\n</code></pre> <pre><code>class MyCommand : CliktCommand(\n    name = \"mycommand\",\n    help = \"command help\",\n    helpEpilog = \"command epilog\",\n    invokeWithoutSubcommand = true,\n    printHelpOnEmptyArgs = true,\n    helpTags = mapOf(\"tag\" to \"value\"),\n    autoCompleteEnvvar = \"MYCOMMAND_COMPLETE\",\n    allowMultipleSubcommands = true,\n    treatUnknownOptionsAsArgs = true,\n    hiddenFromHelp = true,\n) {\n}\n</code></pre> <p>The full list of moved parameters:</p> removed parameter new replacement property <code>help</code> <code>fun help</code> <code>epilog</code> <code>fun helpEpilog</code> <code>invokeWithoutSubcommand</code> <code>val invokeWithoutSubcommand</code> <code>printHelpOnEmptyArgs</code> <code>val printHelpOnEmptyArgs</code> <code>helpTags</code> <code>val helpTags</code> <code>autoCompleteEnvvar</code> <code>val autoCompleteEnvvar</code> <code>allowMultipleSubcommands</code> <code>val allowMultipleSubcommands</code> <code>treatUnknownOptionsAsArgs</code> <code>val treatUnknownOptionsAsArgs</code> <code>hidden</code> <code>val hiddenFromHelp</code>"},{"location":"migration/#markdown-moved-to-a-separate-module","title":"Markdown moved to a separate module","text":"<p>In order to reduce executable size, the Markdown rendering functionality has been moved to a separate module.</p> <p>To use Markdown rendering first, add the <code>:clitk-markdown</code> dependency to your project:</p> <pre><code>dependencies {\n   implementation(\"com.github.ajalt.clikt:clikt-markdown:$cliktVersion\")\n}\n</code></pre> <p>Then install the markdown help formatter on your command:</p> <pre><code>val command = MyCommand().installMordantMarkdown()\n</code></pre>"},{"location":"migration/#context-builder-properties-renamed","title":"<code>Context</code> builder properties renamed","text":"<p>Some of the properties on <code>Context</code> and its builder have been renamed to be more consistent:</p> old name new name <code>Context.envvarReader</code> <code>Context.readEnvvar</code> <code>Context.correctionSuggestor</code> <code>Context.suggestTypoCorrection</code> <code>Context.argumentFileReader</code> <code>Context.readArgumentFile</code> <code>Context.tokenTransformer</code> <code>Context.transformToken</code> <p>The old names are still available as deprecated properties.</p>"},{"location":"migration/#removed-termui","title":"Removed <code>TermUi</code>","text":"<p>The remaining methods in <code>TermUi</code> have been removed. If you were using it, you can open an editor manually with <code>ProcessBuilder</code> or similar.</p>"},{"location":"migration/#upgrading-to-40","title":"Upgrading to 4.0","text":""},{"location":"migration/#help-formatting","title":"Help formatting","text":"<p>The <code>CliktHelpFormatter</code> class has been removed and replaced with the <code>MordantHelpFormatter</code>. The <code>MordantHelpFormatter</code> constructor takes a <code>Context</code> instead of a <code>Localization</code>, and the parameters controlling size and spacing have been removed. See the documentation for details on how to set the help formatter on the Context.</p> <p>If you were subclassing <code>CliktHelpFormatter</code>, <code>MordantHelpFormatter</code>\u2019s open methods are different. See the <code>helpformat</code> sample for an example of how to use the new formatter.</p>"},{"location":"migration/#prompting","title":"Prompting","text":"<p>The <code>CliktConsole</code> class has been removed. If you were using it, use your command\u2019s Mordant <code>terminal</code> instead.</p> <p>The <code>prompt</code> and <code>confirm</code> methods now use Mordant\u2019s prompting functionality, and some of their arguments have changed. In particular, conversion lambdas now return a <code>ConversionResult</code>  instead of throwing an exception.</p> In 4.0In 3.0 <pre><code>val input = prompt(\"Enter a number\") {\n    it.toIntOrNull()\n        ?.let { ConversionResult.Valid(it) }\n        ?: ConversionResult.Invalid(\"$it is not a valid integer\")\n}\n</code></pre> <pre><code>val input = prompt(\"Enter a number\") {\n    it.toIntOrNull() ?: throw BadParameterValue(\"$it is not a valid integer\")\n}\n</code></pre>"},{"location":"migration/#upgrading-to-30","title":"Upgrading to 3.0","text":""},{"location":"migration/#maven-coordinates","title":"Maven Coordinates","text":"<p>Clikt\u2019s Maven groupId changed from <code>com.github.ajalt</code> to <code>com.github.ajalt.clikt</code>. So the full coordinate is now <code>com.github.ajalt.clikt:clikt:3.0.0</code>.</p> <p>With the new Multiplatform plugin in Kotlin 1.4, there is no longer a separate <code>clikt-multiplatform</code> artifact. You can use <code>com.github.ajalt.clikt:clikt:3.0.0</code> for both JVM-only and Multiplatform projects.</p>"},{"location":"migration/#environment-variable-splitting","title":"Environment variable splitting","text":"<p>There used to be an <code>envvarSplit</code> parameter to <code>option()</code> and its <code>convert()</code> that would split values coming from an environment variable. This parameter is removed, and values from environment variables are no longer split automatically.</p> <p>If you still want to split option values, you can do so explicitly with <code>split()</code>.</p>"},{"location":"migration/#experimental-apis","title":"Experimental APIs","text":"<p>The Value Source API and Completion Generation APIs no longer require opt-in. You can use these APIs without needing the <code>ExperimentalValueSourceApi</code> or <code>ExperimentalCompletionCandidates</code> annotations.</p>"},{"location":"migration/#localization","title":"Localization","text":"<p>By default, all strings are defined in the <code>Localization</code> object set on your context.</p> <p>This means that string parameters like <code>usageTitle</code> in the constructor for <code>CliktHelpFormatter</code> have been removed in favor of functions like <code>Localization.usageTitle()</code>.</p> <p><code>Context.helpOptionMessage</code> has also been removed in favor of <code>Localization.helpOptionMessage()</code>. See Help Option Customization for an example.</p>"},{"location":"options/","title":"Options","text":"<p>Options are added to commands by defining a property delegate with the <code>option</code> function.</p>"},{"location":"options/#basic-options","title":"Basic Options","text":"<p>The default option takes one value of type <code>String</code>. The property is nullable. If the option is not given on the command line, the property value will be null. If the option is given at least once, the property will return the value of the last occurrence of the option.</p> ExampleUsage <pre><code>class Hello: CliktCommand() {\n    val name by option(help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello --name=Foo\nHello, Foo!\n</code></pre>"},{"location":"options/#option-names","title":"Option Names","text":"<p>If you don\u2019t specify names for an option, a lowercase hyphen-separated name is automatically inferred from the property. For example, <code>val myOpt by option()</code> will create an option that can be called with <code>--my-opt</code>.</p> <p>You can also specify any number of names for an option manually:</p> <pre><code>class Hello: CliktCommand() {\n    val name by option(\"-n\", \"--name\", help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <p>Option names that are two characters long (like <code>-n</code>) are treated as POSIX-style short options. You call them with a value like this:</p> Usage 1Usage 2 <pre><code>$ ./hello -nfoo\nHello, foo!\n</code></pre> <pre><code>$ ./hello -n foo\nHello, foo!\n</code></pre> <p>All other option names are considered long options, and can be called like this:</p> Usage 1Usage 2 <pre><code>$ ./hello --name=foo\nHello, foo!\n</code></pre> <pre><code>$ ./hello --name foo\nHello, foo!\n</code></pre>"},{"location":"options/#customizing-options","title":"Customizing Options","text":"<p>The option behavior and delegate type can be customized by calling extension functions on the <code>option</code> call. For example, here are some different option declarations:</p> <pre><code>val a: String? by option()\nval b: Int? by option().int()\nval c: Pair&lt;Int, Int&gt;? by option().int().pair()\nval d: Pair&lt;Int, Int&gt; by option().int().pair().default(0 to 0)\nval e: Pair&lt;Float, Float&gt; by option().float().pair().default(0f to 0f)\n</code></pre> <p>There are three main types of behavior that can be customized independently:</p> <ol> <li>The type of each value in the option.    The value type is <code>String</code> by default, but can be customized with built-in functions like    <code>int</code> or <code>choice</code>, or manually with <code>convert</code>.    This is detailed in the parameters page.</li> <li>The number of values that the option requires.    Options take one value by default, but this can be changed with    built-in functions like <code>pair</code> and <code>triple</code>, or manually with    <code>transformValues</code>.</li> <li>How to handle all calls to the option (i.e. if the option is not present, or is present more than once).    By default, the option delegate value is the null if the option is not given on the command line,    and will use the value of the last occurrence if the option is given more than once. You can    change this behavior with functions like <code>default</code> and <code>multiple</code>.</li> </ol> <p>Since the three types of customizations are orthogonal, you can choose which ones you want to use, and if you implement a new customization, it can be used with all the existing functions without any repeated code.</p>"},{"location":"options/#default-values","title":"Default Values","text":"<p>By default, option delegates return <code>null</code> if the option wasn\u2019t provided on the command line. You can instead return a default value with <code>default</code>.</p> ExampleUsage 1Usage 2 <pre><code>class Pow : CliktCommand() {\n    val exp by option(\"-e\", \"--exp\").double().default(1.0)\n    override fun run() {\n        echo(\"2 ^ $exp = ${(2.0).pow(exp)}\")\n    }\n}\n</code></pre> <pre><code>$ ./pow -e 8\n2 ^ 8.0 = 256.0\n</code></pre> <pre><code>$ ./pow\n2 ^ 1.0 = 2.0\n</code></pre> <p>If the default value is expensive to compute, or you want to use another parameter as the default, you can use <code>defaultLazy</code> instead of <code>default</code>. It has the same effect, but you give it a lambda returning the default value, and the lambda will only be called if the option isn\u2019t present on the command line.</p> <p>Warning</p> <p>The lambda you pass to <code>defaultLazy</code> is normally called at most once. But the lambda references another parameter, it may be called more than once in order to make sure the parameter it references is available.</p>"},{"location":"options/#multi-value-options","title":"Multi Value Options","text":"<p>Options can take a fixed number of values separated by whitespace, a variable number of values separated by a delimiter, or a variable number of values separated by a whitespace.</p>"},{"location":"options/#options-with-fixed-number-of-values","title":"Options With Fixed Number of Values","text":"<p>There are built in functions for options that take two values (<code>pair</code>, which uses a <code>Pair</code>), or three values (<code>triple</code>, which uses a <code>Triple</code>). You can change the type of each value as normal with functions like <code>int</code>.</p> <p>If you need more values, you can provide your own container with <code>transformValues</code>. You give that function the number of values you want, and a lambda that will transform a list of values into the output container. The list will always have a size equal to the number you specify. If the user provides a different number of values, Clikt will inform the user and your lambda won\u2019t be called.</p> ExampleUsage <pre><code>data class Quad&lt;out T&gt;(val a: T, val b: T, val c: T, val d: T)\nfun &lt;T&gt; Quad&lt;T&gt;.toList(): List&lt;T&gt; = listOf(a, b, c, d)\n\nclass Geometry : CliktCommand() {\n    val square by option().int().pair()\n    val cube by option().int().triple()\n    val tesseract by option().int().transformValues(4) { Quad(it[0], it[1], it[2], it[3]) }\n    override fun run() {\n        echo(\"Square has dimensions ${square?.toList()?.joinToString(\"x\")}\")\n        echo(\"Cube has dimensions ${cube?.toList()?.joinToString(\"x\")}\")\n        echo(\"Tesseract has dimensions ${tesseract?.toList()?.joinToString(\"x\")}\")\n    }\n}\n</code></pre> <pre><code>$ ./geometry --square 1 2 --cube 3 4 5 --tesseract 6 7 8 9\nSquare has dimensions 1x2\nCube has dimensions 3x4x5\nTesseract has dimensions 6x7x8x9\n</code></pre>"},{"location":"options/#splitting-an-option-value-on-a-delimiter","title":"Splitting an Option Value on a Delimiter","text":"<p>You can use <code>split</code> to allow a variable number of values to a single option invocation by separating the values with non-whitespace delimiters. This will also split values from environment variables.</p> ExampleUsageUsage with Environment Variable <pre><code>class C : CliktCommand() {\n    val profiles by option(\"-P\", envvar=\"PROFILES\").split(\",\")\n    override fun run() {\n        for (profile in profiles) {\n            echo(profile)\n        }\n    }\n}\n</code></pre> <pre><code>$ ./split -P profile-1,profile-2\nprofile-1\nprofile-2\n</code></pre> <pre><code>$ export PROFILES=profile-1,profile-2\n$ ./split\nprofile-1\nprofile-2\n</code></pre>"},{"location":"options/#options-with-an-optional-value","title":"Options with an Optional Value","text":"<p>You can create options that take zero or one values with <code>optionalValue</code> or <code>optionalValueLazy</code>.</p> ExampleUsage with no option valueUsage with option valueUsage with no option <pre><code>class C : CliktCommand() {\n    val log by option().optionalValue(\"debug\").default(\"none\")\n    override fun run() {\n        echo(\"log level: $log\")\n    }\n}\n</code></pre> <pre><code>$ ./command --log\nlog level: debug\n</code></pre> <pre><code>$ ./command --log=verbose\nlog level: verbose\n</code></pre> <pre><code>$ ./command\nlog level: none\n</code></pre> <p>Warning</p> <p>If a user specifies the value without an <code>=</code>, as in <code>--log debug</code>, the <code>debug</code> will always be interpreted as a value for the option, even if the command accepts arguments. This might be confusing to your users, so you can require that the option value always be specified with <code>=</code> by passing <code>optionalValue(acceptsUnattachedValue=false)</code>.</p>"},{"location":"options/#options-with-a-variable-number-of-values","title":"Options With a Variable Number of Values","text":"<p>If you want your option to take a variable number of values, but want to split the value on whitespace  rather than a delimiter, you can use <code>varargValues</code>.</p> ExampleUsage <pre><code>class Order : CliktCommand() {\n    val sizes: List&lt;String&gt; by option().varargValues()\n    override fun run() {\n        echo(\"You ordered: $sizes\")\n    }\n}\n</code></pre> <pre><code>$ ./order --sizes small medium\nYou ordered: [\"small\", \"medium\"]\n</code></pre> <p>By default, <code>varargValues</code> requires at least one value, and has no maximum limit. You can configure the limits by passing <code>min</code> and <code>max</code> arguments to <code>varargValues</code>.</p>"},{"location":"options/#multiple-options","title":"Multiple Options","text":"<p>Normally, when an option is provided on the command line more than once, only the values from the last occurrence are used. But sometimes you want to keep all values provided. For example, <code>git commit -m foo -m bar</code> would create a commit message with two lines: <code>foo</code> and <code>bar</code>. To get this behavior with Clikt, you can use <code>multiple</code>. This will cause the property delegate value to be a list, where each item in the list is the value of from one occurrence of the option. If the option is never given, the list will be empty (or you can specify a default to use).</p> ExampleUsage <pre><code>class Commit : CliktCommand() {\n    val message: List&lt;String&gt; by option(\"-m\").multiple()\n    override fun run() {\n        echo(message.joinToString(\"\\n\"))\n    }\n}\n</code></pre> <pre><code>$ ./commit -m foo -m bar\nfoo\nbar\n</code></pre> <p>You can combine <code>multiple</code> with item type conversions and multiple values.</p> <pre><code>val opt: List&lt;Pair&lt;Int, Int&gt;&gt; by option().int().pair().multiple()\n</code></pre>"},{"location":"options/#default-values-for-optionmultiple","title":"Default values for option().multiple()","text":"<p>You can also supply a default value to <code>multiple</code> or require at least one value be present on the command line. These are specified as arguments rather than with separate extension functions since they don\u2019t change the type of the delegate.</p> RequiredDefault <pre><code>val opt: List&lt;String&gt; by option().multiple(required=true)\n</code></pre> <pre><code>val opt: List&lt;String&gt; by option().multiple(default=listOf(\"default message\"))\n</code></pre>"},{"location":"options/#deduplicating-optionmultiple-into-a-unique-set","title":"Deduplicating option().multiple() into a unique set","text":"<p>You can discard duplicate values from a <code>multiple</code> option with <code>unique</code>.</p> ExampleUsage <pre><code>class Build : CliktCommand() {\n    val platforms: Set&lt;String&gt; by option(\"-p\").multiple().unique()\n    override fun run() {\n        echo(\"Building for platforms: $platforms\")\n    }\n}\n</code></pre> <pre><code>$ ./build -p android -p ios -p android\nBuilding for platforms: [android, ios]\n</code></pre>"},{"location":"options/#key-value-and-map-options","title":"Key-Value and Map Options","text":"<p>You can split an option\u2019s value into a key-value pair with <code>splitPair</code>. By default, the delimiter <code>=</code> will be used to split. You can also use <code>associate</code> to allow the option to be specified multiple times, and have its values collected in a map.</p> ExampleUsage <pre><code>class Build : CliktCommand() {\n    val systemProp: Map&lt;String, String&gt; by option(\"-D\", \"--system-prop\").associate()\n\n    override fun run() {\n        echo(systemProp)\n    }\n}\n</code></pre> <pre><code>$ ./build -Dplace=here --system-prop size=small\n{place=here, size=small}\n</code></pre>"},{"location":"options/#boolean-flag-options","title":"Boolean Flag Options","text":"<p>Flags are options that don\u2019t take a value. Boolean flags can be enabled or disabled, depending on the name used to invoke the option. You can turn an option into a boolean flag with <code>flag</code>. That function takes an optional list of secondary names that will be added to any existing or inferred names for the option. If the option is invoked with one of the secondary names, the delegate will return false. It\u2019s a good idea to always set secondary names so that a user can disable the flag if it was enabled previously.</p> ExampleUsage 1Usage 2 <pre><code>class Cli : CliktCommand() {\n    val flag by option(\"--on\", \"-o\").flag(\"--off\", \"-O\", default = false)\n    override fun run() {\n        echo(flag)\n    }\n}\n</code></pre> <pre><code>$ ./cli -o\ntrue\n</code></pre> <pre><code>$ ./cli --on --off\nfalse\n</code></pre> <p>Multiple short flag options can be combined when called on the command line:</p> ExampleUsage <pre><code>class Cli : CliktCommand() {\n    val flagA by option(\"-a\").flag()\n    val flagB by option(\"-b\").flag()\n    val foo by option(\"-f\")\n    override fun run() {\n        echo(\"$flagA $flagB $foo\")\n    }\n}\n</code></pre> <pre><code>$ ./cli -abfFoo\ntrue true Foo\n</code></pre> <p>Tip</p> <p>You can diasable short option grouping by setting <code>Context.allowGroupedShortOptions</code> to <code>false</code>.</p>"},{"location":"options/#counted-flag-options","title":"Counted Flag Options","text":"<p>You might want a flag option that counts the number of times it occurs on the command line. You can use <code>counted</code> for this.</p> <p>You can specify a <code>limit</code> for the number of times the <code>counted</code> option can be given, and either <code>clamp</code> the value or show an error if the limit is exceeded.</p> ExampleUsage <pre><code>class Log : CliktCommand() {\n    val verbosity by option(\"-v\").counted(limit=3, clamp=true)\n    override fun run() {\n        echo(\"Verbosity level: $verbosity\")\n    }\n}\n</code></pre> <pre><code>$ ./log -vvv\nVerbosity level: 3\n</code></pre>"},{"location":"options/#feature-switch-flags","title":"Feature Switch Flags","text":"<p>Another way to use flags is to assign a value to each option name. You can do this with <code>switch</code>, which takes a map of option names to values. Note that the names in the map replace any previously specified or inferred names.</p> ExampleUsage <pre><code>class Size : CliktCommand() {\n    val size by option().switch(\n        \"--large\" to \"large\",\n        \"--small\" to \"small\"\n    ).default(\"unknown\")\n    override fun run() {\n        echo(\"You picked size $size\")\n    }\n}\n</code></pre> <pre><code>$ ./size --small\nYou picked size small\n</code></pre>"},{"location":"options/#choice-options","title":"Choice Options","text":"<p>You can restrict the values that a regular option can take to a set of values using <code>choice</code>. You can also map the input values to new types.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>class Digest : CliktCommand() {\n    val hash by option().choice(\"md5\", \"sha1\")\n    override fun run() {\n        echo(hash)\n    }\n}\n</code></pre> <pre><code>$ ./digest --hash=md5\nmd5\n</code></pre> <pre><code>$ ./digest --hash=sha256\nUsage: digest [&lt;options&gt;]\n\nError: Invalid value for \"--hash\": invalid choice: sha256. (choose from md5, sha1)\n</code></pre> <pre><code>$ ./digest --help\nUsage: digest [&lt;options&gt;]\n\nOptions:\n  --hash [md5|sha1]\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"options/#mutually-exclusive-option-groups","title":"Mutually Exclusive Option Groups","text":"<p>If <code>choice</code> or <code>switch</code> options aren\u2019t flexible enough, you can use <code>mutuallyExclusiveOptions</code> to group any nullable options into a mutually exclusive group. If more than one of the options in the group is given on the command line, the last value is used.</p> <p>If you want different types for each option, you can wrap them in a sealed class.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>sealed class Fruit {\n    data class Oranges(val size: String): Fruit()\n    data class Apples(val count: Int): Fruit()\n}\nclass Order : CliktCommand() {\n    val fruit: Fruit? by mutuallyExclusiveOptions&lt;Fruit&gt;(\n        option(\"--oranges\").convert { Oranges(it) },\n        option(\"--apples\").int().convert { Apples(it) }\n    )\n\n    override fun run() = echo(fruit)\n}\n</code></pre> <pre><code>$ ./order --apples=10\nApples(count=10)\n</code></pre> <pre><code>$ ./order --oranges=small\nOranges(size=small)\n</code></pre> <pre><code>$ ./order --apples=10 --oranges=large\nOranges(size=large)\n</code></pre> <p>You can enforce that only one of the options is given with <code>single</code>:</p> ExampleUsage <pre><code>val fruit: Fruit? by mutuallyExclusiveOptions&lt;Fruit&gt;(\n        option(\"--apples\").convert { Apples(it.toInt()) },\n        option(\"--oranges\").convert { Oranges(it) }\n).single()\n</code></pre> <pre><code>$ ./order --apples=10 --oranges=small\nUsage: order [&lt;options&gt;]\n\nError: option --apples cannot be used with --oranges\n</code></pre> <p>Like regular options, you can make the entire group <code>required</code>, or give it a <code>default</code> value.</p> <p>Like other option groups, you can specify a <code>name</code> and <code>help</code> text for the group if you want to set the group apart in the help output.</p>"},{"location":"options/#co-occurring-option-groups","title":"Co-Occurring Option Groups","text":"<p>Sometimes you have a set of options that only make sense when specified together. To enforce this, you can make an option group <code>cooccurring</code>.</p> <p>Co-occurring groups must have at least one <code>required</code> option, and may also have non-required options. The <code>required</code> constraint is enforced if any of the options in the group are given on the command line. If none of the options are given, the value of the group is null.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>class UserOptions : OptionGroup() {\n    val name by option().required()\n    val age by option().int()\n}\nclass Tool : CliktCommand() {\n    val userOptions by UserOptions().cooccurring()\n    override fun run() {\n        userOptions?.let {\n            echo(it.name)\n            echo(it.age)\n        } ?: echo(\"No user options\")\n    }\n}\n</code></pre> <pre><code>$ ./tool\nNo user options\n</code></pre> <pre><code>$ ./tool --name=jane --age=30\njane\n30\n</code></pre> <pre><code>$ ./tool --age=30\nUsage: tool [&lt;options&gt;]\n\nError: Missing option \"--name\".\n</code></pre> <p>Like other option groups, you can specify a <code>name</code> and <code>help</code> text for the group if you want to set the group apart in the help output.</p>"},{"location":"options/#choice-and-switch-options-with-groups","title":"Choice and Switch Options With Groups","text":"<p>If you have different groups of options that only make sense when another option has a certain value, you can use <code>groupChoice</code> and <code>groupSwitch</code>.</p> <p><code>groupChoice</code> options are similar to <code>choice</code> options, but instead of mapping a value to a single new type, they map a value to a co-occurring <code>OptionGroup</code>. Options for groups other than the selected one are ignored, and only the selected group\u2019s <code>required</code> constraints are enforced. In the same way, <code>groupSwitch</code> options are similar to <code>switch</code> options.</p> ExampleUsage 1Usage 2Usage 3Usage 4 <pre><code>sealed class LoadConfig(name: String): OptionGroup(name)\nclass FromDisk : LoadConfig(\"Options for loading from disk\") {\n    val path by option().file().required()\n    val followSymlinks by option().flag()\n}\n\nclass FromNetwork: LoadConfig(\"Options for loading from network\") {\n    val url by option().required()\n    val username by option().prompt()\n    val password by option().prompt(hideInput = true)\n}\n\nclass Tool : CliktCommand() {\n    val load by option().groupChoice(\n            \"disk\" to FromDisk(),\n            \"network\" to FromNetwork()\n    )\n\n    override fun run() {\n        when(val it = load) {\n            is FromDisk -&gt; echo(\"Loading from disk: ${it.path}\")\n            is FromNetwork -&gt; echo(\"Loading from network: ${it.url}\")\n            null -&gt; echo(\"Not loading\")\n        }\n    }\n}\n</code></pre> <pre><code>$ ./tool --load=disk --path=./config --follow-symlinks\nLoading from disk: .\\config\n</code></pre> <pre><code>$ ./tool --load=network --url=www.example.com --username=admin\nPassword: *******\nLoading from network: www.example.com\n</code></pre> <pre><code>$ ./tool --load=disk\nUsage: cli [&lt;options&gt;]\n\nError: Missing option \"--path\".\n</code></pre> <pre><code>$ ./tool --load=whoops\nUsage: cli [&lt;options&gt;]\n\nError: Invalid value for \"--load\": invalid choice: whoops. (choose from disk, network)\n</code></pre>"},{"location":"options/#number-options-without-a-name","title":"Number Options Without a Name","text":"<p>If you have an int or long option, you might want to allow it to be specified without need the option name. For example, <code>git log -2</code> and <code>git log -n 2</code> are equivalent. You can add an option like this by passing <code>acceptsValueWithoutName=true</code> to <code>int()</code> or <code>long()</code>.</p> ExampleUsage 1Usage 2Help Output <pre><code>class Tool : CliktCommand() {\n    val level by option(\"-l\", \"--level\", metavar = \"&lt;number&gt;\")\n        .int(acceptsValueWithoutName = true)\n\n    override fun run() {\n        echo(\"Level: $level\")\n    }\n}\n</code></pre> <pre><code>$ ./tool -20\nLevel: 20\n</code></pre> <pre><code>$ ./tool --level=3\nLevel: 3\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n-&lt;number&gt;, -l, --level &lt;number&gt;\n-h, --help             Show this message and exit\n</code></pre> <p>Caution</p> <p>You may only have one option with <code>acceptsValueWithoutName=true</code> per command</p>"},{"location":"options/#prompting-for-input","title":"Prompting For Input","text":"<p>In some cases, you might want to create an option that uses the value given on the command line if there is one, but prompt the user for input if one is not provided. Clikt can take care of this for you with the <code>prompt</code> function.</p> ExampleUsage 1Usage 2 <pre><code>class Hello : CliktCommand() {\n    val name by option().prompt()\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>./hello --name=foo\nHello foo\n</code></pre> <pre><code>./hello\nName: foo\nHello foo\n</code></pre> <p>The default prompt string is based on the option name, but <code>prompt</code> takes a number of parameters to customize the output.</p>"},{"location":"options/#password-prompts","title":"Password Prompts","text":"<p>You can also create an option that uses a hidden prompt and asks for confirmation. This combination of behavior is commonly used for passwords.</p> ExampleUsage <pre><code>class Login : CliktCommand() {\n    val password by option().prompt(requireConfirmation = true, hideInput = true)\n    override fun run() {\n        echo(\"Your hidden password: $password\")\n    }\n}\n</code></pre> <pre><code>$ ./login\nPassword:\nYour hidden password: hunter2\n</code></pre>"},{"location":"options/#eager-options","title":"Eager Options","text":"<p>Sometimes you want an option to halt execution immediately and print a message. For example, the built-in <code>--help</code> option, or the <code>--version</code> option that many programs have.</p> <p>The <code>--help</code> option is added automatically to commands, and <code>--version</code> can be added using <code>versionOption</code>. Since these options don\u2019t have values, you can\u2019t define them using property delegates. Instead, call the function on a command directly, either in an <code>init</code> block, or on a command instance.</p> <p>These definitions are equivalent:</p> Version 1Version 2Usage <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        versionOption(\"1.0\")\n    }\n}\nfun main(args: Array&lt;String&gt;) = Cli().main(args)\n</code></pre> <pre><code>class Cli : NoOpCliktCommand()\nfun main(args: Array&lt;String&gt;) = Cli().versionOption(\"1.0\").main(args)\n</code></pre> <pre><code>$ ./cli --version\ncli version 1.0\n</code></pre>"},{"location":"options/#custom-eager-options","title":"Custom Eager Options","text":"<p>If you want to define your own option with a similar behavior, you can do so by calling <code>eagerOption</code>. This function takes an <code>action</code> that is called when the option is encountered on the command line. To print a message and halt execution normally from the callback, you can throw a <code>PrintMessage</code> exception, and <code>CliktCommand.main</code> will take care of printing the message. If you want to exit normally without printing a message, you can throw <code>Abort(error=false)</code> instead.</p> <p>You can define your own version option like this:</p> <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        eagerOption(\"--version\") {\n            throw PrintMessage(\"$name version 1.0\")\n        }\n    }\n}\n</code></pre>"},{"location":"options/#custom-eager-options-with-values","title":"Custom Eager Options With Values","text":"<p>If you need an eager option that takes a value, pass <code>eager=true</code> to <code>option()</code>.</p> <pre><code>val color by option(eager=true).flag(\"--no-color\", default=true)\n</code></pre> <p>Warning</p> <p>Eager options can\u2019t reference other options or arguments, since they\u2019re evaluated before parsing the rest of the command line. They can be declared in regular <code>OptionGroups</code>, but not in other types of groups like switch groups.</p>"},{"location":"options/#deprecating-options","title":"Deprecating Options","text":"<p>You can communicate to users that an option is deprecated with <code>option().deprecated()</code>. By default, this function will add a tag to the option\u2019s help message, and print a warning to stderr if the option is used.</p> <p>You can customize or omit the warning message and help tags, or change the warning into an error.</p> ExampleUsage 1Usage 2Usage 3Usage 4Help Output <pre><code>class Cli : CliktCommand() {\n   val opt by option(help = \"option 1\").deprecated()\n   val opt2 by option(help = \"option 2\").deprecated(\"WARNING: --opt2 is deprecated, use --new-opt instead\", tagName = null)\n   val opt3 by option(help = \"option 3\").deprecated(tagName = \"pending deprecation\", tagValue = \"use --new-opt instead\")\n   val opt4 by option(help = \"option 4\").deprecated(error = true)\n\n   override fun run() = echo(\"command run\")\n}\n</code></pre> <pre><code>$ ./cli --opt=x\nWARNING: option --opt is deprecated\ncommand run\n</code></pre> <pre><code>$ ./cli --opt2=x\nWARNING: --op2 is deprecated, use --new-opt instead\ncommand run\n</code></pre> <pre><code>$ ./cli --opt3=x\nWARNING: option --opt3 is deprecated\ncommand run\n</code></pre> <pre><code>$ ./cli --opt4=x\nERROR: option --opt4 is deprecated\n</code></pre> <pre><code>$ ./cli --help\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  --opt &lt;text&gt;   option 1 (deprecated)\n  --opt2 &lt;text&gt;  option 2\n  --opt3 &lt;text&gt;  option 3 (pending deprecation: use --new-opt instead)\n  --opt4 &lt;text&gt;  option 4 (deprecated)\n</code></pre>"},{"location":"options/#unknown-options","title":"Unknown Options","text":"<p>You may want to collect unknown options for manual processing. You can do this by overriding <code>treatUnknownOptionsAsArgs = true</code> in your command. This will cause Clikt to treat unknown options as positional arguments rather than reporting an error when one is encountered. You\u2019ll need to define an <code>argument().multiple()</code> property to collect the options, otherwise an error will still be reported.</p> ExampleUsage <pre><code>class Wrapper : CliktCommand() {\n    init { context { allowInterspersedArgs = false }}\n    override val treatUnknownOptionsAsArgs = true\n\n    val command by option().required()\n    val arguments by argument().multiple()\n\n    override fun run() {\n        val cmd = (listOf(command) + arguments).joinToString(\" \")\n        val proc = Runtime.getRuntime().exec(cmd)\n        echo(proc.inputStream.bufferedReader().readText())\n        proc.waitFor()\n    }\n}\n</code></pre> <pre><code>$ ./wrapper --command=git tag --help | head -n4\nGIT-TAG(1)                        Git Manual                        GIT-TAG(1)\n\nNAME\n       git-tag - Create, list, delete or verify a tag object signed with GPG\n</code></pre> <p>Warning</p> <p>Multiple short options in a single token (e.g. using <code>-abc</code> to specify <code>-a</code>, <code>-b</code>, and <code>-c</code> in a single token) will still report an error if it contains a mixture of known and unknown options. To avoid this, don\u2019t declare single-letter names for options in commands that use <code>treatUnknownOptionsAsArgs</code>.</p> <p>You\u2019ll often want to set <code>allowInterspersedArgs = false</code> on your Context when using <code>treatUnknownOptionsAsArgs</code>. You may also find that subcommands are a better fit than <code>treatUnknownOptionsAsArgs</code> for your use case.</p>"},{"location":"options/#values-from-environment-variables","title":"Values From Environment Variables","text":"<p>Clikt supports reading option values from environment variables if they aren\u2019t given on the command line. This feature is helpful when automating tools. For example, when using <code>git commit</code>, you can set the author date with a command line parameter: <code>git commit --date=10/21/2015</code>. But you can also set it with an environment variable: <code>GIT_AUTHOR_DATE=10/21/2015 git commit</code>.</p> <p>Clikt will read option values from environment variables as long as it has an envvar name for the option. There are two ways to set that name: you can set the name manually for an option, or you can enable automatic envvar name inference.</p> <p>To set the envvar name manually, pass the name to <code>option</code>:</p> ExampleUsage 1Usage 2 <pre><code>class Hello : CliktCommand() {\n    val name by option(envvar = \"MY_NAME\")\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>$ export MY_NAME=Foo\n$ ./hello\nHello Foo\n</code></pre> <pre><code>$ export MY_NAME=Foo\n$ ./hello --name=Bar\nHello Bar\n</code></pre> <p>You can enable automatic envvar name inference by setting the <code>autoEnvvarPrefix</code> on a command\u2019s <code>context</code>. This will cause all options without an explicit envvar name to be given an uppercase underscore-separated envvar name. Since the prefix is set on the <code>context</code>, it is propagated to subcommands. If you have a subcommand called <code>foo</code> with an option <code>--bar</code>, and your prefix is <code>MY_TOOL</code>, the option\u2019s envvar name will be <code>MY_TOOL_FOO_BAR</code>.</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    init {\n        context { autoEnvvarPrefix = \"HELLO\" }\n    }\n    val name by option()\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>$ export HELLO_NAME=Foo\n$ ./hello\nHello Foo\n</code></pre>"},{"location":"options/#multiple-values-from-environment-variables","title":"Multiple Values from Environment Variables","text":"<p>You might need to allow users to specify multiple values for an option in a single environment variable. You can do this by creating an option with <code>split</code>.</p>"},{"location":"options/#flag-option-values-from-environment-variables","title":"Flag Option Values from Environment Variables","text":"<p>For flag options, any of the following (case-insensitive) environment variable values will be interpreted as <code>true</code>:</p> <ul> <li><code>\"true\"</code>, <code>\"t\"</code>, <code>\"1\"</code>, <code>\"yes\"</code>, <code>\"y\"</code>, <code>\"on\"</code></li> </ul> <p>The following (case-insensitive) values wil be interpreted as <code>false</code>:</p> <ul> <li><code>\"false\"</code>, <code>\"f\"</code>, <code>\"0\"</code>, <code>\"no\"</code>, <code>\"n\"</code>, <code>\"off\"</code></li> </ul> <p>All other values are invalid.</p>"},{"location":"options/#overriding-system-environment-variables","title":"Overriding system environment variables","text":"<p>You can set a custom function that will be used instead of the system environment variables with ContextBuilder.readEnvvar.</p> <pre><code>@Test\nfun `test envvar`() {\n    val envvars = mapOf(\"MY_TOOL_OPTION\" to \"value\")\n    val tool = MyTool().context {\n        readEnvvar = { envvars[it] }\n    }\n    tool.parse(emptyList())\n    assertEquals(\"value\", tool.option)\n}\n</code></pre>"},{"location":"options/#values-from-configuration-files","title":"Values from Configuration Files","text":"<p>Clikt also supports reading option values from one or more configuration files (or other sources) when they aren\u2019t present on the command line. For example, when using <code>git commit</code>, you can set the author email with a command line parameter: <code>git commit --author='Clikt &lt;clikt@example.com&gt;</code>. But you can also set it in your git configuration file: <code>user.email=clikt@example.com</code>.</p> <p>Clikt allows you to specify one or more sources of option values that will be read from with the <code>Context.valueSource</code> builder.</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    init {\n        context {\n            valueSource = PropertiesValueSource.from(\"myconfig.properties\")\n        }\n    }\n    val name by option()\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>$ echo \"name=Foo\" &gt; myconfig.properties\n$ ./hello\nHello Foo\n</code></pre> <p>You can also pass multiple sources to <code>Context.valueSources</code>, and each source will be searched for the value in order.</p> <p>Clikt includes support for reading values from a map, and (on JVM) from Java Properties files. For these two sources, you can customize the keys used to look up options by passing the result of <code>ValueSource.getKey</code> or <code>ValueSource.envvarKey</code> to the source\u2019s <code>getKey</code> constructor parameter.</p> <p>You can add any other file type by implementing ValueSource. See the JSON sample for an implementation that uses kotlinx.serialization to load values from JSON files.</p>"},{"location":"options/#configuration-files-and-environment-variables","title":"Configuration Files and Environment Variables","text":"<p>Every option can read values from both environment variables and configuration files. By default, Clikt will use the value from an environment variable before the value from a configuration file, but you can change this by setting <code>Context.readEnvvarBeforeValueSource</code> to <code>false</code>.</p>"},{"location":"options/#windows-and-java-style-option-prefixes","title":"Windows and Java-Style Option Prefixes","text":"<p>When specifying option names manually, you can use any prefix (as long as it\u2019s entirely punctuation).</p> <p>For example, you can make a Windows-style interface with slashes:</p> ExampleUsage <pre><code>class Hello: CliktCommand() {\n    val name by option(\"/name\", help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello /name Foo\nHello, Foo!\n</code></pre> <p>Or you can make a Java-style interface that uses single-dashes for long options:</p> ExampleUsage <pre><code>class Hello: CliktCommand() {\n    val name by option(\"-name\", help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello -name Foo\nHello, Foo!\n</code></pre> <p>Note</p> <p>Inferred names will always have a POSIX-style prefix like <code>--name</code>. If you want to use a different prefix, you should specify all option names manually.</p>"},{"location":"options/#option-transformation-order","title":"Option Transformation Order","text":"<p>Clikt has a large number of extension functions that can modify options. When applying multiple functions to the same option, there\u2019s only one valid order for the functions to be applied. For example, <code>option().default(3).int()</code> will not compile, because <code>default</code> must be applied after the value type conversion. </p> <p>You can call <code>convert</code> multiple times, but you can only apply one transform of each other type. So <code>option().default(\"\").multiple()</code> is invalid, since <code>default</code> and <code>multiple</code> both transform the call list (if you need a custom default value for <code>multiple</code>, you can pass it one as an argument).</p> <p>Here\u2019s an integer option with one of each available transform in a valid order:</p> <pre><code>val opt: Pair&lt;Int, Int&gt; by option(\"-o\", \"--opt\")\n        .int()\n        .restrictTo(1..100)\n        .pair()\n        .default(1 to 2)\n        .validate { require(it.second % 2 == 0) }\n</code></pre>"},{"location":"parameters/","title":"Parameters","text":"<p>Clikt supports two types of parameters: options and positional arguments. If you\u2019re following Unix conventions with your interface, you should use options for most parameters. Options are usually optional, and arguments are frequently required.</p>"},{"location":"parameters/#differences","title":"Differences","text":"<p>Arguments have the advantage of being able to accept a variable number of values, while Options are limited to a fixed number of values. Other than that restriction, options have more capabilities than arguments.</p> <p>Options can:</p> <ul> <li>Act as flags (options don\u2019t have to take values)</li> <li>Prompt for missing input</li> <li>Load values from environment variables</li> </ul> <p>In general, arguments are usually used for values like file paths or URLs, or for required values, and options are used for everything else.</p>"},{"location":"parameters/#parameter-names","title":"Parameter Names","text":"<p>Both options and arguments can infer their names (or the metavar in the case of arguments) from the name of the property. You can also specify the names manually. Options can have any number of names, where arguments only have a single metavar.</p> ExampleHelp Output <pre><code>class Cli : CliktCommand() {\n    val inferredOpt by option()\n    val inferred by argument()\n    val explicitOpt by option(\"-e\", \"--explicit\")\n    val explicitArg by argument(\"&lt;explicit&gt;\")\n    override fun run() = Unit\n}\n</code></pre> <pre><code>Usage: cli [&lt;options&gt;] &lt;inferred&gt; &lt;explicit&gt;\n\nOptions:\n  --inferred-opt &lt;text&gt;\n  -e, --explicit &lt;text&gt;\n  -h, --help           Show this message and exit\n</code></pre>"},{"location":"parameters/#parameter-types","title":"Parameter Types","text":"<p>Both options and arguments can convert the String that the user inputs to other types.</p> <p>Types work by transforming the return value of the property delegate. By default, parameters have a string type:</p> <pre><code>val opt: String? by option(help=\"an option\")\nval arg: String by argument(help=\"an argument\")\n</code></pre> <p>To convert the input to an integer, for example, use the <code>int()</code> extension function:</p> <pre><code>val opt: Int? by option(help=\"an option\").int()\nval arg: Int by argument(help=\"an argument\").int()\n</code></pre>"},{"location":"parameters/#built-in-types","title":"Built-In Types","text":"<p>There are a number of built-in types that can be applied to options and arguments.</p>"},{"location":"parameters/#int-and-long","title":"Int and Long","text":"<ul> <li><code>option().int()</code> and <code>argument().int()</code></li> <li><code>option().long()</code> and <code>argument().long()</code></li> <li><code>option().uint()</code> and <code>argument().uint()</code></li> <li><code>option().ulong()</code> and <code>argument().ulong()</code></li> </ul> <p>By default, any value that fits in the integer type is accepted. You can restrict the values to a range with <code>restrictTo()</code>, which allows you to either clamp the input to the range, or fail with an error if the input is outside the range.</p>"},{"location":"parameters/#float-and-double","title":"Float and Double","text":"<ul> <li><code>option().float()</code> and <code>argument().float()</code></li> <li><code>option().double()</code> and <code>argument().double()</code></li> </ul> <p>As with integers, you can restrict the input to a range with <code>restrictTo()</code>.</p>"},{"location":"parameters/#boolean","title":"Boolean","text":"<ul> <li><code>option().flag()</code></li> <li><code>option().boolean()</code> and <code>argument().boolean()</code></li> </ul> <p>You will normally want to use flags for boolean options. Explicit boolean value conversion is also available if you need, for example, a tri-state <code>Boolean?</code> parameter.</p>"},{"location":"parameters/#choice","title":"Choice","text":"<ul> <li><code>option().choice()</code> and <code>argument().choice()</code></li> </ul> <p>You can restrict the values to a set of values, and optionally map the input to a new value. For example, to create an option that only accepts the value \u201ca\u201d or \u201cb\u201d:</p> <pre><code>val opt: String? by option().choice(\"a\", \"b\")\n</code></pre> <p>You can also convert the restricted set of values to a new type:</p> <pre><code>val color: Int? by argument().choice(\"red\" to 1, \"green\" to 2)\n</code></pre> <p>Choice parameters accept values that are case-sensitive by default. This can be configured by passing <code>ignoreCase = true</code>.</p>"},{"location":"parameters/#enum","title":"Enum","text":"<ul> <li><code>option().enum()</code> and <code>argument().enum()</code></li> </ul> <p>Like <code>choice</code>, but uses the values of an enum type.</p> <pre><code>enum class Color { RED, GREEN }\nval color: Color? by option().enum&lt;Color&gt;()\n</code></pre> <p>Enum parameters accept case-insensitive values by default. This can be configured by passing <code>ignoreCase = false</code>. </p> <p>You can also pass a lambda to map the enum values to option names.</p> <pre><code>val color: Color? by option().enum&lt;Color&gt; { it.name.lowercase() }\n</code></pre>"},{"location":"parameters/#file-paths","title":"File paths","text":"<ul> <li><code>option().file()</code> and <code>argument().file()</code></li> <li><code>option().path()</code> and <code>argument().path()</code></li> </ul> <p>These conversion functions take extra parameters that allow you to require that values are file paths that have certain attributes, such as that they are directories, or they are writable files.</p>"},{"location":"parameters/#file-path-inputstream-and-outputstreams","title":"File path <code>InputStream</code> and <code>OutputStream</code>s","text":"<ul> <li><code>option().inputStream()</code> and <code>argument().inputStream()</code></li> <li><code>option().outputStream()</code> and <code>argument().outputStream()</code></li> </ul> <p>Like file and path, these conversions take file path values, but expose them as open streams for reading or writing. They support the unix convention of passing <code>-</code> to specify stdin or stdout rather than a file on the filesystem. You\u2019ll need to close the streams yourself. You can also use stdin or stdout as their default values.</p> <p>If you need to check if one of these streams is pointing to a file rather than stdin or stdout, you can use <code>isCliktParameterDefaultStdin</code> or <code>isCliktParameterDefaultStdout</code>.</p>"},{"location":"parameters/#custom-types","title":"Custom Types","text":"<p>You can convert parameter values to a custom type by using <code>argument().convert()</code> and <code>option().convert()</code>. These functions take a lambda that converts the input <code>String</code> to any type. If the parameter takes multiple values, or an option appears multiple times in <code>argv</code>, the conversion lambda is called once for each value.</p> <p>Any errors that are thrown from the lambda are automatically caught and a usage message is printed to the user. If you need to trigger conversion failure, you can use <code>fail(\"error message\")</code> instead of raising an exception.</p> <p>For example, you can create an option of type <code>BigDecimal</code> like this:</p> ExampleUsage 1Usage 2 <pre><code>class Cli: CliktCommand() {\n    val opt by option().convert { it.toBigDecimal() }\n    override fun run() = echo(\"opt=$opt\")\n}\n</code></pre> <pre><code>$ ./cli --opt=1.5\nopt=1.5\n</code></pre> <pre><code>$ ./cli --opt=foo\nUsage: cli [&lt;options&gt;]\n\nError: Invalid value for \"--opt\": For input string: \"foo\"\n</code></pre>"},{"location":"parameters/#metavars","title":"Metavars","text":"<p>You can also pass <code>option().convert()</code> a metavar that will be printed in the help page instead of the default of <code>value</code>. We can modify the above example to use a metavar and an explicit error message:</p> ExampleUsage 1Usage 2 <pre><code>class Cli: CliktCommand() {\n    val opt by option(help=\"a real number\").convert(\"float\") {\n        it.toBigDecimalOrNull() ?: fail(\"A real number is required\")\n    }\n    override fun run() = echo(\"opt=$opt\")\n}\n</code></pre> <pre><code>$ ./cli --opt=foo\nUsage: cli [&lt;options&gt;]\n\nError: Invalid value for \"--opt\": A real number is required\n</code></pre> <pre><code>$ ./cli --help\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  --opt &lt;float&gt;  a real number\n  -h, --help     Show this message and exit\n</code></pre>"},{"location":"parameters/#chaining","title":"Chaining","text":"<p>You can call <code>convert</code> more than once on the same parameter. This allows you to reuse existing conversion functions. For example, you could automatically read the text of a file parameter.</p> ExampleUsage <pre><code>class FileReader: CliktCommand() {\n    val file: String by argument()\n        .file(mustExist=true, canBeDir=false)\n        .convert { it.readText() }\n    override fun run() {\n        echo(\"Your file contents: $file\")\n    }\n}\n</code></pre> <pre><code>$ echo 'some text' &gt; myfile.txt\n$ ./filereader ./myfile.txt\nYour file contents: some text\n</code></pre>"},{"location":"parameters/#parameter-validation","title":"Parameter Validation","text":"<p>After converting a value to a new type, you can perform additional validation on the converted value with <code>check()</code> and <code>validate()</code> (or the argument equivalents).</p>"},{"location":"parameters/#check","title":"<code>check()</code>","text":"<p><code>check()</code> is similar the stdlib function of the same name: it takes lambda that returns a boolean to indicate if the parameter value is valid or not, and reports an error if it returns false. The lambda is only called if the parameter value is non-null.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>class Tool : CliktCommand() {\n    val number by option(help = \"An even number\").int()\n            .check(\"value must be even\") { it % 2 == 0 }\n\n    override fun run() {\n        echo(\"number=$number\")\n    }\n}\n</code></pre> <pre><code>$ ./tool --number=2\nnumber=2\n</code></pre> <pre><code>$ ./tool\nnumber=null\n</code></pre> <pre><code>$ ./tool --number=1\nUsage: tool [&lt;options&gt;]\n\nError: invalid value for --number: value must be even\n</code></pre>"},{"location":"parameters/#validate","title":"<code>validate()</code>","text":"<p>For more complex validation, you can use <code>validate()</code>. This function takes a lambda that returns nothing, but can call <code>fail(\"error message\")</code> if the value is invalid. You can also call <code>require()</code>, which will fail if the provided expression is false. Like <code>check</code>, the lambda is only called if the value is non-null.</p> <p>The lambdas you pass to <code>validate</code> are called after the values for all options and arguments have been set, so (unlike in transforms) you can reference other parameters:</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    val number by option().int().default(0)\n    val biggerNumber by option().int().validate {\n        require(it &gt; number) {\n            \"--bigger-number must be bigger than --number\"\n        }\n    }\n\n    override fun run() {\n        echo(\"number=$number, biggerNumber=$biggerNumber\")\n    }\n}\n</code></pre> <pre><code>$ ./tool --number=1\nnumber=1, biggerNumber=null\n</code></pre> <pre><code>$ ./tool --number=1 --bigger-number=0\nUsage: tool [&lt;options&gt;]\n\nError: --bigger-number must be bigger than --number\n</code></pre>"},{"location":"quickstart/","title":"Quick Start","text":"<p>You can get the library using any maven-compatible build system. Installation instructions can be found in the README.</p>"},{"location":"quickstart/#basic-concepts","title":"Basic Concepts","text":"<p>Clikt command line interfaces are created by using property delegates inside a <code>CliktCommand</code>. The normal way to use Clikt is to forward <code>argv</code> from your <code>main</code> function to <code>CliktCommand.main</code>.</p> <p>The simplest command with no parameters would look like this:</p> <pre><code>import com.github.ajalt.clikt.core.CliktCommand\nimport com.github.ajalt.clikt.core.main\n\nclass Hello: CliktCommand() {\n    override fun run() {\n        echo(\"Hello World!\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Hello().main(args)\n</code></pre> <p>And what it looks like to use:</p> <pre><code>$ ./hello\nHello World!\n</code></pre> <p>A help page is generated automatically:</p> <pre><code>$ ./hello --help\nUsage: hello [&lt;options&gt;]\n\nOptions:\n  -h, --help  Show this message and exit\n</code></pre>"},{"location":"quickstart/#printing-to-stdout-and-stderr","title":"Printing to Stdout and Stderr","text":"<p>Why does this example use <code>echo</code> instead of <code>println</code>? Although <code>println</code> works, it can cause problems with multi-platform support. <code>echo</code> uses Mordant to print, so it supports colors and detects the current terminal to make sure that colors work on the current system. You can also pass <code>err=true</code> to <code>echo</code> to print to stderr instead of stdout.</p> <p>Additionally, if you use Clikt\u2019s testing utilities, output sent  to <code>echo</code> will be captured for testing, but output sent to <code>println</code> will not.</p>"},{"location":"quickstart/#coroutine-commands-with-suspend-functions","title":"Coroutine commands with suspend functions","text":"<p>If you want to use coroutines in your command, you can use a SuspendingCliktCommand:</p> <pre><code>class Hello : SuspendingCliktCommand() {\n    val count by option(help=\"Number of greetings\").int().default(1)\n    val name by argument()\n\n    override suspend fun run() {\n        for (i in 1..count) {\n            echo(\"Hello $name!\")\n            delay(1000)\n        }\n    }\n}\n\nsuspend fun main(args: Array&lt;String&gt;) = Hello().main(args)\n</code></pre>"},{"location":"quickstart/#nesting-commands","title":"Nesting Commands","text":"<p>Instances of any command can be attached to other commands, allowing arbitrary nesting of commands. For example, you could write a script to manage a database:</p> ExampleUsageHelp Output <pre><code>class Database : CliktCommand(name = \"db\") {\n    override fun run() = Unit\n}\n\nclass Init : CliktCommand() {\n    override fun help(context: Context) = \"Initialize the database\"\n    override fun run() {\n        echo(\"Initialized the database.\")\n    }\n}\n\nclass Drop : CliktCommand() {\n    override fun help(context: Context) = \"Drop the database\"\n    override fun run() {\n        echo(\"Dropped the database.\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Database()\n        .subcommands(Init(), Drop())\n        .main(args)\n</code></pre> <pre><code>$ ./db init\nInitialized the database.\n\n$ ./db drop\nDropped the database.\n</code></pre> <pre><code>$ ./db --help\nUsage: database [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  -h, --help  Show this message and exit\n\nCommands:\n  init  Initialize the database\n  drop  Drop the database\n</code></pre>"},{"location":"quickstart/#adding-parameters","title":"Adding Parameters","text":"<p>To add parameters, use the <code>option</code> and <code>argument</code> property delegates:</p> ExampleHelp Output <pre><code>class Hello : CliktCommand() {\n    val count by option(help=\"Number of greetings\").int().default(1)\n    val name by argument()\n\n    override fun run() {\n        for (i in 1..count) {\n            echo(\"Hello $name!\")\n        }\n    }\n}\n</code></pre> <pre><code>$ ./hello --help\nUsage: hello [&lt;options&gt;] &lt;name&gt;\n\nOptions:\n  --count &lt;int&gt;  Number of greetings\n  -h, --help     Show this message and exit\n</code></pre>"},{"location":"quickstart/#developing-command-line-applications-with-gradle","title":"Developing Command Line Applications With Gradle","text":"<p>When you write a command line application, you probably want to be able to run it without invoking <code>java -jar ...</code> every time. If you\u2019re using Gradle, the application plugin provides a gradle task that bundles your program jars and scripts to launch them. It makes it easy to build a zip or tarball that you can distribute to your users without them needing to perform any incantations like setting up a classpath. You can see this plugin in use the in Clikt samples.</p> <p>The application plugin also creates tasks that will build then run your main function directly from within gradle. You can pass command line arguments through to your app with the <code>--args</code> flag:</p> <pre><code>$ ./gradlew run --args=\"--count=3 Clikt\"\n</code></pre> <p>A drawback to using the <code>run</code> gradle task is that it redirects stdout, so Clikt will not print colors or prompt for input. You can configure the Mordant terminal that Clikt uses to always print with color, but this will cause ANSI codes to be printed even if you redirect the app\u2019s output to a file.</p> <pre><code>MyCommand().context {\n    terminal = Terminal(ansiLevel = AnsiLevel.TRUECOLOR, interactive = true)\n}.main(args)\n</code></pre> <p>Another approach is to use the <code>installDist</code> task provided by the plugin. This builds all the distribution scripts in your build folder, which you can then execute normally. See Clikt\u2019s runsample script for an example of this approach.</p>"},{"location":"testing/","title":"Testing Clikt Commands","text":"<p>Clikt includes the <code>test</code> extension to help testing commands and their output.</p> TestCommand <pre><code>@Test\nfun testHello() {\n    val command = Hello()\n    val result = command.test(\"--name Foo\")\n    assertEqual(result.stdout, \"Hello, Foo!\")\n    assertEqual(result.exitCode, 0)\n    assertEqual(command.name, \"Foo\")\n}\n</code></pre> <pre><code>class Hello: CliktCommand() {\n    val name by option()\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <p>Calling <code>test</code> will run the command with the given arguments and return a result object that contains the captured outputs and result status code. You can check the captured output with the <code>stdout</code> property of the result, errors output with <code>stderr</code>, or both combined in with <code>output</code>.</p> <p>Caution</p> <p>Output printed with Kotlin\u2019s <code>print</code> and <code>println</code> functions are not captured.  Use <code>echo</code> instead.</p>"},{"location":"testing/#testing-environment-variables","title":"Testing Environment Variables","text":"<p>You can set environment variables for your command by passing in a map of <code>envvars</code>.</p> TestCommand <pre><code>@Test\nfun testHello() {\n    val command = Hello()\n    val result = command.test(\"\", envvars=mapOf(\"HELLO_NAME\" to \"Foo\"))\n    assertEqual(result.stdout, \"Hello, Foo!\")\n}\n</code></pre> <pre><code>class Hello: CliktCommand() {\n    val name by option(envvar=\"HELLO_NAME\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <p>To keep tests reproducible, only the envvar values you provide to <code>test</code> are visible to the command. To include system envvars as well, pass <code>includeSystemEnvvars=true</code> to <code>test</code>.</p>"},{"location":"testing/#testing-prompt-options","title":"Testing Prompt Options","text":"<p>If you use <code>prompt</code> options, you can use the <code>stdin</code> parameter of <code>test</code> to pass a string containing all the lines of input. If you have multiple prompts, each input should be separated by <code>\\n</code>.</p> TestCommand <pre><code>@Test\nfun testAdder() {\n    val command = Adder()\n    val result = command.test(\"\", stdin = \"2\\n3\")\n    assertEqual(result.stdout, \"first: second: result: 2 + 3 = 5\")\n}\n</code></pre> <pre><code>class Adder : TestCommand() {\n    val first by option().prompt()\n    val second by option().prompt()\n\n    override fun run_() {\n        echo(\"result: $first + $second = ${first + second}\")\n    }\n}\n</code></pre>"},{"location":"testing/#custom-testing","title":"Custom Testing","text":"<p>If the <code>test</code> helper doesn\u2019t cover all the use cases you need to test, you can run your command yourself.</p> <p>If your command uses environment variables, you can configure the context to return test values for them.</p> <p>To capture output, override the command\u2019s console.</p> <p>By default <code>CliktCommand.main</code>, calls <code>exitProcess</code> when errors occur, which would stop tests from running. You have a couple of choices to handle this:</p>"},{"location":"testing/#configuring-exitprocess","title":"Configuring <code>exitProcess</code>","text":"<p><code>CliktCommand.main</code> calls <code>Context.exitProcess</code> to exit the process. You can set that to an empty lambda to skip it, or one that captures the status value if you want to check it in you tests.</p>"},{"location":"testing/#using-parse-instead-of-main","title":"Using <code>parse</code> instead of <code>main</code>","text":"<p>Instead of calling <code>main</code>, you can use <code>CliktCommand.parse</code>, which throws exceptions with error details rather than printing the details and exiting the process. See the documentation on exceptions for more information on the exceptions that can be thrown.</p>"},{"location":"utilities/","title":"Utilities","text":"<p>Writing command line interfaces often involves more than just parsing the command line. Clikt also provides functions to perform actions commonly used in command line programs.</p>"},{"location":"utilities/#launching-editors","title":"Launching Editors","text":"<p>If you need to ask users for multi-line input, or need to have the user edit a file, you can do so through <code>editText</code> and <code>editFile</code>. These functions open the program defined in the <code>VISUAL</code> or <code>EDITOR</code> environment variables, or a sensible default if neither are defined. The functions return the edited text if the user saved their changes.</p> Example <pre><code>fun getCommitMessage(): String? {\n    val message = \"\"\"\n    # Enter your message.\n    # Lines starting with # are ignored\n    \"\"\".trimIndent()\n    return editText(message, requireSave = true)\n            ?.replace(Regex(\"#[^\\n]*\\n\"), \"\")\n}\n</code></pre>"},{"location":"utilities/#input-prompts","title":"Input Prompts","text":"<p>Options can prompt for values automatically, but you can also do so manually by using Mordant\u2019s prompt functionality directly. By default, it accepts any input string, but you can also pass in a conversion function. If the conversion returns a <code>ConversionResult.Invalid</code>, the prompt will ask the user to enter a different value.</p> ExampleInteractive Session <pre><code>val input = terminal.prompt(\"Enter a number\") {\n    it.toIntOrNull()\n        ?.let { ConversionResult.Valid(it) }\n        ?: ConversionResult.Invalid(\"$it is not a valid integer\")\n}\necho(\"Twice your number is ${input * 2}\")\n</code></pre> <pre><code>Enter a number: foo\nError: foo is not a valid integer\nEnter a number: 11\nTwice your number is 22\n</code></pre>"},{"location":"utilities/#confirmation-prompts","title":"Confirmation Prompts","text":"<p>You can also ask the user for a yes or no response with Mordant\u2019s <code>YesNoPrompt</code>:</p> <pre><code>if (YesNoPrompt(\"Continue?\", terminal).ask() == true) {\n    echo(\"Ok!\")\n}\n</code></pre>"},{"location":"whyclikt/","title":"Why Clikt?","text":"<p>There are existing Kotlin libraries for creating command line interfaces, and many Java libraries work in Kotlin as well. However, none of them had all the following features:</p> <ul> <li>Unrestricted composability of commands</li> <li>Fully static type safety for parameters</li> <li>Composable parameter customization that doesn\u2019t require registering converter objects.</li> <li>Full support for Unix command line conventions</li> <li>Capable of reading parameter values from environment variables out of the box</li> <li>Included support for common functionality (keyboard interactivity, line ending normalization, launching editors, etc.)</li> <li>Built-in support for multi-token command aliases</li> </ul> <p>Clikt is focused on making writing robust, posix-compliant command line interfaces as easy as possible. A good CLI does more than just parse <code>argv</code>. It allows users to specify values in environment variables, and in some cases prompts for additional input, or opens an editor. Clikt supports all of this out of the box.</p> <p>Sometimes you need to make a CLI that doesn\u2019t follow Unix conventions. You might be writing for windows, or you want to use the Java style of long options with a single dash. Maybe you need to use a bunch of required options instead of arguments, or you want the help page formatted differently. \u201cBest practices\u201d might not be the best for you, so Clikt tries to make implementing uncommon use-cases as easy as possible.</p>"},{"location":"whyclikt/#why-not-a-kotlin-library-like-kotlin-argparser-or-kotlinxcli","title":"Why not a Kotlin library like kotlin-argparser or kotlinx.cli?","text":"<p>Clikt isn\u2019t the only Kotlin CLI library. kotlin-argparser and kotlinx.cli both predate Clikt\u2019s creation.</p> <p>Both, like Clikt, use property delegates to define parameters, but they\u2019re missing most of Clikt features and its extensible design.</p> <p>kotlinx.cli was written by JetBrains and mostly copied kotlin-argparser\u2019s design (and, later, some of Clikt\u2019s).</p> <p>kotlin-argparser works well for simple cases. It\u2019s missing a lot of features that Clikt has, but features could be added. Its real drawback is that it fundamentally does not support composition of commands or parameter values. The lack of subcommand support was already a non-starter, but there are other design decisions that make it unsuitable.</p> <p>In the simple cases, the two libraries are similar. Here\u2019s an example from its README:</p> <pre><code>class MyArgs(parser: ArgParser) {\n    val v: Boolean by parser.flagging(help=\"enable verbose mode\")\n    val username: String? by parser.storing(help=\"name of the user\")\n    val count: Int? by parser.storing(help=\"number of the widgets\") { toInt() }\n    val source: List&lt;String&gt; by parser.positionalList(help=\"source filenames\")\n    val destination: String by parser.positional(help=\"destination\")\n}\n\nfun main(args: Array&lt;String&gt;) = mainBody {\n    ArgParser(args).parseInto(::MyArgs).run {\n        println(\"Hello, $username!\")\n        println(\"Moving $count widgets from $source to $destination.\")\n    }\n}\n</code></pre> <p>Here\u2019s the same thing with Clikt:</p> <pre><code>class Cli : CliktCommand() {\n    val v: Boolean by option(help = \"enable verbose mode\").flag()\n    val username: String? by option(help = \"name of the user\")\n    val count: Int? by option(help = \"number of the widgets\").int()\n    val source: List&lt;String&gt; by argument(help = \"source filenames\").multiple()\n    val destination: String by argument(help = \"destination\")\n    override fun run() {\n        println(\"Hello, $name!\")\n        println(\"Moving $count widgets from $source to $destination.\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Cli().main(args)\n</code></pre> <p>Both work fine, although you may find Clikt more consistent and a bit less verbose. The differences become more pronounced once you try to do anything that isn\u2019t built in to kotlin-argparser.</p> <p>Maybe you need an option to take two values. Here\u2019s another example from the <code>kotlin-argparser</code> README showing how to do that:</p> <pre><code>fun ArgParser.putting(vararg names: String, help: String) =\n          option&lt;MutableMap&lt;String, String&gt;&gt;(*names,\n                  argNames = listOf(\"KEY\", \"VALUE\"),\n                  help = help) {\n              value.orElse { mutableMapOf&lt;String, String&gt;() }.apply {\n                  put(arguments.first(), arguments.last()) }\n          }\n\n fun ArgParser.putting(help: String) =\n          ArgParser.DelegateProvider { identifier -&gt;\n              putting(identifierToOptionName(identifier), help = help) }\n\nclass MyArgs(parser: ArgParser) {\n    val v by parser.putting(help=\"this takes two values\")\n}\n</code></pre> <p>Clikt has that functionality built in as <code>option().pair()</code>, but you could implement it yourself like this:</p> <pre><code>class Cli : CliktCommand() {\n    val v by option(help=\"this takes two values\").transformValues(2) { it[0] to it[1] }\n}\n</code></pre> <p>The Clikt version is of course much simpler, but there are more fundamental issues with the <code>kotlin-argparser</code> version that drove the creation of Clikt:</p> <ul> <li>Its inheritance-based design means that if you wanted to change the type of each value, you would have to copy all the code for each type. With Clikt, you could just do <code>option().int().transformValues(2) { it[0] to it[1] }</code></li> <li>Its inheritance-based design means that supporting types, multiple values, and multiple option occurrences would require a combinatorial number of copies of the above code. With Clikt, these are all orthogonal.</li> <li>You have to do all error checking yourself. The <code>argparser</code> example silently discards extra values, or copies the single value, rather than inform the user of the mistake. You could write more code to do so, but Clikt takes care of it for you.</li> <li>Option name inference is not automatic, requiring you to wrap the delegate with yet another function.</li> <li>Each delegate function has a different name, with no indication of whether it\u2019s creating an option or positional argument. With Clikt, all options are created with <code>option()</code>, and all arguments with <code>argument()</code>.</li> </ul> <p>Some of these problems can be solved by writing more code, and some can\u2019t. On the other hand, Clikt attempts to have a consistent, intuitive, composable design that does the right thing without forcing you to think about edge cases.</p>"},{"location":"whyclikt/#why-not-a-java-library-like-jcommander-or-picocli","title":"Why not a Java library like JCommander or Picocli?","text":"<p>There are a lot of command line libraries for Java. Most are verbose and not composable. Two popular Java libraries that are usable from Kotlin are JCommander and picocli.</p> <p>These libraries use annotations to define parameters, and reflection to set fields. This is functional for simple types, but defining your own types requires you to register a type adapter with the library. This means that type errors are not caught until runtime, and many types of customization are not possible.</p> <p>For example, in JCommander, options that take multiple values cannot be converted to other types. The JCommander docs explain:</p> <p>\u2026 only List is allowed for parameters that define an arity. You will have to convert these values yourself if the parameters you need are of type Integer or other (this limitation is due to Java\u2019s erasure). <p>You also can\u2019t customize many aspects of parsing in JCommander. It can\u2019t infer parameter names. With JCommander, you can\u2019t have an option with multiple values and multiple occurrences at the same time. You can\u2019t have more than one argument, and it can only take one value or an unlimited number of values. You can\u2019t nest subcommands.</p> <p>JCommander and piocli are great libraries if you\u2019re writing code in Java, but we can do much better with Kotlin.</p>"}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Home","text":"<p>Clikt (pronounced \u201cclicked\u201d) is a multiplatform Kotlin library that makes writing command line interfaces simple and intuitive. It\u2019s the \u201cCommand Line Interface for Kotlin\u201d.</p> <p>It is designed to make the process of writing command line tools effortless while supporting a wide variety of use cases and allowing advanced customization when needed.</p> <p>Clikt has:</p> <ul> <li>arbitrary nesting of commands</li> <li>composable, type safe parameter values</li> <li>generation of help output and shell autocomplete scripts</li> <li>multiplatform packages for JVM, Node.js, and native Linux, Windows and macOS </li> </ul> <p>What does it look like? Here\u2019s a complete example of a simple Clikt program:</p> <pre><code>class Hello : CliktCommand() {\n    val count: Int by option().int().default(1).help(\"Number of greetings\")\n    val name: String by option().prompt(\"Your name\").help(\"The person to greet\")\n\n    override fun run() {\n        repeat(count) {\n            echo(\"Hello $name!\")\n        }\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Hello().main(args)\n</code></pre> <p>And here\u2019s what it looks like when run:</p> <p></p> <p>The help page is generated for you:</p> <p></p> <p>Errors are also taken care of:</p> <p></p>"},{"location":"#installation","title":"Installation","text":"<p>Clikt is distributed through Maven Central.</p> <pre><code>dependencies {\n   implementation(\"com.github.ajalt.clikt:clikt:5.0.0\")\n\n   // optional support for rendering markdown in help messages\n   implementation(\"com.github.ajalt.clikt:clikt-markdown:5.0.0\")\n}\n</code></pre> <p>There is also a smaller core module available. See the docs for details.</p>"},{"location":"#if-youre-using-maven-instead-of-gradle-use-artifactidclikt-jvmartifactid","title":"If you\u2019re using Maven instead of Gradle, use <code>&lt;artifactId&gt;clikt-jvm&lt;/artifactId&gt;</code>","text":""},{"location":"#multiplatform","title":"Multiplatform","text":"<p>Clikt supports most multiplatform targets. See the docs  for more information about functionality supported on each target. You\u2019ll need to use Gradle 6 or newer.</p>"},{"location":"#snapshots","title":"Snapshots","text":"Snapshot builds are also available <p> You'll need to add the Sonatype snapshots repository:   <pre><code>repositories {\n    maven {\n        url = uri(\"https://oss.sonatype.org/content/repositories/snapshots/\")\n    }\n}\n</code></pre> </p>"},{"location":"#api-reference","title":"API Reference","text":"<ul> <li>Commands and Exceptions</li> <li>Options</li> <li>Arguments</li> <li>Parameter Type Conversions</li> <li>Output Formatting</li> </ul>"},{"location":"advanced/","title":"Advanced Patterns","text":""},{"location":"advanced/#common-options-with-subcommands","title":"Common Options With Subcommands","text":"<p>In some cases, you will have multiple subcommands that all share a common set of options. For example, you may have an option for a config file, or an output directory, or some API credentials. There are several ways to structure your commands to avoid repeating the option declarations in each subcommand.</p>"},{"location":"advanced/#defining-common-options-on-the-root-command","title":"Defining Common Options on the Root Command","text":"<p>You can define your options on the root command and pass down the information via the context. With this design, you\u2019ll have to specify the common options before the subcommand name on the command line.</p> ExampleUsage 1Usage 2 <pre><code>class Config(val token: String, val hostname: String)\n\nclass MyApi : CliktCommand() {\n    private val token by option(help=\"api token to use for requests\").default(\"...\")\n    private val hostname by option(help=\"base url for requests\").default(\"example.com\")\n\n    override fun run() {\n        currentContext.obj = Config(token, hostname)\n    }\n}\n\nclass Store : CliktCommand() {\n    private val file by option(help=\"file to store\").file(canBeDir = false)\n    private val config by requireObject&lt;Config&gt;()\n    override fun run() {\n        myApiStoreFile(config.token, config.hostname, file)\n    }\n}\n\nclass Fetch : CliktCommand() {\n    private val outdir by option(help=\"directory to store file in\").file(canBeFile = false)\n    private val config by requireObject&lt;Config&gt;()\n    override fun run() {\n        myApiFetchFile(config.token, config.hostname, outdir)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = MyApi().subcommands(Store(), Fetch()).main(args)\n</code></pre> <pre><code>$ ./myapi --hostname=https://example.com store file.txt\n</code></pre> <pre><code>$ ./myapi --hostname=https://example.com fetch --outdir=./out\n</code></pre>"},{"location":"advanced/#defining-common-options-in-a-group","title":"Defining Common Options in a Group","text":"<p>Instead of defining your common options on the root command, you can instead define them in an OptionGroup which you include in each subcommand. This allows you to specify all options after the subcommand name.</p> ExampleUsage 1Usage 2 <pre><code>class CommonOptions: OptionGroup(\"Standard Options:\") {\n    val token by option(help=\"api token to use for requests\").default(\"...\")\n    val hostname by option(help=\"base url for requests\").default(\"example.com\")\n}\n\nclass MyApi : NoOpCliktCommand()\n\nclass Store : CliktCommand() {\n    private val commonOptions by CommonOptions()\n    private val file by option(help=\"file to store\").file(canBeDir = false)\n    override fun run() {\n        myApiStoreFile(commonOptions.token, commonOptions.hostname, file)\n    }\n}\n\nclass Fetch : CliktCommand() {\n    private val commonOptions by CommonOptions()\n    private val outdir by option(help=\"directory to store file in\").file(canBeFile = false)\n    override fun run() {\n        myApiFetchFile(commonOptions.token, commonOptions.hostname, outdir)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = MyApi().subcommands(Store(), Fetch()).main(args)\n</code></pre> <pre><code>$ ./myapi store --hostname=https://example.com file.txt\n</code></pre> <pre><code>$ ./myapi fetch --hostname=https://example.com --outdir=./out\n</code></pre>"},{"location":"advanced/#defining-common-options-in-a-base-class","title":"Defining Common Options in a Base Class","text":"<p>A third design to share options is to define the common options in a base class that all the subcommands inherit from.</p> ExampleUsage 1Usage 2 <pre><code>abstract class MyApiSubcommand : CliktCommand() {\n    val token by option(help = \"api token to use for requests\").default(\"...\")\n    val hostname by option(help = \"base url for requests\").default(\"example.com\")\n}\n\nclass MyApi : NoOpCliktCommand()\n\nclass Store : MyApiSubcommand() {\n    private val file by option(help = \"file to store\").file(canBeDir = false)\n    override fun run() {\n        myApiStoreFile(token, hostname, file)\n    }\n}\n\nclass Fetch : MyApiSubcommand() {\n    private val outdir by option(help = \"directory to store file in\").file(canBeFile = false)\n    override fun run() {\n        myApiFetchFile(token, hostname, outdir)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = MyApi().subcommands(Store(), Fetch()).main(args)\n</code></pre> <pre><code>$ ./myapi store --hostname=https://example.com file.txt\n</code></pre> <pre><code>$ ./myapi fetch --hostname=https://example.com --outdir=./out\n</code></pre>"},{"location":"advanced/#command-aliases","title":"Command Aliases","text":"<p>Clikt allows commands to alias command names to sequences of tokens. This allows you to implement common patterns like allowing the user to invoke a command by typing a prefix of its name, or user-defined aliases like the way you can configure git to accept <code>git ci</code> as an alias for <code>git commit</code>.</p> <p>To implement command aliases, override <code>CliktCommand.aliases</code> in your command. This function is called once at the start of parsing, and returns a map of aliases to the tokens that they alias to.</p> <p>To implement git-style aliases:</p> ExampleUsage 1Usage 2 <pre><code>class Repo : NoOpCliktCommand() {\n    // You could load the aliases from a config file etc.\n    override fun aliases(): Map&lt;String, List&lt;String&gt;&gt; = mapOf(\n            \"ci\" to listOf(\"commit\"),\n            \"cm\" to listOf(\"commit\", \"-m\")\n    )\n}\n\nclass Commit: CliktCommand() {\n    val message by option(\"-m\").default(\"\")\n    override fun run() {\n        echo(\"Committing with message: $message\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Repo().subcommands(Commit()).main(args)\n</code></pre> <pre><code>$ ./repo ci -m 'my message'\nCommitting with message: my message\n</code></pre> <pre><code>$ ./repo cm 'my message'\nCommitting with message: my message\n</code></pre> <p>Note</p> <p>Aliases are not expanded recursively: none of the tokens that an alias expands to will be expanded again, even if they match another alias.</p> <p>You also use this functionality to implement command prefixes:</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand() {\n    override fun aliases(): Map&lt;String, List&lt;String&gt;&gt; {\n        val prefixCounts = mutableMapOf&lt;String, Int&gt;().withDefault { 0 }\n        val prefixes = mutableMapOf&lt;String, List&lt;String&gt;&gt;()\n        for (name in registeredSubcommandNames()) {\n            if (name.length &lt; 3) continue\n            for (i in 1..name.lastIndex) {\n                val prefix = name.substring(0..i)\n                prefixCounts[prefix] = prefixCounts.getValue(prefix) + 1\n                prefixes[prefix] = listOf(name)\n            }\n        }\n        return prefixes.filterKeys { prefixCounts.getValue(it) == 1 }\n    }\n}\n\nclass Foo: CliktCommand() {\n    override fun run() {\n        echo(\"Running Foo\")\n    }\n}\n\nclass Bar: CliktCommand() {\n    override fun run() {\n        echo(\"Running Bar\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Foo(), Bar()).main(args)\n</code></pre> <pre><code>$ ./tool ba\nRunning Bar\n</code></pre>"},{"location":"advanced/#token-normalization","title":"Token Normalization","text":"<p>To prevent ambiguities in parsing, aliases are only supported for command names. However, there\u2019s another way to modify user input that works on more types of tokens. You can set <code>transformToken</code> on the command\u2019s context, which will be called for each option and command name that\u2019s input. This can be used to implement case-insensitive parsing, for example:</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    init {\n        context { transformToken = { it.lowercase() } }\n    }\n\n    val name by option()\n    override fun run() = echo(\"Hello $name!\")\n}\n</code></pre> <pre><code>$ ./hello --NAME=Clikt\nHello Clikt!\n</code></pre>"},{"location":"advanced/#replacing-stdin-and-stdout","title":"Replacing stdin and stdout","text":"<p>By default, functions like <code>CliktCommand.main</code> and <code>option().prompt()</code> read from stdin and write to stdout. If you want to use Clikt in an environment where the standard streams aren\u2019t available, you can set your own implementation of a <code>TerminalInterface</code> when customizing the command context.</p> <pre><code>object MyInterface : TerminalInterface {\n    override val info: TerminalInfo\n        get() = TerminalInfo(/* ... */)\n\n    override fun completePrintRequest(request: PrintRequest) {\n        if (request.stderr) MyOutputStream.writeError(request.text)\n        else MyOutputStream.write(request.text)\n    }\n\n    override fun readLineOrNull(hideInput: Boolean): String? {\n        return if (hideInput) MyInputStream.readPassword()\n        else MyInputStream.readLine()\n    }\n}\n\nclass CustomCLI : NoOpCliktCommand() {\n    init { context { terminal = Terminal(terminalInterface = MyInterface ) } }\n}\n</code></pre> <p>Tip</p> <p>If you want to log the output, you can use Mordant\u2019s <code>TerminalRecorder</code>. That\u2019s how test is implemented!</p>"},{"location":"advanced/#command-line-argument-files-argfiles","title":"Command Line Argument Files (\u201c@argfiles\u201d)","text":"<p>Similar to <code>javac</code>, Clikt supports loading command line parameters from a file using the \u201c@argfile\u201d syntax. You can pass any file path to a command prefixed with <code>@</code>, and the file will be expanded into the command line parameters. This can be useful on operating systems like Windows that have command line length limits.</p> <p>If you create a file named <code>cliargs</code> with content like this:</p> <pre><code>--number 1\n--name='jane doe' --age=30\n./file.txt\n</code></pre> <p>You can call your command with the contents of the file like this:</p> <pre><code>$ ./tool @cliargs\n</code></pre> <p>Which is equivalent to calling it like this:</p> <pre><code>$ ./tool --number 1 --name='jane doe' --age=30 ./file.txt\n</code></pre> <p>You can use any file path after the <code>@</code>, and can specify multiple @argfiles:</p> <pre><code>$ ./tool @../config/args @C:\\\\Program\\ Files\\\\Tool\\\\argfile\n</code></pre> <p>If you have any options with names that start with <code>@</code>, you can still use <code>@argfiles</code>, but values on the command line that match an option will be parsed as that option, rather than an <code>@argfile</code>, so you\u2019ll have to give your files a different name.</p>"},{"location":"advanced/#preventing-argfile-expansion","title":"Preventing @argfile expansion","text":"<p>If you want to use a value starting with <code>@</code> as an argument without expanding it, you have three options:</p> <ol> <li>Pass it after a <code>--</code>, which disables expansion for everything that occurs after it.</li> <li>Escape it with <code>@@</code>. The first <code>@</code> will be removed and the rest used as the argument value. For example, <code>@@file</code> will parse as the string <code>@file</code></li> <li>Disable @argfile expansion entirely by setting <code>Context.readArgumentFile = null</code></li> </ol>"},{"location":"advanced/#file-format","title":"File format","text":"<ul> <li>Normal shell quoting and escaping rules apply. </li> <li>Line breaks are treated as word separators, and can be used where you would normally use a space   to separate parameters.</li> <li>Line breaks can occur within quotes, and will be included in the quoted value.</li> <li>@argfiles can contain other @argfile arguments, which will be expanded recursively.</li> <li>An unescaped <code>#</code> character outside of quotes is treated as a line comment: it and the rest of the   line are skipped. You can pass a literal <code>#</code> by escaping it with <code>\\#</code> or quoting it with <code>'#'</code>.</li> <li>If a <code>\\</code> occurs at the end of a line, the next line is trimmed of leading whitespace and the two   lines are concatenated.</li> </ul>"},{"location":"advanced/#managing-shared-resources","title":"Managing Shared Resources","text":"<p>You might need to open a resource like a file or a network connection in one command, and use it in its subcommands.</p> <p>The typical way to manage a resource is with the <code>use</code> function:</p> <pre><code>class MyCommand : CliktCommand() {\n    private val file by option().file().required()\n\n    override fun run() {\n        file.bufferedReader().use { reader -&gt;\n            // use the reader\n        }\n    }\n}\n</code></pre> <p>But if you need to share the resource with subcommands, the <code>use</code> function will exit and close the resource before the subcommand is called. Instead, use the context\u2019s registerCloseable function (for <code>kotlin.AutoCloseable</code>) or registerJvmCloseable function (for <code>java.lang.AutoCloseable</code>) to:</p> <pre><code>class MyCommand : CliktCommand() {\n    private val file by option().file().required()\n\n    override fun run() {\n        currentContext.obj = currentContext.registerJvmCloseable(file.bufferedReader())\n    }\n}\n</code></pre> <p>You can register as many closeables as you need, and they will all be closed when the command and its subcommands have finished running. If you need to manage a resource that isn\u2019t <code>AutoClosable</code>, you can use callOnClose.</p>"},{"location":"advanced/#custom-exit-status-codes","title":"Custom exit status codes","text":"<p>Clikt will normally exit your program with a status code of 0 for a normal execution, or 1 if there\u2019s an error. If you want to use a different value, you can <code>throw ProgramResult(statusCode)</code>. If you use <code>CliktCommand.main</code>, that exception will be caught and <code>exitProcess</code> will be called with the value of <code>statusCode</code>.</p> <p>You could also call <code>exitProcess</code> yourself, but the ProgramResult has a couple of advantages:</p> <ul> <li><code>ProgramResult</code> is easier to test. Exiting the process makes unit tests difficult to run.</li> <li><code>ProgramResult</code> works on all platforms. <code>exitProcess</code> is only available on the JVM.</li> </ul>"},{"location":"advanced/#custom-run-function-signature","title":"Custom run function signature","text":"<p>Clikt provides a few command base classes that have different run function signatures. CliktCommand has <code>fun run()</code>, while SuspendingCliktCommand has <code>suspend fun run()</code>. If you want a run function with a different signature, you can define your own base class the inherits from BaseCliktCommand and use the CommandLineParser methods to parse and run the command.</p> <p>For example, if you want a command that uses a Flow to emit multiple value for each run, you could implement it like this:</p> ExampleUsage <pre><code>abstract class FlowCliktCommand : BaseCliktCommand&lt;FlowCliktCommand&gt;() {\n    abstract fun run(): Flow&lt;String&gt;\n}\n\nclass MyFlowCommand : FlowCliktCommand() {\n    val opt by option().required()\n    val arg by argument().int()\n\n    override fun run(): Flow&lt;String&gt; = flow {\n        emit(opt)\n        emit(arg.toString())\n    }\n}\n\nclass MyFlowSubcommand : FlowCliktCommand() {\n    val arg by argument().multiple()\n\n    override fun run(): Flow&lt;String&gt; = flow {\n        arg.forEach { emit(it) }\n    }\n}\n\nfun FlowCliktCommand.parse(argv: Array&lt;String&gt;): Flow&lt;String&gt; {\n    val flows = mutableListOf&lt;Flow&lt;String&gt;&gt;()\n    CommandLineParser.parseAndRun(this, argv.asList()) { flows += it.run() }\n    return flow { flows.forEach { emitAll(it) } }\n}\n\nfun FlowCliktCommand.main(argv: Array&lt;String&gt;): Flow&lt;String&gt; {\n    return CommandLineParser.mainReturningValue(this) { parse(argv) }\n}\n\nsuspend fun main(args: Array&lt;String&gt;) {\n    val command = MyFlowCommand().subcommands(MyFlowSubcommand())\n    val resultFlow: Flow&lt;String&gt; = command.main(args)\n    resultFlow.collect {\n        command.echo(it)\n    }\n}\n</code></pre> <pre><code>$ ./command --opt=foo 11 my-flow-subcommand bar baz\nfoo\n11\nbar\nbaz\n</code></pre> <p>There are a number of steps here, so let\u2019s break it down:</p> <ol> <li>Define a base class <code>FlowCliktCommand</code> that inherits from BaseCliktCommand and has an abstract    <code>run</code> function that returns a <code>Flow</code>.</li> <li>Define your commands that inherit from <code>FlowCliktCommand</code> and implement your <code>run</code> function.</li> <li>Define an extension function <code>parse</code> that uses CommandLineParser.parseAndRun to parse the    command and run the <code>run</code> function.</li> <li>Define an extension function <code>main</code> that uses CommandLineParser.main to run the <code>parse</code>    function and handle any exceptions it might throw.</li> <li>In your <code>main</code> function, call <code>main</code> on your command, and collect the results of the <code>Flow</code>.</li> </ol> <p>If you want to customize the behavior even further, see the next section.</p>"},{"location":"advanced/#custom-run-behavior","title":"Custom run behavior","text":"<p>If you want to customize how or when subcommands are run, you can do so by defining a custom base class like in the previous section, but instead of using <code>CommandLineParser.parseAndRun</code>, you can call your command\u2019s <code>run</code> functions manually.</p> <p>For example, if you want commands to return status codes, and you want to stop running commands as soon as one of them returns a non-zero status code, you could implement it like this:</p> ExampleUsage <pre><code>abstract class StatusCliktCommand : BaseCliktCommand&lt;StatusCliktCommand&gt;() {\n    abstract fun run(): Int\n}\n\nclass ParentCommand : StatusCliktCommand() {\n    override val allowMultipleSubcommands: Boolean = true\n    override fun run(): Int {\n        echo(\"Parent\")\n        return 0\n    }\n}\n\nclass SuccessCommand : StatusCliktCommand() {\n    override fun run(): Int {\n        echo(\"Success\")\n        return 0\n    }\n}\n\nclass FailureCommand : StatusCliktCommand() {\n    override fun run(): Int {\n        echo(\"Failure\")\n        return 1001\n    }\n}\n\nfun StatusCliktCommand.parse(argv: Array&lt;String&gt;): Int {\n    val parseResult = CommandLineParser.parse(this, argv.asList())\n    parseResult.invocation.flatten().use { invocations -&gt;\n        for (invocation in invocations) {\n            val status = invocation.command.run()\n            if (status != 0) {\n                return status\n            }\n        }\n    }\n    return 0\n}\n\nfun StatusCliktCommand.main(argv: Array&lt;String&gt;) {\n    val status = CommandLineParser.mainReturningValue(this) { parse(argv) }\n    exitProcess(status)\n}\n\nfun main(argv: Array&lt;String&gt;) {\n    ParentCommand().subcommands(SuccessCommand(), FailureCommand()).main(argv)\n}\n</code></pre> <pre><code>$ ./command success failure success\nParent\nSuccess\nFailure\n\n$ echo $?\n1001\n</code></pre> <p>The steps here are similar to the previous section, but instead of using CommandLineParser.parseAndRun, we use CommandLineParser.parse, then call <code>run</code> on each command invocation manually, and stop when one of them returns a non-zero status code.</p>"},{"location":"advanced/#core-module","title":"Core Module","text":"<p>Clikt normally uses Mordant for rendering output and interacting with the system, but there are some  cases where you might want to use Clikt without Mordant. For these cases, Clikt has a core module that doesn\u2019t have any dependencies.</p> <p>Replace your Clikt dependency with the core module:</p> <pre><code>dependencies {\n    implementation(\"com.github.ajalt.clikt:clikt-core:$cliktVersion\")\n}\n</code></pre> <p>The CliktCommand class is only available in the full module, so you\u2019ll need to use CoreCliktCommand (or CoreNoOpCliktCommand) instead. The <code>CoreCliktCommand</code> has the same API as <code>CliktCommand</code>, but it doesn\u2019t have any of these features built in:</p> <ul> <li>Text wrapping, formatting, markdown, or color support</li> <li>argument files</li> <li>environment variables</li> <li><code>main</code> exiting the process with a status code</li> <li>printing to stderr</li> <li>prompt options</li> <li>The test function</li> </ul> <p>Most of those features can be added by setting the appropriate properties on the command\u2019s context. Here\u2019s an example of setting all of them using Java APIs, but you only need to set the ones you\u2019ll use:</p> <pre><code>abstract class MyCoreCommand : CoreCliktCommand() {\n    init {\n        context {\n            readArgumentFile = {\n                try {\n                    Path(it).readText()\n                } catch (e: IOException) {\n                    throw FileNotFound(it)\n                }\n            }\n            readEnvvar = { System.getenv(it) }\n            exitProcess = { System.exit(it) }\n            echoMessage = { context, message, newline, err -&gt;\n                val writer = if (err) System.err else System.out\n                if (newline) {\n                    writer.println(message)\n                } else {\n                    writer.print(message)\n                }\n            }\n        }\n    }\n}\n</code></pre>"},{"location":"advanced/#multiplatform-support","title":"Multiplatform Support","text":"<p>Clikt supports the following platforms:</p>"},{"location":"advanced/#jvm","title":"JVM","text":"<p>There are some JVM-only extensions available such as file and path parameter types.</p>"},{"location":"advanced/#desktop-native-linux-windows-and-macos","title":"Desktop native (Linux, Windows, and macOS)","text":""},{"location":"advanced/#javascript-and-wasmjs","title":"JavaScript and WasmJS","text":"<p>All functionality is supported on Node.js.</p> <p>In the browser, the default terminal only outputs to the browser\u2019s developer console, which is probably not what you want. You can define your own TerminalInterface, or you can call parse instead of main and handle output yourself.</p>"},{"location":"advanced/#ios","title":"iOS","text":""},{"location":"advanced/#watchos-tvos-and-wasmwasi","title":"watchOS, tvOS and WasmWasi","text":"<p>These platforms are not supported by the markdown module, but all other functionality is available.</p>"},{"location":"arguments/","title":"Arguments","text":"<p>Arguments are declared and customized similarly to options, but are provided on the command line positionally instead of by name. Arguments are declared with <code>argument()</code>, and the order that they are declared defines the order that they must be provided on the command line.</p>"},{"location":"arguments/#basic-arguments","title":"Basic Arguments","text":"<p>By default, <code>argument</code> takes a single <code>String</code> value which is required to be provided on the command line.</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    val name by argument()\n    override fun run() {\n        echo(\"Hello $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello Foo\nHello Foo!\n</code></pre> <p>Arguments appear in the usage string, but listed in the help page unless you set their <code>help</code> value. It\u2019s usually clearer to document arguments in the command help.</p> ExampleHelp Output <pre><code>class Cp : CliktCommand(\n    help = \"Copy &lt;source&gt; to &lt;dest&gt;, or multiple &lt;source&gt;(s) to directory &lt;dest&gt;.\"\n) {\n    private val source by argument().file(mustExist = true).multiple()\n    private val dest by argument().file()\n    override fun run() {\n        // ...\n    }\n}\n</code></pre> <pre><code>Usage: cp [&lt;options&gt;] [&lt;source&gt;]... &lt;dest&gt;\n\n  Copy &lt;source&gt; to &lt;dest&gt;, or multiple &lt;source&gt;(s) to directory &lt;dest&gt;.\n\nOptions:\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"arguments/#variadic-arguments","title":"Variadic Arguments","text":"<p>Like options, arguments can take any fixed number of values, which you can change with functions like <code>pair</code> and <code>triple</code>. Unlike options, arguments can also take a variable (or unlimited) number of values. This is common with file path arguments, since they are frequently expanded with a glob pattern on the command line.</p> <p>Variadic arguments are declared with <code>multiple</code>. You can declare any number of arguments with fixed numbers of values, but only one variadic argument in a command.</p> ExampleUsage <pre><code>class Copy : CliktCommand() {\n    val source: List&lt;Path&gt; by argument().path(mustExist = true).multiple()\n    val dest: Path by argument().path(canBeFile = false)\n    override fun run() {\n        echo(\"Copying files $source to $dest\")\n    }\n}\n</code></pre> <pre><code>$ ./copy file.* out/\nCopying files [file.txt, file.md] to out/\n</code></pre> <p>You can also use <code>unique</code> to discard duplicates:</p> <pre><code>val source: Set&lt;Path&gt; by argument().path(mustExist = true).multiple().unique()\n</code></pre>"},{"location":"arguments/#option-like-arguments-using-","title":"Option-Like Arguments (Using <code>--</code>)","text":"<p>Clikt normally parses any value that starts with punctuation as an option, which allows users to intermix options and arguments. However, sometimes you need to pass a value that starts with punctuation to an argument. For example, you might have a file named <code>-file.txt</code> that you want to use as an argument.</p> <p>Clikt supports the POSIX convention of using <code>--</code> to force all following values to be treated as arguments. Any values before the <code>--</code> will be parsed normally.</p> ExampleUsage 1Usage 2 <pre><code>class Touch : CliktCommand() {\n    val verbose by option().flag()\n    val files by argument().multiple()\n    override fun run() {\n        if (verbose) echo(files.joinToString(\"\\n\"))\n    }\n}\n</code></pre> <pre><code>$ ./touch --foo.txt\nUsage: touch [&lt;options&gt;] [&lt;files&gt;]...\n\nError: no such option: \"--foo.txt\".\n</code></pre> <pre><code>$ ./touch --verbose -- --foo.txt bar.txt\n--foo.txt\nbar.txt\n</code></pre>"},{"location":"autocomplete/","title":"Shell Autocomplete","text":"<p>Clikt includes built-in support for generating autocomplete scripts for bash, zsh and fish shells.</p> Example <pre><code>$ ./repo &lt;TAB&gt;&lt;TAB&gt;\ncommit clone pull\n\n$ ./repo -&lt;TAB&gt;\n--config -h --help --repo-home --verbose\n\n$./repo --repo-home ./g&lt;TAB&gt;\n./git ./got ./good\n</code></pre>"},{"location":"autocomplete/#enabling-completion","title":"Enabling Completion","text":"<p>Clikt handles autocomplete by generating a shell script that defines the completion. You generate the script once each time your CLI changes, and load it each time your start your shell. </p>"},{"location":"autocomplete/#with-an-environment-variable","title":"With an environment variable","text":"<p>You can generate the completion script by invoking your program with a special environment variable.</p> <p>You can set the variable name manually with by overriding the <code>autoCompleteEnvvar</code> property in your command. By default, it\u2019s your command\u2019s name capitalized, with <code>-</code> replaced with <code>_</code>, and prefixed with another <code>_</code>. So if your command name is <code>my-command</code>, the variable would be <code>_MY_COMMAND_COMPLETE=bash</code>, <code>_MY_COMMAND_COMPLETE=zsh</code>, or <code>_MY_COMMAND_COMPLETE=fish</code>, depending on your current shell.</p> <p>For example to activate bash autocomplete for this command:</p> <pre><code>class MyProgram: CliktCommand() {\n    // ...\n}\n</code></pre> <p>You can generate the completion script and save it to a file like this:</p> <pre><code>$ _MY_PROGRAM_COMPLETE=bash ./my-program &gt; ~/my-program-completion.sh\n</code></pre>"},{"location":"autocomplete/#with-an-option","title":"With an option","text":"<p>If you\u2019d prefer not to use environment variables, you can add a special option to your command with the <code>completionOption</code> function. Invoking your program with this option will generate the completion script:</p> Example 1Example 2Usage <pre><code>class MyCommand: CliktCommand() {\n    init {\n        completionOption()\n    }\n    // ...\n}\n</code></pre> <pre><code>class MyCommand: CliktCommand() {\n    //..\n}\n\nfun main(args: Array&lt;String&gt;) = MyCommand().completionOption().main(args)\n</code></pre> <pre><code>$ ./my-command --generate-completion=bash &gt; ~/my-program-completion.sh\n</code></pre>"},{"location":"autocomplete/#with-a-subcommand","title":"With a subcommand","text":"<p>A third option is to add a subcommand that will generate the completion when invoked.</p> Example 1Example 2Usage <pre><code>class MyCommand: CliktCommand() {\n    init {\n        subcommands(CompletionCommand())\n    }\n    // ...\n}\n</code></pre> <pre><code>class MyCommand: CliktCommand() {\n    //..\n}\n\nfun main(args: Array&lt;String&gt;) = MyCommand().subcommands(CompletionCommand()).main(args)\n</code></pre> <pre><code>$ ./my-command generate-completion bash &gt; ~/my-program-completion.sh\n</code></pre>"},{"location":"autocomplete/#manually","title":"Manually","text":"<p>Finally, if none of the built-in methods work for you, you can generate the completion script yourself with the CompletionGenerator.</p> Example <pre><code>class MyCommand: CliktCommand() {\n    override fun run() {\n        echo(CompletionGenerator.generateCompletionForCommand(this, \"bash\"))\n    }\n}\n</code></pre>"},{"location":"autocomplete/#using-the-generated-script","title":"Using the generated script","text":"<p>Once you\u2019ve generated the completion script, source the file to activate completion:</p> <pre><code>$ source ~/my-program-completion.sh\n</code></pre> <p>You can add that source command to your startup script so that completion is always available. For example, with bash:</p> <pre><code>$ echo source ~/my-program-completion.sh &gt;&gt; ~/.bashrc\n</code></pre> <p>You\u2019ll need to regenerate the completion script any time your command structure changes.</p>"},{"location":"autocomplete/#supported-functionality","title":"Supported Functionality","text":""},{"location":"autocomplete/#bash-and-zsh","title":"Bash and Zsh","text":"<p>Currently subcommand, option, and command alias names can be completed, as well as values for options and arguments. <code>choice</code> parameters are completed with their possible values. Other parameter types are completed as file or directory names. <code>Context.allowInterspersedArgs</code> is supported.</p>"},{"location":"autocomplete/#fish","title":"Fish","text":"<p>Fish\u2019s completion mechanism is more limited that Bash\u2019s. Subcommands can be completed, options can be completed as long as they start with a <code>-</code>. Completion suggestions for positional arguments are the union of all positional arguments. Other advanced Clikt features are not supported. </p>"},{"location":"autocomplete/#customizing-completions","title":"Customizing Completions","text":"<p>There is built-in completion for values for <code>choice</code> parameters, and for parameters converted with <code>file</code> and <code>path</code>.</p> <p>You can add completion for other parameters with the <code>completionCandidates</code> parameter to <code>option()</code> and <code>argument()</code>. The value can be one of the following:</p> <ul> <li><code>None</code>: The default. The parameter\u2019s values will not be completed.</li> <li><code>Path</code>: Completions will be filesystem paths.</li> <li><code>Hostname</code>: Completions will be read from the system\u2019s hosts file.</li> <li><code>Username</code>: Completions will be taken from the system\u2019s users.</li> <li><code>Fixed</code>: Completions are given as a fixed set of strings.</li> <li><code>Custom</code>: Completions are generated from a custom script.</li> </ul>"},{"location":"autocomplete/#custom-completion-candidates","title":"<code>Custom</code> completion candidates","text":"<p>The <code>Custom</code> type takes a block that returns code to add to the script which generates completions for the given parameter.</p> <p>If you just want to call another script or binary that prints all possible completion words to stdout, you can use fromStdout.</p> <p>Both Bash and ZSH scripts use Bash\u2019s Programmable Completion system (ZSH via a comparability layer). The string returned from [generator] should be the body of a function that will be passed to <code>compgen -F</code>.</p> <p>Specifically, you should set the variable <code>COMPREPLY</code> to the completion(s) for the current word being typed. The word being typed can be retrieved from the <code>COMP_WORDS</code> array at index <code>COMP_CWORD</code>.</p> Example with fromStdoutExample with full script <pre><code>class Hello: CliktCommand() {\n    // This example uses `echo`, but you would use your own binary\n    // or script that prints the completions.\n    val name by option(completionCandidates =\n        CompletionCandidates.Custom.fromStdout(\"echo completion1 completion2\")\n    )\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>class Hello: CliktCommand() {\n    // This is identical to the previous example\n    val name by option(completionCandidates = CompletionCandidates.Custom {\n        \"\"\"\n        WORDS=${'$'}(echo completion1 completion2)\n        COMPREPLY=(${'$'}(compgen -W \"${'$'}WORDS\" -- \"${'$'}{COMP_WORDS[${'$'}COMP_CWORD]}\"))\n        \"\"\".trimIndent()\n    })\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre>"},{"location":"autocomplete/#limitations","title":"Limitations","text":"<p>Token Normalization is not supported.</p> <p>If you have arguments that occur after a <code>multiple</code> argument, those arguments won\u2019t be autocompleted. Partial command lines are ambiguous in those situations, and Clikt assumes that you\u2019re trying to complete the <code>multiple</code> argument rather than the later ones.</p> <p>Bash must be at least version 3, or Zsh must be at least version 4.1.</p>"},{"location":"changelog/","title":"Change Log","text":""},{"location":"changelog/#500","title":"5.0.0","text":""},{"location":"changelog/#added","title":"Added","text":"<ul> <li>Publish <code>iosArm64</code> and <code>iosX64</code> targets.</li> <li>Added <code>NoSuchArgument</code> exception that is thrown when too many arguments were given on the command line. Previously, a less specific <code>UsageError</code> was thrown instead.</li> <li>Added <code>CommandLineParser.tokenize</code> that splits a string into argv tokens.</li> <li>Added <code>CommandLineParser</code> that provides functions for parsing and finalizing commands manually for more control.</li> <li>Added <code>Context.invokedSubcommands</code> that contains all subcommands of the current command that are going to be invoked when <code>allowMultipleSubcommands</code> is <code>true</code>.</li> <li>Added <code>SuspendingCliktCommand</code> that has a <code>suspend fun run</code> method, allowing you to use coroutines in your commands.</li> <li>Added <code>ChainedCliktCommand</code> that allows you to return a value from your <code>run</code> method and pass it to the next command in the chain.</li> <li>Added <code>Context.data</code> as an alternative to <code>obj</code> that allows you to store more than one object in the context.</li> <li>Added <code>Context.echoer</code> to customize how <code>echo</code> messages are printed.</li> <li>Added <code>CompletionGenerator</code> to manually generate completions for a command.</li> <li>Added <code>Context.exitProcess</code> which you can use to prevent the process from exiting during tests.</li> <li>Added core module that supports watchOS, tvOS, and wasmWasi targets and has no dependencies.</li> <li>Added more options to <code>CliktCommand.test</code> to control the terminal interactivity. (#517)</li> <li>Added <code>associate{}</code>, <code>associateBy{}</code>, and <code>associateWith{}</code> transforms for options that allow you to convert the keys and values of the map.  (#529)</li> <li>Added support for aliasing options to other options. (#535)</li> <li>Added <code>limit</code> and <code>ignoreCase</code> parameters to <code>option().split()</code>. (#541)</li> <li>Support calling <code>--help</code> on subcommands when parents have required parameters.</li> </ul>"},{"location":"changelog/#changed","title":"Changed","text":"<ul> <li>In a subcommand with and an <code>argument()</code> with <code>multiple()</code> or <code>optional()</code>, the behavior is now the same regardless of the value of <code>allowMultipleSubcommands</code>: if a token matches a subcommand name, it\u2019s now treated as a subcommand rather than a positional argument.</li> <li>Due to changes to the internal parsing algorithm, the exact details of error messages when multiple usage errors occur have changed in some cases.</li> <li>Breaking Change: Moved the following parameters from <code>CliktCommand</code>\u2019s constructor; override the corresponding properties instead:</li> </ul> removed parameter replacement property <code>help</code> <code>fun help</code> <code>epilog</code> <code>fun helpEpilog</code> <code>invokeWithoutSubcommand</code> <code>val invokeWithoutSubcommand</code> <code>printHelpOnEmptyArgs</code> <code>val printHelpOnEmptyArgs</code> <code>helpTags</code> <code>val helpTags</code> <code>autoCompleteEnvvar</code> <code>val autoCompleteEnvvar</code> <code>allowMultipleSubcommands</code> <code>val allowMultipleSubcommands</code> <code>treatUnknownOptionsAsArgs</code> <code>val treatUnknownOptionsAsArgs</code> <code>hidden</code> <code>val hiddenFromHelp</code> - The following methods on <code>CliktCommand</code> have been renamed: <code>commandHelp</code> -&gt; <code>help</code>, <code>commandHelpEpilog</code> -&gt; <code>epilog</code>. The old names are deprecated. - Breaking Change: <code>CliktCommand.main</code> and <code>CliktCommand.parse</code> are now extension functions rather than methods. - Breaking Change: <code>Context.obj</code> and <code>Context.terminal</code>, and <code>OptionTransformContext.terminal</code> are now extension functions rather than properties. - Breaking Change: The <code>RenderedSection</code> and <code>DefinitionRow</code> classes have moved to <code>AbstractHelpFormatter</code>. - Markdown support in the help formatter is no longer included by default. To enable it, include the <code>:clikt-markdown</code> dependency and call <code>yourCommand.installMordantMarkdown()</code> before parsing. - Updated Kotlin to 2.0.0"},{"location":"changelog/#fixed","title":"Fixed","text":"<ul> <li>Fixed excess arguments not being reported when <code>allowMultipleSubcommands=true</code> and a subcommand has excess arguments followed by another subcommand.</li> <li>Commands with <code>printHelpOnEmptyArgs=true</code> will no longer print help if an option has a value from an environment variable or value source.  (#382)</li> </ul>"},{"location":"changelog/#deprecated","title":"Deprecated","text":"<ul> <li>Deprecated <code>Context.originalArgv</code>. It will now always return an empty list. If your commands need an argv, you can pass it to them before you run them, or set in on the new <code>Context.data</code> map.</li> <li>Deprecated <code>Context.expandArgumentFiles</code>. Use <code>Context.argumentFileReader</code> instead.</li> <li>Renamed the following <code>Context</code> fields to be more consistent. The old names are deprecated.</li> </ul> old name new name <code>Context.envvarReader</code> <code>Context.readEnvvar</code> <code>Context.correctionSuggestor</code> <code>Context.suggestTypoCorrection</code> <code>Context.argumentFileReader</code> <code>Context.readArgumentFile</code> <code>Context.tokenTransformer</code> <code>Context.transformToken</code>"},{"location":"changelog/#removed","title":"Removed","text":"<ul> <li>Removed previously deprecated experimental annotations.</li> <li>Removed <code>MordantHelpFormatter.graphemeLength</code></li> <li>Removed <code>TermUi</code></li> </ul>"},{"location":"changelog/#440","title":"4.4.0","text":""},{"location":"changelog/#added_1","title":"Added","text":"<ul> <li>Publish <code>linuxArm64</code> and <code>wasmJs</code> targets.</li> </ul>"},{"location":"changelog/#430","title":"4.3.0","text":""},{"location":"changelog/#added_2","title":"Added","text":"<ul> <li>Added <code>limit</code> parameter to <code>option().counted()</code> to limit the number of times the option can be used. You can either clamp the value to the limit, or throw an error if the limit is exceeded. (#483)</li> <li>Added <code>Context.registerClosable</code> and <code>Context.callOnClose</code> to allow you to register cleanup actions that will be called when the command exits. (#395)</li> </ul>"},{"location":"changelog/#fixed_1","title":"Fixed","text":"<ul> <li>Fixed <code>unrecognized modifier 'i'</code> that happened on tab-completion when using sub command aliases. Thanks to @hick209 for the contribution. (#500)</li> <li>Make sure auto complete script works on zsh, fixing the error <code>complete:13: command not found: compdef</code>. Thanks to @hick209 for the contribution. (#499)</li> </ul>"},{"location":"changelog/#422","title":"4.2.2","text":""},{"location":"changelog/#changed_1","title":"Changed","text":"<ul> <li>Options and arguments can now reference option groups in their <code>defaultLazy</code> and other finalization blocks. They can also freely reference each other, including though chains of references. (#473)</li> <li>Updated Kotlin to 1.9.21 (#472)</li> </ul>"},{"location":"changelog/#421","title":"4.2.1","text":""},{"location":"changelog/#added_3","title":"Added","text":"<ul> <li>Added <code>toString</code> implementations to options and arguments. (#434)</li> <li>Added <code>CliktCommand.test</code> overload that takes a vararg of <code>String</code>s as the command line arguments. Thanks to @sschuberth for the contribution (#451)</li> </ul>"},{"location":"changelog/#fixed_2","title":"Fixed","text":"<ul> <li>Update Mordant dependency to fix crashes on native targets and GraalVM (#447)</li> </ul>"},{"location":"changelog/#420","title":"4.2.0","text":""},{"location":"changelog/#added_4","title":"Added","text":"<ul> <li>Added <code>requireConfirmation</code> parameter to <code>option().prompt()</code> (#426)</li> <li>Added <code>CliktCommand.terminal</code> extension for accessing the terminal from a command.</li> <li>Added <code>includeSystemEnvvars</code>, <code>ansiLevel</code>, <code>width</code>, and <code>height</code> parameters to all <code>CliktCommand.test</code> overloads.</li> </ul>"},{"location":"changelog/#deprecated_1","title":"Deprecated","text":"<ul> <li>Deprecated <code>CliktCommand.prompt</code>, use <code>CliktCommand.terminal.prompt</code> or <code>Prompt</code> instead.</li> <li>Deprecated <code>CliktCommand.confirm</code>, use <code>YesNoPrompt</code> instead.</li> </ul>"},{"location":"changelog/#fixed_3","title":"Fixed","text":"<ul> <li>Fixed incorrect error message when a <code>defaultLazy</code> option referenced a <code>required</code> option. (#430)</li> </ul>"},{"location":"changelog/#410","title":"4.1.0","text":""},{"location":"changelog/#added_5","title":"Added","text":"<ul> <li>Added <code>MordantHelpFormatter.renderAttachedOptionValue</code> that you can override to change how option values are shown, e.g. if you want option to show as <code>--option &lt;value&gt;</code> instead of <code>--option=&lt;value&gt;</code>. (#416)</li> <li>Added <code>option().optionalValueLazy{}</code>, which work like <code>optionalValue()</code> but the default value is computed lazily. (#381)</li> </ul>"},{"location":"changelog/#changed_2","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.9.0</li> <li><code>PrintMessage</code>, <code>PrintHelpMessage</code> and <code>PrintCompletionMessage</code> now default to exiting with a status code 0, which is the behavior they had in 3.x. (#419)</li> </ul>"},{"location":"changelog/#400","title":"4.0.0","text":""},{"location":"changelog/#added_6","title":"Added","text":"<ul> <li>Added <code>Context.errorEncountered</code> which is true if parsing has continued after an error was encountered.</li> <li><code>option().help{\"\"}</code> and <code>argument().help{\"\"}</code> extensions that set the parameter\u2019s help text lazily, with access to the current context so that you can add colors.</li> </ul>"},{"location":"changelog/#changed_3","title":"Changed","text":"<ul> <li><code>Option.optionHelp</code> and <code>Argument.argumentHelp</code>, <code>CliktCommand.commandHelp</code>, and <code>CliktCommand.commandHelpEpilog</code> are now methods that take the context as an argument, and the <code>help</code> parameter to <code>copy</code> is now a <code>helpGetter</code> lambda. <code>CliktCommand.shortHelp</code> now takes the context as an argument.</li> <li>The <code>message</code> method on <code>TransformContext</code> interfaces is now an extension.</li> </ul>"},{"location":"changelog/#deprecated_2","title":"Deprecated","text":"<ul> <li>Deprecated <code>CliktCommand.commandHelp</code> and <code>commandHelpEpilog</code> properties in favor of the methods with the same name.</li> </ul>"},{"location":"changelog/#400-rc","title":"4.0.0-RC","text":""},{"location":"changelog/#added_7","title":"Added","text":"<ul> <li>You can now use markdown in your help strings, including tables and lists. Clikt uses the Mordant library for rendering.</li> <li>Help output and error messages now include colors by default. You can disable this or customize the styling by configuring the <code>context.terminal</code></li> <li>Added <code>Option.varargValues()</code> to create an option that accepts a variable number of values</li> <li>Added <code>Option.optionalValue()</code> to create an option whose value is optional.</li> <li>Added <code>obj</code> setter to context builder as an alternative to <code>currentContext.obj</code></li> <li>Added <code>boolean()</code> parameter type conversions.</li> <li>Added <code>uint()</code> and <code>ulong()</code> parameter type conversions.</li> <li>Added <code>nullableFlag()</code> parameter transformation.</li> <li>Added <code>CliktCommand.test</code> extension for testing your commands and their output</li> <li>Clikt will now report multiple errors if they occur via the new <code>MultiUsageError</code> exception, rather than just reporting the first error. (#367)</li> <li>Added <code>CliktCommand.allHelpParams()</code>, which can be overridden to change which parameters are displayed in help output</li> <li>Added <code>Context.argumentFileReader</code> which allows custom loading of argument files</li> <li>Added <code>Context.allowGroupedShortOptions</code> which can disable parsing <code>-abc</code> as <code>-a -b -c</code></li> <li>Options named <code>-?</code> or <code>/?</code> are now supported</li> <li>Added <code>option(eager=true)</code> to create an eager option that takes values</li> <li>Added <code>option(acceptsUnattachedValue=false)</code> to force the option to only accept values like <code>--option=1</code> and not <code>--option 1</code></li> <li>Added <code>CliktCommand.test()</code> that captures the output of a command and does not exit the process.</li> </ul>"},{"location":"changelog/#removed_1","title":"Removed","text":"<ul> <li>Removed <code>CliktConsole</code>. Mordant is now used for all input and output. If you were defining a custom console, instead define a mordant <code>TerminalInterface</code> and set it on your context\u2019s <code>Terminal</code>.</li> <li>Removed <code>TermUi.echo</code>, <code>TermUi.prompt</code>, and <code>TermUi.confirm</code>. Use the equivalent methods on your <code>CliktCommand</code>, or use mordant\u2019s prompts directly.</li> <li>Removed legacy JS publications. Now only the JS/IR artifacts are published.</li> <li>Removed <code>CliktHelpFormatter</code>. Use <code>MordantHelpFormatter</code> instead.</li> <li>Removed <code>FlagOption</code> and <code>EagerOption</code> classes. All options are now implemented as transformations on <code>OptionWithValues</code>. <code>FlagOption</code> is now <code>OptionWithValues&lt;Boolean, Boolean, Boolean&gt;</code>.</li> </ul>"},{"location":"changelog/#changed_4","title":"Changed","text":"<ul> <li><code>prompt</code> and <code>confirm</code> are now implemented with mordant\u2019s prompt functionality, and the method parameters have changed to match mordant\u2019s</li> <li>When using <code>treatUnknownOptionsAsArgs</code>, grouped short options like <code>-abc</code> will be treated as an argument rather than reporting an error as long as they don\u2019t match any short options in the command. (#340)</li> <li>Clikt no longer automatically calls <code>trimIndent</code> on strings passed to <code>help</code>. Call <code>trimIndent</code> or <code>trimMargin</code> yourself if necessary.</li> <li><code>Context.Builder.helpOptionNames</code> now accepts any iterable rather than just a set.</li> <li><code>CliktCommand.echo</code> and <code>prompt</code> are now public. (#407)</li> <li>Internally, all options are implemented transformations on <code>OptionWithValues</code>, rather than using separate classes for each option type. </li> <li>Some Localization strings have changed, removed <code>Localization.aborted()</code>, added <code>Localization.argumentsMetavar()</code></li> <li><code>Context.Builder.helpFormatter</code> is now a lambda that takes the current context as an argument</li> <li>Exceptions have been reworked so that all exceptions thrown by Clikt are subclasses of <code>CliktError</code>.</li> <li><code>CliktError</code> now includes <code>statusCode</code> and <code>printError</code> properties.</li> <li>The constructor of <code>UsageError</code> and its subclasses no longer takes a <code>context</code> parameter. The context is now inferred automatically.</li> <li><code>UsageError.formatUsage</code> now takes the localization and formatter as arguments</li> </ul>"},{"location":"changelog/#fixed_4","title":"Fixed","text":"<ul> <li>When parsing a command line with more than one error, Clikt will now always report the error that occurs earliest if it can\u2019t report them all (#361)</li> <li>When <code>treatUnknownOptionsAsArgs</code> is true, grouped unknown short options will now be treated as arguments rather than reporting an error.</li> </ul>"},{"location":"changelog/#354","title":"3.5.4","text":""},{"location":"changelog/#fixed_5","title":"Fixed","text":"<ul> <li>Revert jvm jars to target Java 8</li> </ul>"},{"location":"changelog/#353","title":"3.5.3","text":""},{"location":"changelog/#changed_5","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.8.22</li> </ul>"},{"location":"changelog/#fixed_6","title":"Fixed","text":"<ul> <li>Context is now set properly on NoSuchOption exceptions when thrown from subcommands. (#399)</li> <li>When <code>treatUnknownOptionsAsArgs</code> is true, grouped unknown short options will now be treated as arguments rather than reporting an error.</li> </ul>"},{"location":"changelog/#352","title":"3.5.2","text":""},{"location":"changelog/#changed_6","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.8.10</li> </ul>"},{"location":"changelog/#fixed_7","title":"Fixed","text":"<ul> <li>Fix <code>CliktCommand.prompt</code> on NodeJS targets that would hang due to KT-55817 (#387)</li> </ul>"},{"location":"changelog/#351","title":"3.5.1","text":""},{"location":"changelog/#changed_7","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.7.20</li> </ul>"},{"location":"changelog/#fixed_8","title":"Fixed","text":"<ul> <li>Support unicode in environment variable values on Native Windows. (#362)</li> <li>Support environment variables for options in a mutually exclusive options group. (#384)</li> </ul>"},{"location":"changelog/#350","title":"3.5.0","text":""},{"location":"changelog/#added_8","title":"Added","text":"<ul> <li>Added <code>hidden</code> parameter to <code>CliktCommand</code>, which will prevent the command from being displayed as a subcommand in help output  (#353)</li> <li>Publish artifacts for the <code>macosArm64</code> target. Note that this target is not tested on CI. (#352)</li> </ul>"},{"location":"changelog/#changed_8","title":"Changed","text":"<ul> <li>Default values for arguments will now be included in help output when <code>showDefaultValues=true</code> is set on your help formatter (#357)</li> </ul>"},{"location":"changelog/#fixed_9","title":"Fixed","text":"<ul> <li>Fix flags and other options with defaults not being usable in <code>mutuallyExclusiveOptions</code> (#349)</li> <li>Fix <code>CompletionCommand</code> generating completion for itself (#355)</li> </ul>"},{"location":"changelog/#342","title":"3.4.2","text":""},{"location":"changelog/#deprecated_3","title":"Deprecated","text":"<ul> <li><code>TermUi.echo</code>, <code>TermUi.prompt</code>, and <code>TermUi.confirm</code>. Use the equivalent methods on <code>CliktCommand</code> instead. (#344)</li> </ul>"},{"location":"changelog/#341","title":"3.4.1","text":""},{"location":"changelog/#added_9","title":"Added","text":"<ul> <li>Added <code>obj</code> setter to context builder as an alternative to <code>currentContext.obj</code></li> <li>Added <code>option().boolean()</code> and <code>argument().boolean()</code></li> <li><code>uint()</code> and <code>ulong()</code> parameter type conversions.</li> <li><code>CliktCommand.test</code> extension for testing your commands and their output</li> </ul>"},{"location":"changelog/#changed_9","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.6.20</li> </ul>"},{"location":"changelog/#340","title":"3.4.0","text":""},{"location":"changelog/#changed_10","title":"Changed","text":"<ul> <li><code>unique()</code> now works with any option with a list type, not just <code>multiple()</code> options (#332)</li> <li>Updated Kotlin to 1.6.10</li> </ul>"},{"location":"changelog/#fixed_10","title":"Fixed","text":"<ul> <li>Fixed co-occurring option groups returning null when all options in the group are defined in environment variables (#330)</li> </ul>"},{"location":"changelog/#330","title":"3.3.0","text":""},{"location":"changelog/#added_10","title":"Added","text":"<ul> <li>Added <code>default</code> parameter to <code>argument().multiple()</code> (#305)</li> <li><code>Context.originalArgv</code> that allows you to read the command line arguments from within a command\u2019s <code>run</code> (#290)</li> <li><code>context { envarReader = {...} }</code> to set a custom function to read from environment variables (#299)</li> </ul>"},{"location":"changelog/#changed_11","title":"Changed","text":"<ul> <li><code>defaultLazy</code> values can now reference other parameters, as long the referenced parameters do not also reference other parameters</li> <li>You can now call <code>CliktCommand.context</code> multiple times on the same command, and all builder blocks will be applied </li> <li>Validate values entered to a <code>prompt</code> option, and show another prompt if the validation fails (#288)</li> <li>Updated kotlin to 1.5.31</li> </ul>"},{"location":"changelog/#fixed_11","title":"Fixed","text":"<ul> <li>Report error when excess arguments are given to a command with <code>allowMultipleSubcommands=true</code> (#303)</li> </ul>"},{"location":"changelog/#320","title":"3.2.0","text":""},{"location":"changelog/#added_11","title":"Added","text":"<ul> <li><code>InputStream.isCliktParameterDefaultStdin</code> and <code>OutputStream.isCliktParameterDefaultStdout</code> to check if the streams returned from <code>inputStream</code>/<code>outputStream</code> options are proxying stdin/stdout (#272)</li> </ul>"},{"location":"changelog/#changed_12","title":"Changed","text":"<ul> <li>Make parameters of <code>mutuallyExclusiveOptions</code> covariant to allow validation without explicit type annotations. (#265)</li> <li>Updated kotlin to 1.5.0</li> </ul>"},{"location":"changelog/#fixed_12","title":"Fixed","text":"<ul> <li>Reading from an option or argument property on a command that hasn\u2019t been invoked will now always throw an <code>IllegalStateException</code></li> </ul>"},{"location":"changelog/#310","title":"3.1.0","text":""},{"location":"changelog/#added_12","title":"Added","text":"<ul> <li>Added <code>required()</code> and <code>defaultLazy()</code> for nullable flag options like <code>switch()</code>. (#240)</li> <li>Added support for generating autocomplete scripts for Fish shells (#189)</li> <li>Added <code>CompletionCommand</code> and <code>CliktCommand.completionOption()</code> that will print an autocomplete script when invoked, as an alternative to using environment variables.</li> </ul>"},{"location":"changelog/#changed_13","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.4.21</li> <li><code>@argfiles</code> now allow line breaks in quoted values, which are included in the value verbatim. You can now end lines with <code>\\</code> to concatenate them with the following line. (#248)</li> </ul>"},{"location":"changelog/#301","title":"3.0.1","text":""},{"location":"changelog/#deprecated_4","title":"Deprecated","text":"<ul> <li>Deprecated calling <code>echo</code> with <code>err</code> or <code>lineSeparator</code> but no <code>message</code>. </li> </ul>"},{"location":"changelog/#300","title":"3.0.0","text":""},{"location":"changelog/#added_13","title":"Added","text":"<ul> <li>Clikt\u2019s JS target now supports both NodeJS and Browsers. (#198)</li> <li>Default values for switch options are now shown in the help. Help text can be customized using the <code>defaultForHelp</code> argument, similar to normal options. (#205)</li> <li>Added <code>FlagOption.convert</code> (#208)</li> <li>Added ability to use unicode NEL character (<code>\\u0085</code>) to manually break lines in help output (#214)</li> <li>Added <code>help(\"\")</code> extension to options and arguments as an alternative to passing the help as an argument (#207)</li> <li>Added <code>valueSourceKey</code> parameter to <code>option</code></li> <li>Added <code>check()</code> extensions to options and arguments as an alternative to <code>validate()</code></li> <li>Added <code>prompt</code> and <code>confirm</code> functions to <code>CliktCommand</code> that call the <code>TermUi</code> equivalents with the current console.</li> <li>Added <code>echo()</code> overload with no parameters to CliktCommand that prints a newline by itself.</li> <li>Added localization support. You can set an implementation of the <code>Localization</code> interface on your context with your translations. (#227)</li> </ul>"},{"location":"changelog/#fixed_13","title":"Fixed","text":"<ul> <li>Hidden options will no longer be suggested as possible typo corrections. (#202)</li> <li>Options and Arguments with <code>multiple(required=true)</code> will now show as required in help output. (#212)</li> <li>Multiple short lines in a help text paragraph no longer appear dedented (#215)</li> </ul>"},{"location":"changelog/#changed_14","title":"Changed","text":"<ul> <li>Updated Kotlin to 1.4.0</li> <li><code>Argument.help</code> and <code>Option.help</code> properties have been renamed to <code>argumentHelp</code> and <code>optionHelp</code>, respectively. The <code>help</code> parameter names to <code>option()</code> and <code>argument()</code> are unchanged.</li> <li><code>commandHelp</code> and <code>commandHelpEpilog</code> properties on <code>CliktCommand</code> are now <code>open</code>, so you can choose to override them instead of passing <code>help</code> and <code>epilog</code> to the constructor.</li> <li>Replaced <code>MapValueSource.defaultKey</code> with <code>ValueSource.getKey()</code>, which is more customizable.</li> <li><code>Option.metavar</code>, <code>Option.parameterHelp</code>, <code>OptionGroup.parameterHelp</code> and <code>Argument.parameterHelp</code> properties are now functions.</li> <li>Changed constructor parameters of <code>CliktHelpFormatter</code>. Added <code>localization</code> and removed <code>usageTitle</code>, <code>optionsTitle</code>, <code>argumentsTitle</code>, <code>commandsTitle</code>, <code>optionsMetavar</code>, and <code>commandMetavar</code>. Those strings are now defined on equivalently named functions on <code>Localization</code>.</li> </ul>"},{"location":"changelog/#removed_2","title":"Removed","text":"<ul> <li>Removed <code>envvarSplit</code> parameter from <code>option()</code> and <code>convert()</code>. Option values from environment variables are no longer split automatically. (#177)</li> <li>Removed public constructors from the following classes: <code>ProcessedArgument</code>, <code>OptionWithValues</code>, <code>FlagOption</code>, <code>CoOccurringOptionGroup</code>, <code>ChoiceGroup</code>, <code>MutuallyExclusiveOptions</code>.</li> <li><code>MissingParameter</code> exception replaced with <code>MissingOption</code> and <code>MissingArgument</code></li> <li>Removed <code>Context.helpOptionMessage</code>. Override <code>Localization.helpOptionMessage</code> and set it on your context instead.</li> </ul>"},{"location":"changelog/#deprecated_5","title":"Deprecated","text":"<ul> <li><code>@ExperimentalCompletionCandidates</code> and <code>@ExperimentalValueSourceApi</code> annotations. These APIs no longer require an opt-in.</li> </ul>"},{"location":"changelog/#280","title":"2.8.0","text":""},{"location":"changelog/#added_14","title":"Added","text":"<ul> <li>Added <code>error</code> parameter to <code>PrintMessage</code> and <code>PrintHelpMessage</code>. When <code>true</code>, <code>CliktCommand.main</code> will exit with status code 1. (#187)</li> </ul>"},{"location":"changelog/#changed_15","title":"Changed","text":"<ul> <li>When <code>printHelpOnEmptyArgs</code> is <code>true</code> and no arguments are present, or when <code>invokeWithoutSubcommand</code> is <code>false</code> and no subcommand is present, <code>CliktCommand.main</code> will now exit with status code 1 rather than 0. </li> <li><code>restrictTo</code> now works with any <code>Comparable</code> value, not just <code>Number</code>.</li> <li><code>CliktCommand.main</code> now accepts <code>Array&lt;out String&gt;</code>, not just <code>Array&lt;String&gt;</code>. (#196)</li> </ul>"},{"location":"changelog/#fixed_14","title":"Fixed","text":"<ul> <li>Fixed option values being reset when calling multiple subcommands with <code>allowMultipleSubcommands=true</code> (#190)</li> </ul>"},{"location":"changelog/#271","title":"2.7.1","text":""},{"location":"changelog/#fixed_15","title":"Fixed","text":"<ul> <li>Fixed NPE thrown in some cases when using <code>defaultByName</code> (#179)</li> </ul>"},{"location":"changelog/#270","title":"2.7.0","text":""},{"location":"changelog/#added_15","title":"Added","text":"<ul> <li>Ability to use custom program exit status codes via <code>ProgramResult</code>.</li> <li><code>inputStream</code> and <code>outputStream</code> conversions for options and arguments. (#157 and #159)</li> <li><code>splitPair</code>, <code>toMap</code>, and <code>associate</code> extensions on <code>option</code>. (#166)</li> <li><code>treatUnknownOptionsAsArgs</code> parameter to <code>CliktCommand</code>. (#152)</li> <li><code>defaultByName</code> function for <code>groupChoice</code> and <code>groupSwitch</code> options. (#171)</li> </ul>"},{"location":"changelog/#changed_16","title":"Changed","text":"<ul> <li>Update Kotlin to 1.3.71</li> <li>Improved command name inference. Now, a class like <code>MyAppCommand</code> will infer its <code>commandName</code> as <code>my-app</code> rather than <code>myappcommand</code>. You can still specify the name manually as before. (#168)</li> </ul>"},{"location":"changelog/#fixed_16","title":"Fixed","text":"<ul> <li>Correctly parse short options with attached values that contain <code>=</code></li> </ul>"},{"location":"changelog/#260","title":"2.6.0","text":""},{"location":"changelog/#added_16","title":"Added","text":"<ul> <li><code>registeredSubcommands</code>, <code>registeredOptions</code>, <code>registeredArguments</code>, and <code>registeredParameterGroups</code> methods on <code>CliktCommand</code>.</li> <li>Ability to read default option values from configuration files and other sources. Support for Java property files is built in on JVM, see the <code>json</code> sample for an example of reading from other formats.</li> <li><code>allowMultipleSubcommands</code> parameter to <code>CliktCommand</code> that allows you to pass multiple subcommands in the same call. (docs)</li> <li>Errors from typos in subcommand names will now include suggested corrections. Corrections for options and subcommands are now based on a Jaro-Winkler similarity metric, and can be customized with <code>Context.correctionSuggestor</code></li> </ul>"},{"location":"changelog/#changed_17","title":"Changed","text":"<ul> <li>Update Kotlin to 1.3.70</li> <li><code>convert</code> can be called more than once on the same option or argument, including after calls to conversion functions like <code>int</code> and <code>file</code>.</li> <li><code>CliktCommand.toString</code> now includes the class name</li> <li>Reverted automatic <code>~</code> expansion in <code>file()</code> and <code>path()</code> introduced in 2.5.0. If you need this behavior, you can implement it with code like <code>convert { /* expand tidle */ }.file()</code> </li> </ul>"},{"location":"changelog/#deprecated_6","title":"Deprecated","text":"<ul> <li><code>wrapValue</code> is now deprecated, since <code>convert</code> can be used in its place instead.</li> </ul>"},{"location":"changelog/#250","title":"2.5.0","text":""},{"location":"changelog/#added_17","title":"Added","text":"<ul> <li>Clikt is now available as a Kotlin Multiplatform Project, supporting JVM, NodeJS, and native Windows, Linux, and macOS.</li> <li><code>eagerOption {}</code> function to more easily register eager options.</li> <li>Eager options can now be added to option groups in help out by passing a value for <code>groupName</code> when creating them. </li> <li><code>canBeSymlink</code> parameter to <code>file()</code> and <code>path()</code> conversions that can be used to disallow symlinks</li> <li><code>CliktCommand.eagerOption</code> to simplify creating custom eager options</li> </ul>"},{"location":"changelog/#changed_18","title":"Changed","text":"<ul> <li>The parameter names of <code>file()</code> and <code>path()</code> conversions have changed. The existing names are deprecated, and can be converted to the new usages with an IntelliJ inspection. Note that if you are calling these functions with unnamed arguments (e.g. <code>file(true, false)</code>), you\u2019ll need to add argument names in order to remove the deprecation warning.</li> </ul>"},{"location":"changelog/#deprecated_7","title":"Deprecated","text":"<ul> <li>The <code>CliktCommand.context</code> property has been deprecated in favor of the new name, <code>currentContext</code>, to avoid confusion with the <code>CliktCommand.context{}</code> method.</li> <li><code>NoRunCliktCommand</code> was renamed to <code>NoOpCliktCommand</code>. The existing class is deprecated. (#130)</li> </ul>"},{"location":"changelog/#fixed_17","title":"Fixed","text":"<ul> <li><code>file()</code> and <code>path()</code> conversions will now properly expand leading <code>~</code> in paths to the home directory for <code>mustExist</code>, <code>canBeFile</code>, and <code>canBeDir</code> checks. The property value is unchanged, and can still begin with a <code>~</code>. (#131)</li> </ul>"},{"location":"changelog/#240","title":"2.4.0","text":""},{"location":"changelog/#added_18","title":"Added","text":"<ul> <li><code>CompletionCandidates.Fixed</code> now has a secondary convenience constructor that take a <code>vararg</code> of <code>String</code>s</li> <li><code>CompletionCadidates.Custom</code>, which allows you to call other binaries or write a script to generate completions. This class is currently experimental. (#79)</li> <li><code>Option.wrapValue</code> and <code>Argument.wrapValue</code> to make it easier to reuse existing conversion functions.</li> <li><code>ignoreCase</code> parameter to <code>choice()</code> and <code>enum()</code> conversion functions.</li> </ul>"},{"location":"changelog/#changed_19","title":"Changed","text":"<ul> <li><code>option()</code> and <code>argument()</code> now take optional <code>completionCandidates</code> parameters to override how completion is generated. The constructor and <code>copy</code> functions of <code>OptionsWithValues</code> and <code>ProcessedArgument</code> have changed to support default values.</li> <li>The overloads of <code>findObject</code> (1 2) that take a default value have been renamed <code>findOrSetObject</code>. The existing names are marked with <code>@Deprecated</code>, and IntelliJ can convert your call sites automatically. (#110)</li> <li><code>enum()</code> parameters now accept case-insensitive values by default. You change this behavior by passing <code>ignoreCase = false</code> to <code>enum()</code> (#115)</li> </ul>"},{"location":"changelog/#fixed_18","title":"Fixed","text":"<ul> <li><code>groupChoice</code> help output now includes the choices in the help output metavar</li> <li><code>TermUi.edit*</code> functions could freeze on certain editors (#99, thanks @iampravikant and @sebokopter)</li> <li>Shell completion can now handle command names with dashes. (#104)</li> <li>Arguments with <code>=</code> in them could be incorrectly interpreted as options (#106)</li> </ul>"},{"location":"changelog/#230","title":"2.3.0","text":""},{"location":"changelog/#added_19","title":"Added","text":"<ul> <li><code>option().groupSwitch()</code>, which works like <code>groupChoice()</code>, but uses a <code>switch()</code> option rather than a <code>choice()</code> option.</li> <li><code>UsageError</code> now has a <code>statusCode</code> parameter (which defaults to 1). If you\u2019re using <code>ClicktCommand.main</code>, the value of <code>statusCode</code> will be passed to <code>exitProcess</code>. </li> </ul>"},{"location":"changelog/#changed_20","title":"Changed","text":"<ul> <li>Shell completion code is now printed by throwing a <code>PrintCompletionMessage</code> (a subclass of <code>PrintMessage</code>) rather than calling <code>echo</code> directly.</li> </ul>"},{"location":"changelog/#220","title":"2.2.0","text":""},{"location":"changelog/#added_20","title":"Added","text":"<ul> <li>Added <code>enum()</code> conversion for options and arguments. (#84)</li> </ul>"},{"location":"changelog/#changed_21","title":"Changed","text":"<ul> <li>There are now several ways of preventing @-file expansion</li> </ul>"},{"location":"changelog/#fixed_19","title":"Fixed","text":"<ul> <li>Help output missing items when no help text is specified. (#85)</li> <li>Help output not grouping options in groups passed to <code>groupChoice</code>. (#88)</li> </ul>"},{"location":"changelog/#210","title":"2.1.0","text":""},{"location":"changelog/#added_21","title":"Added","text":"<ul> <li>Ability to prevent rewrapping individual paragraphs in help output.</li> <li>Added parameter <code>required</code> to <code>Option.multiple()</code> to require at least one instance of the option on the command line.</li> </ul>"},{"location":"changelog/#changed_22","title":"Changed","text":"<ul> <li><code>CliktCommand.toString()</code> now includes the names and values of all parameters and subcommands.</li> </ul>"},{"location":"changelog/#fixed_20","title":"Fixed","text":"<ul> <li>Create subcommand context when <code>helpOptionNames</code> is empty. (#64)</li> </ul>"},{"location":"changelog/#200","title":"2.0.0","text":""},{"location":"changelog/#added_22","title":"Added","text":"<ul> <li>Bash autocomplete script generation. A property named <code>completionCandidates</code> has been added to <code>Argument</code> and <code>Option</code> interfaces, and corresponding parameters have been added to the various implementation constructors, as well as the <code>convert</code> functions. You can use this to control the values autocomplete that will be suggested.</li> <li><code>option().split()</code>, and the corresponding <code>OptionWithValues.valueSplit</code>.</li> <li>Marking options as deprecated with <code>option().deprecated()</code></li> <li>You can manually set the pattern to split envvars on by passing a pattern to the <code>envvarSplit</code> parameter of <code>option()</code></li> <li>Option groups, mutually exclusive groups, co-occurring groups, and choice options with groups</li> <li>Support for Command line argument files a.k.a. \u201c@-files\u201d</li> </ul>"},{"location":"changelog/#changed_23","title":"Changed","text":"<ul> <li>If multiple <code>--</code> tokens are present on the command line, all subsequent occurrences after the first are now parsed as positional arguments. Previously, subsequent <code>--</code> tokens were skipped.  </li> <li>The <code>PlaintextHelpFormatter</code> has been replaced with <code>CliktHelpFormatter</code>, which is more customizable. See the docs for more info, or the new sample for an example of customizing help output to use ANSI colors.</li> <li>Some of the properties and constructor parameters for <code>OptionWithValues</code> and <code>ProcessedArgument</code> have changed.</li> <li>The <code>OptionDelegate</code> interface has changed, and <code>GroupableOption</code> and <code>ParameterHolder</code> interfaces have been added to work with option groups.</li> <li>Parameter validation now occurs after all parameter delegates have set their values, so the lambdas passed to <code>validate</code> may reference other parameters. </li> </ul>"},{"location":"changelog/#170","title":"1.7.0","text":""},{"location":"changelog/#added_23","title":"Added","text":"<ul> <li><code>printHelpOnEmptyArgs</code> parameter to <code>CliktCommand</code> constructor. (#41)</li> </ul>"},{"location":"changelog/#fixed_21","title":"Fixed","text":"<ul> <li>Usage errors now correctly print subcommand names. (#47)</li> <li>Arguments with <code>multiple(required=true)</code> now report an error if no argument is given on the command line. (#36)</li> </ul>"},{"location":"changelog/#160","title":"1.6.0","text":""},{"location":"changelog/#added_24","title":"Added","text":"<ul> <li><code>.multiple().unique()</code> modifier for options and arguments.</li> </ul>"},{"location":"changelog/#fixed_22","title":"Fixed","text":"<ul> <li>Support multi-line input when redirecting stdin</li> </ul>"},{"location":"changelog/#150","title":"1.5.0","text":""},{"location":"changelog/#added_25","title":"Added","text":"<ul> <li>Ability to use alternate output streams rather than stdin and stdout by setting <code>Context.console</code> or by passing a console to <code>TermUI</code> functions.</li> </ul>"},{"location":"changelog/#140","title":"1.4.0","text":""},{"location":"changelog/#added_26","title":"Added","text":"<ul> <li><code>path()</code> type for parameter values</li> </ul>"},{"location":"changelog/#changed_24","title":"Changed","text":"<ul> <li>Clikt now targets JVM 8 bytecode</li> <li>Responses to <code>TermUi.confirm()</code> are now case-insensitive</li> </ul>"},{"location":"changelog/#130","title":"1.3.0","text":""},{"location":"changelog/#added_27","title":"Added","text":"<ul> <li><code>defaultLazy</code> extension for options and arguments</li> </ul>"},{"location":"changelog/#changed_25","title":"Changed","text":"<ul> <li><code>main</code> now prints messages to stderr instead of stdout</li> </ul>"},{"location":"changelog/#fixed_23","title":"Fixed","text":"<ul> <li>Parameter help messages are now wrapped more consistently</li> </ul>"},{"location":"changelog/#120","title":"1.2.0","text":""},{"location":"changelog/#added_28","title":"Added","text":"<ul> <li>Default parameter to <code>option().default()</code></li> </ul>"},{"location":"changelog/#changed_26","title":"Changed","text":"<ul> <li>Treat tokens with unknown prefixes as arguments (this makes it easier   to pass in file paths without using <code>--</code>).</li> </ul>"},{"location":"changelog/#110","title":"1.1.0","text":""},{"location":"changelog/#added_29","title":"Added","text":"<ul> <li><code>List&lt;String&gt;</code> overloads to <code>CliktCommand.parse</code> and <code>main</code></li> <li><code>err</code> parameter to <code>TermUi.echo</code></li> <li><code>error</code> property to <code>Abort</code></li> </ul>"},{"location":"commands/","title":"Commands","text":"<p>Clikt supports arbitrarily nested commands. You can add one command as a child of another with the <code>subcommands</code> function, which can be called either in an <code>init</code> block, or on an existing instance.</p>"},{"location":"commands/#executing-nested-commands","title":"Executing Nested Commands","text":"<p>For commands with no children, <code>run</code> is called whenever the command line is parsed (unless parsing is aborted from an error or an option like <code>--help</code>).</p> <p>If a command has children, this isn\u2019t the case. Instead, its <code>run</code> is called only if a child command is invoked, just before the subcommand\u2019s <code>run</code>. If a parent command is called without specifying a subcommand, the help page is printed and <code>run</code> is not called.</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    val verbose by option().flag(\"--no-verbose\")\n    override fun run() {\n        echo(\"Verbose mode is ${if (verbose) \"on\" else \"off\"}\")\n    }\n}\n\nclass Execute : CliktCommand() {\n    override fun run() {\n        echo(\"executing\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  --verbose / --no-verbose\n  -h, --help                Show this message and exit\n\nCommands:\n  execute\n</code></pre> <pre><code>$ ./tool --verbose execute\nVerbose mode is on\nexecuting\n</code></pre>"},{"location":"commands/#customizing-command-name","title":"Customizing Command Name","text":"<p>The default name for subcommands is inferred as a lowercase name from the command class name. You can also set a name manually in the <code>CliktCommand</code> constructor.</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    override fun run()= Unit\n}\n\nclass Execute : CliktCommand(name = \"RUN-ME\") {\n    override fun run() {\n        echo(\"executing\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool RUN-ME\nexecuting\n</code></pre> <pre><code>$ ./tool -h\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  -h, --help  Show this message and exit\n\nCommands:\n  RUN-ME\n</code></pre>"},{"location":"commands/#passing-parameters","title":"Passing Parameters","text":"<p>When calling subcommands, the position of options and arguments on the command line affect which command will parse them. A parameter is parsed by a command if it occurs after the command name, but before any other command names.</p> ExampleUsage <pre><code>class Tool : CliktCommand() {\n    override fun help(context: Context) = \"A tool that runs\"\n    val verbose by option().flag(\"--no-verbose\")\n    override fun run() = Unit\n}\n\nclass Execute : CliktCommand() {\n    override fun help(context: Context) = \"Execute the command\"\n    val name by option()\n    override fun run() = Unit\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\n  A tool that runs\n\nOptions:\n  --verbose / --no-verbose\n  -h, --help                Show this message and exit\n\nCommands:\n  execute  Execute the command\n</code></pre> <p>If you instead execute <code>--help</code> after the subcommand, the subcommand\u2019s help is printed:</p> <pre><code>$ ./tool execute --help\nUsage: execute [&lt;options&gt;]\n\n  Execute the command\n\nOptions:\n  --name &lt;text&gt;\n  -h, --help   Show this message and exit\n</code></pre> <p>But executing <code>./tool --help execute</code>, with the option before the subcommand, will cause the parent\u2019s help option to be invoked, printing out <code>Tool</code>\u2019s help page as if you just typed <code>./tool --help</code>.</p>"},{"location":"commands/#nested-handling-and-contexts","title":"Nested Handling And Contexts","text":"<p>Normally nested command are independent of each other: a child can\u2019t access its parent\u2019s parameters. This makes composing commands much easier, but what if you want to pass information to a child command? You can do so with the command\u2019s <code>Context</code>.</p> <p>Every time the command line is parsed, each command creates a new context object for itself that is linked to its parent\u2019s context. <code>Context</code> objects have a number of properties that can be used to customize command line parsing. Although each command creates its own context, the configuration is inherited from the parent context.</p> <p><code>Context</code> objects also have a [<code>data</code>][Context.data] map and <code>obj</code> property that hold objects that can be accessed from child commands.</p> ExampleUsage <pre><code>data class MyConfig(var verbose: Boolean = false)\n\nclass Tool : CliktCommand() {\n    val verbose by option().flag(\"--no-verbose\")\n    val config by findOrSetObject { MyConfig() }\n    override fun run() {\n        config.verbose = if (verbose) \"on\" else \"off\"\n    }\n}\n\nclass Execute : CliktCommand() {\n    val config by requireObject&lt;MyConfig&gt;()\n    override fun run() {\n        echo(\"Verbose mode is ${config.verbose}\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Tool().subcommands(Execute()).main(args)\n</code></pre> <pre><code>$ ./tool --verbose execute\nVerbose mode is on\n</code></pre> <p>The <code>findObject</code>, <code>findOrSetObject</code>, and <code>requireObject</code> functions will walk up the context tree until they find a <code>obj</code> with the given type. If no such object exists, they will either return <code>null</code>, throw an exception, or create an instance of the object and store it on the command\u2019s context, depending on which function you use. If you need more than one object, you can pass a <code>key</code> to these functions, and they\u2019ll look for an object with that key and type in the context\u2019s <code>data</code> map.</p> <p>Keep in mind that the <code>findOrSetObject</code> property is lazy and won\u2019t set the Context\u2019s <code>obj</code> until its value is accessed. If you need to set an object for subcommands without accessing the property, you should use <code>currentContext.findOrSetObject</code>, or set <code>currentContext.obj</code> or <code>Context.Builder.obj</code> directly, instead.</p> Eager initialization with findOrSetObjectEager initialization with currentContext.objEager initialization with context builder <pre><code>class Tool : CliktCommand() {\n    override fun run() {\n        // runs eagerly\n        currentContext.findOrSetObject { MyConfig() }\n    }\n}\n</code></pre> <pre><code>class Tool : CliktCommand() {\n    override fun run() {\n        // runs eagerly, won't look for parent contexts\n        currentContext.obj = MyConfig()\n    }\n}\n</code></pre> <pre><code>Tool().context {\n    // runs eagerly, won't look for parent contexts\n    obj = MyConfig()\n}\n</code></pre> <p>Tip</p> <p>If you need to share resources that need to be cleaned up, you can use <code>currentContext.registerCloseable</code></p>"},{"location":"commands/#running-parent-command-without-children","title":"Running Parent Command Without Children","text":"<p>Normally, if a command has children, <code>run</code> is not called unless a child command is invoked on the command line. Instead, <code>--help</code> is called on the parent. If you want to change this behavior to always call <code>run()</code> on the parent, you can do so by setting <code>invokeWithoutSubcommand</code> to <code>true</code>. The <code>Context</code> will then have information on the subcommand that is about to be invoked, if there is one.</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    override val invokeWithoutSubcommand = true\n    override fun run() {\n        val subcommand = currentContext.invokedSubcommand\n        if (subcommand == null) {\n            echo(\"invoked without a subcommand\")\n        } else {\n            echo(\"about to run ${subcommand.name}\")\n        }\n    }\n}\n\nclass Execute : CliktCommand() {\n    override fun run() {\n        echo(\"running subcommand\")\n    }\n}\n</code></pre> <pre><code>$ ./tool\ninvoked without a subcommand\n</code></pre> <pre><code>$./tool execute\nabout to run execute\nrunning subcommand\n</code></pre>"},{"location":"commands/#customizing-contexts","title":"Customizing Contexts","text":"<p>Contexts have a number of properties that can be customized, and which are inherited by child commands. You can change these properties with the <code>context</code> builder function, which can be called in an <code>init</code> block, or on a command instance.</p> <p>For example, you can change the name of help option. These definitions are equivalent:</p> Version 1Version 2Usage <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        context { helpOptionNames = setOf(\"/help\") }\n    }\n}\nfun main(args: Array&lt;String&gt;) = Cli()\n</code></pre> <pre><code>class Cli : NoOpCliktCommand()\nfun main(args: Array&lt;String&gt;) = Cli()\n    .context { helpOptionNames = setOf(\"/help\") }\n    .main(args)\n</code></pre> <pre><code>$ ./cli --help\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  -h, --help  print the help\n</code></pre>"},{"location":"commands/#printing-the-help-message-when-no-arguments-are-given","title":"Printing the Help Message When No Arguments Are Given","text":"<p>Normally, if a command is called with no values on the command line, a usage error is printed if there are required parameters, or <code>run</code> is called if there aren\u2019t any.</p> <p>You can change this behavior by passing overriding <code>printHelpOnEmptyArgs = true</code> in your command. This will cause a help message to be printed when no values are provided on the command line, regardless of the parameters in your command.</p> ExampleUsage <pre><code>class Cli : CliktCommand() {\n    override val printHelpOnEmptyArgs = true\n    val arg by argument()\n    override fun run() { echo(\"Command ran\") }\n}\n</code></pre> <pre><code>$ ./cli\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  -h, --help  print the help\n</code></pre>"},{"location":"commands/#warnings-and-other-messages","title":"Warnings and Other Messages","text":"<p>When you want to show information to the user, you\u2019ll usually want to use the functions for printing to stdout directly.</p> <p>However, there\u2019s another mechanism that can be useful when writing reusable parameter code: command messages. These messages are buffered during parsing and printed all at once immediately before a command\u2019s <code>run</code> is called. They are not printed if there are any errors in parsing. This type of message is used by Clikt for <code>deprecating options</code>.</p> <p>You can issue a command message by calling <code>CliktCommand.issueMessage</code> or with the <code>message</code> function available in the context of parameter transformers.</p> ExampleUsage 1Usage 2 <pre><code>class Cli : CliktCommand() {\n    // This will print the warning when the option is given, but not if there are errors\n    val opt by option().validate {\n        if (it.isEmpty()) message(\"Empty strings are not recommended\")\n    }\n    override fun run() {\n        echo(\"command run\")\n    }\n}\n</code></pre> <pre><code>$ ./cli --opt=''\nEmpty strings are not recommended\ncommand run\n</code></pre> <pre><code>$ ./cli --opt='' --oops\nError: no such option: \"--oops\".\n</code></pre> <p>You can disable automatic message printing on the command\u2019s context:</p> ExampleUsage <pre><code>class Cli : CliktCommand() {\n    init { context { printExtraMessages = false } }\n    val opt by option().validate {\n        if (it.isEmpty()) message(\"Empty strings are not recommended\")\n    }\n    override fun run() {\n        echo(\"command run\")\n    }\n}\n</code></pre> <pre><code>$ ./cli --opt=''\ncommand run\n</code></pre>"},{"location":"commands/#chaining-and-repeating-subcommands","title":"Chaining and Repeating Subcommands","text":"<p>Some command line interfaces allow you to call more than one subcommand at a time. For example, you might do something like <code>gradle clean build publish</code> to run the <code>clean</code> task, then the <code>build</code> task, then the <code>publish</code> task, which are all subcommands of <code>gradle</code>.</p> <p>To do this with Clikt, override <code>allowMultipleSubcommands = true</code> in your command.</p> ExampleUsage <pre><code>class Compiler: CliktCommand() {\n    override val allowMultipleSubcommands = true\n    override fun run() {\n        echo(\"Running compiler\")\n    }\n}\n\nclass Clean: CliktCommand() {\n    val force by option().flag()\n    override fun run() {\n        echo(\"Cleaning (force=$force)\")\n    }\n}\n\nclass Build: CliktCommand() {\n    val file by argument().file()\n    override fun run() {\n        echo(\"Building $file\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Compiler().subcommands(Clean(), Build()).main(args)\n</code></pre> <pre><code>$ ./compiler clean --force build main.kt\nRunning compiler\nCleaning (force=true)\nBuilding main.kt\n</code></pre> <p>The parent command will <code>run</code> once, and each subcommand will <code>run</code> once each time they\u2019re called.</p> <p>Warning</p> <p>Enabling <code>allowMultipleSubcommands</code> will disable <code>allowInterspersedArgs</code> on the command and all its subcommands. If both were allowed to be enabled at the same time, then not all command lines could be parsed unambiguously.</p> <p>Subcommands of a command with <code>allowMultipleSubcommands=true</code> can themselves have subcommands, but cannot have <code>allowMultipleSubcommands=true</code>.</p>"},{"location":"commands/#command-pipelines","title":"Command pipelines","text":"<p>If you have multiple subcommands you might want to pass the output of one subcommand to the next. For example, the ImageMagick tool lets you apply a series of transformations to an image by invoking multiple subcommands.</p> <p>To do this with Clikt, you could pass your output through the <code>Context.obj</code>, but another option is to use a ChainedCliktCommand, which allows you to return values from your <code>run</code> function that will be passed to the next subcommand.</p> <p>In this example, we\u2019ll write simple text editing pipeline that takes an initial string, and then applies a series of transformations to it, printing the final result:</p> ExampleUsage <pre><code>class EditText : ChainedCliktCommand&lt;String&gt;() {\n    override val allowMultipleSubcommands: Boolean = true\n    val text by argument()\n    override fun run(value: String): String = text\n}\n\nclass RepeatText : ChainedCliktCommand&lt;String&gt;(\"repeat\") {\n    val count by option().int().default(1)\n    override fun run(value: String): String {\n        return value.repeat(count)\n    }\n}\n\nclass UppercaseText : ChainedCliktCommand&lt;String&gt;(\"uppercase\") {\n    override fun run(value: String): String {\n        return value.uppercase()\n    }\n}\n\nclass ReplaceText : ChainedCliktCommand&lt;String&gt;(\"replace\") {\n    val oldValue by argument()\n    val newValue by argument()\n    override fun run(value: String): String {\n        return value.replace(oldValue, newValue)\n    }\n}\n\nfun main(args: Array&lt;String&gt;) {\n    val command = EditText()\n        .subcommands(RepeatText(), UppercaseText(), ReplaceText())\n    val result = command.main(args, \"\")\n    command.echo(result)\n}\n</code></pre> <pre><code>$ ./edit-text 'hello ' uppercase repeat --count=3 replace H Y\nYELLO YELLO YELLO\n</code></pre>"},{"location":"documenting/","title":"Documenting Scripts","text":"<p>Clikt takes care of creating formatted help messages for commands. There are a number of ways to customize the default behavior. You can also implement your own <code>HelpFormatter</code> and set it on the command\u2019s context.</p>"},{"location":"documenting/#help-texts","title":"Help Texts","text":"<p>You can add help text to commands and parameters. For parameters, you can pass a <code>help</code> string or  use the <code>help()</code> extension. For commands, you can override the <code>help</code> and <code>helpEpilog</code> methods.</p> ExampleAlternate styleHelp output <pre><code>class Hello : CliktCommand() {\n    override fun help(context: Context) = \"\"\"\n    This script prints &lt;name&gt; &lt;count&gt; times.\n\n    &lt;count&gt; must be a positive number, and defaults to 1.\n    \"\"\".trimIndent()\n    val count by option(\"-c\", \"--count\", metavar=\"count\", help=\"number of greetings\")\n        .int().default(1)\n    val name by argument(help=\"The name to greet\")\n    override fun run() = repeat(count) { echo(\"Hello $commandName!\") }\n}\n</code></pre> <pre><code>class Hello : CliktCommand() {\n    override fun help(context: Context): String {\n        val style = context.theme.info\n        return \"\"\"\n        This script prints ${style(\"&lt;name&gt;\")} ${style(\"&lt;count&gt;\")} times.\n\n        ${style(\"&lt;count&gt;\")} must be a positive number, and defaults to 1.\n        \"\"\".trimIndent()\n    }\n\n    val count by option(\"-c\", \"--count\", metavar=\"count\").int().default(1)\n        .help { theme.success(\"number of greetings\") }\n    val name by argument()\n        .help(\"The name to greet\")\n    override fun run() = repeat(count) { echo(\"Hello $name!\") }\n}\n</code></pre> <pre><code>$ ./hello --help\nUsage: hello [&lt;options&gt;] &lt;name&gt;\n\n  This script prints &lt;name&gt; &lt;count&gt; times.\n\n  &lt;count&gt; must be a positive number, and defaults to 1.\n\nOptions:\n  -c, --count &lt;count&gt; number of greetings\n  -h, --help          Show this message and exit\n</code></pre> <p>Option names and metavars will appear in help output even if no help string is specified for them. On the other hand, arguments only appear in the usage string. It is possible to add a help string to arguments which will be added to the help page, but the Unix convention is to just describe arguments in the command help.</p>"},{"location":"documenting/#markdown-in-help-texts","title":"Markdown in help texts","text":"<p>You can configure Clikt to use Mordant to render Markdown in help texts. You can use all the normal markdown features, such as lists, tables, and even hyperlinks if your terminal supports them.</p> <p>First, add the <code>:clitk-markdown</code> dependency to your project:</p> <pre><code>dependencies {\n   implementation(\"com.github.ajalt.clikt:clikt-markdown:$cliktVersion\")\n}\n</code></pre> <p>And install the markdown help formatter on your command:</p> <pre><code>val command = MyCommand().installMordantMarkdown()\n</code></pre> <p>Then you can use markdown in your help strings:</p> ExampleHelp output <pre><code>class Tool : NoOpCliktCommand() {\n    init {\n        installMordantMarkdown()\n    }\n    val option by option().help {\n        \"\"\"\n        | This | is | a | table |\n        | ---- | -- | - | ----- |\n        | 1    | 2  | 3 | 4     |\n\n        - This is\n        - a list\n\n        ```\n        You can\n            use code blocks\n        ```\n        \"\"\".trimIndent()\n    }\n}\n</code></pre> <pre><code>Usage: tool [&lt;options&gt;]\n\nOptions:\n  --option=&lt;text&gt;  \u250c\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n                   \u2502 This \u2502 is \u2502 a \u2502 table \u2502\n                   \u255e\u2550\u2550\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u256a\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2561\n                   \u2502 1    \u2502 2  \u2502 3 \u2502 4     \u2502\n                   \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\n                    \u2022 This is\n                    \u2022 a list\n\n                   \u256d\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256e\n                   \u2502You can            \u2502\n                   \u2502    use code blocks\u2502\n                   \u2570\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u256f\n  -h, --help       Show this message and exit\n</code></pre>"},{"location":"documenting/#manual-line-breaks","title":"Manual Line Breaks","text":"<p>If you want to insert a line break manually without preformatting the entire paragraph, you can use the Unicode Next Line (NEL) character. You can type a NEL with the unicode literal <code>\\u0085</code>.</p> <p>Clikt will treat NEL similarly to how <code>&lt;br&gt;</code> behaves in HTML: The NEL will be replaced with a line break in the output, and the paragraph will still be wrapped to the terminal width.</p> ExampleHelp output <pre><code>class Tool : NoOpCliktCommand() {\n    val option by option()\n        .help(\"This help will be at least two lines.\\u0085(this will start a new line)\")\n}\n</code></pre> <pre><code>Usage: tool\n\nOptions:\n  --option    This help will be at least\n              two lines.\n              (this will start a new\n              line)\n  -h, --help  Show this message and exit\n</code></pre> <p>Tip</p> <p>In raw multiline strings (which do not parse escape sequences), you\u2019ll need to insert the NEL with a string template such as <code>${\"\\u0085\"}</code>.</p>"},{"location":"documenting/#subcommand-short-help","title":"Subcommand Short Help","text":"<p>Subcommands are listed in the help page based on their name. They have a short help string which is the first line of their help.</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand()\n\nclass Execute : NoOpCliktCommand() {\n    override fun help(context: Context) = \"\"\"\n        Execute the command.\n\n        The command will be executed.\n        \"\"\".trimIndent()\n}\n\nclass Abort : NoOpCliktCommand() {\n    override fun help(context: Context) = \"Kill any running commands.\"\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  -h, --help  Show this message and exit\n\nCommands:\n  execute  Execute the command.\n  abort    Kill any running commands.\n</code></pre>"},{"location":"documenting/#help-option-customization","title":"Help Option Customization","text":"<p>Clikt adds a help option to every command automatically. It uses the names <code>-h</code> and <code>--help</code> and prints the command\u2019s help message when invoked. </p>"},{"location":"documenting/#changing-the-help-option-names","title":"Changing the help option names","text":"<p>Any help option name that conflicts with another option is not used for the help option. If the help option has no unique names, it is not added.</p> <p>You can change the help option\u2019s name and help message on the command\u2019s context:</p> ExampleUsage <pre><code>class HelpLocalization: Localization {\n    override fun helpOptionMessage(): String = \"show the help\"\n}\n\nclass Tool : NoOpCliktCommand() {\n    init {\n        context {\n            helpOptionNames = setOf(\"/help\")\n            localization = HelpLocalization()\n        }\n    }\n}\n</code></pre> <pre><code>$ ./tool /help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  /help  show the help\n</code></pre> <p>If you don\u2019t want a help option to be added, you can set <code>helpOptionNames = emptySet()</code></p>"},{"location":"documenting/#changing-the-help-option-behavior","title":"Changing the help option behavior","text":"<p>If you want to run some code when the help option is invoked, or change its behavior, you can define the option yourself. The default help option is an eager option that throws a PrintHelpMessage, so if you wanted to log some information when the help option is invoked, you could do something like this:</p> ExampleExample 2Usage <pre><code>class CustomHelpCommand : TestCommand() {\n    init {\n        eagerOption(\"-h\", \"--help\", help=\"Show this message and exit\") {\n            echo(\"about to print help\")\n            throw PrintHelpMessage(context)\n        }\n    }\n}\n</code></pre> <pre><code>// If you want to use the help message from the localization, you can register an option\n// with eager=true and use the lazy `help` method.\nclass CustomHelpCommand : TestCommand() {\n    init {\n        registerOption(\n            option(\"-h\", \"--help\", eager=true).flag()\n                .help { context.localization.helpOptionMessage() }\n                .validate {\n                    if(it) {\n                        echo(\"about to print help\")\n                        throw PrintHelpMessage(context)\n                    }\n                }\n        )\n    }\n}\n</code></pre> <pre><code>$ ./tool --help\nabout to print help\nUsage: custom-help [&lt;options&gt;]\n\nOptions:\n  -h, --help  Show this message and exit\n</code></pre> <p>Warning</p> <p>Eager options can\u2019t reference other options or arguments, since they\u2019re evaluated before parsing the rest of the command line.</p>"},{"location":"documenting/#default-values-in-help","title":"Default Values in Help","text":"<p>You can configure the help formatter to show default values in the help output by passing <code>showDefaultValues = true</code> to the <code>MordantHelpFormatter</code>. By default, the string value of the default value will be shown. You can show a different value by passing the value you want to show to the <code>defaultForHelp</code> parameter of <code>default</code>.</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand() {\n    init {\n        context {\n            helpFormatter = { MordantHelpFormatter(it, showDefaultValues = true) }\n        }\n    }\n\n    val a by option(help = \"this is optional\").default(\"value\")\n    val b by option(help = \"this is also optional\").default(\"value\", defaultForHelp=\"chosen for you\")\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  --a &lt;text&gt;    this is optional (default: value)\n  --b &lt;text&gt;    this is also optional (default: chosen for you)\n</code></pre>"},{"location":"documenting/#required-options-in-help","title":"Required Options in Help","text":"<p>By default, <code>required</code> options are displayed the same way as other options. The help formatter includes two different ways to show that an option is required.</p>"},{"location":"documenting/#required-option-marker","title":"Required Option Marker","text":"<p>You can pass a character to the <code>requiredOptionMarker</code> argument of the <code>MordantHelpFormatter</code>.</p> ExampleUsage <pre><code>class Tool : NoOpCliktCommand() {\n    init {\n        context {\n            helpFormatter = { MordantHelpFormatter(it, requiredOptionMarker = \"*\") }\n        }\n    }\n\n    val option by option(help = \"this is optional\")\n    val required by option(help = \"this is required\").required()\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  --option &lt;text&gt;    this is optional\n* --required &lt;text&gt;  this is required\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"documenting/#required-option-tag","title":"Required Option Tag","text":"<p>You can also show a tag for required options by passing <code>showRequiredTag = true</code> to the <code>MordantHelpFormatter</code>.</p> ExampleUsage <pre><code>class Tool : CliktCommand() {\n    init {\n        context {\n            helpFormatter = { MordantHelpFormatter(it, showRequiredTag = true) }\n        }\n    }\n\n    val option by option(help = \"this is optional\")\n    val required by option(help = \"this is required\").required()\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n  --option &lt;text&gt;    this is optional\n  --required &lt;text&gt;  this is required (required)\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"documenting/#grouping-options-in-help","title":"Grouping Options in Help","text":"<p>You can group options into separate help sections by using OptionGroup and importing groups.provideDelegate. The name of the group will be shown in the output. You can also add an extra help message to be shown with the group. Groups can\u2019t be nested.</p> ExampleUsage <pre><code>import com.github.ajalt.clikt.parameters.groups.provideDelegate\n\nclass UserOptions : OptionGroup(\n        name = \"User Options\",\n        help = \"Options controlling the user\"\n) {\n    val name by option(help = \"user name\")\n    val age by option(help = \"user age\").int()\n}\n\nclass Tool : NoOpCliktCommand() {\n    val userOptions by UserOptions()\n}\n</code></pre> <pre><code>$ ./tool --help\nUsage: cli [&lt;options&gt;]\n\nUser Options:\n\n  Options controlling the user\n\n  --name &lt;text&gt;  user name\n  --age &lt;int&gt;    user age\n\nOptions:\n  -h, --help  Show this message and exit\n</code></pre>"},{"location":"documenting/#suggesting-corrections-for-mistyped-parameters","title":"Suggesting Corrections for Mistyped Parameters","text":"<p>When an option or subcommand is mistyped, Clikt will suggest corrections that are similar to the typed value.</p> Mistyped OptionMistyped Subcommand <pre><code>$ ./cli --sise=5\nError: no such option: \"--sise\". Did you mean \"--size\"?\n</code></pre> <pre><code>$ ./cli building\nUsage: cli [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nError: no such subcommand: \"building\". Did you mean \"build\"?\n</code></pre> <p>By default, Clikt will suggest corrections of any similar option or subcommand name based on a similarity metric. You can customize the suggestions by setting <code>suggestTypoCorrection</code> on your command\u2019s context.</p> <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        context {\n            // Only suggest corrections that start with the entered value\n            suggestTypoCorrection = { enteredValue, possibleValues -&gt;\n                possibleValues.filter { it.startsWith(enteredValue) }\n            }\n        }\n    }\n}\n</code></pre>"},{"location":"documenting/#localization","title":"Localization","text":"<p>You can localize error messages by implementing <code>Localization</code> and setting the <code>localization</code> property on your context.</p> ExampleUsage <pre><code>class CursiveLocalization : Localization {\n    override fun usageTitle() = \"\ud835\udcb0\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52:\"\n    override fun optionsTitle() = \"\ud835\udcaa\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8\"\n    override fun optionsMetavar() = \"\ud835\udc5c\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8\"\n    override fun helpOptionMessage() = \"\ud835\udcae\ud835\udcbd\ud835\udc5c\ud835\udccc \ud835\udcc9\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc2\ud835\udc52\ud835\udcc8\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52 \ud835\udcb6\ud835\udcc3\ud835\udcb9 \ud835\udc52\ud835\udccd\ud835\udcbe\ud835\udcc9\"\n\n    // ... override the rest of the strings here\n}\n\nclass I18NTool : NoOpCliktCommand() {\n    override fun help(context: Context) = \"\ud835\udcaf\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc9\ud835\udc5c\ud835\udc5c\ud835\udcc1 \ud835\udcbe\ud835\udcc8 \ud835\udcbe\ud835\udcc3 \ud835\udcb8\ud835\udcca\ud835\udcc7\ud835\udcc8\ud835\udcbe\ud835\udccb\ud835\udc52\"\n    init { context { localization = CursiveLocalization() } }\n}\n</code></pre> <pre><code>$ ./i18ntool --help\n\ud835\udcb0\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52: i18ntool [&lt;\ud835\udc5c\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8&gt;]\n\n  \ud835\udcaf\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc9\ud835\udc5c\ud835\udc5c\ud835\udcc1 \ud835\udcbe\ud835\udcc8 \ud835\udcbe\ud835\udcc3 \ud835\udcb8\ud835\udcca\ud835\udcc7\ud835\udcc8\ud835\udcbe\ud835\udccb\ud835\udc52\n\n\ud835\udcaa\ud835\udcc5\ud835\udcc9\ud835\udcbe\ud835\udc5c\ud835\udcc3\ud835\udcc8:\n  -h, --help  \ud835\udcae\ud835\udcbd\ud835\udc5c\ud835\udccc \ud835\udcc9\ud835\udcbd\ud835\udcbe\ud835\udcc8 \ud835\udcc2\ud835\udc52\ud835\udcc8\ud835\udcc8\ud835\udcb6\ud835\udc54\ud835\udc52 \ud835\udcb6\ud835\udcc3\ud835\udcb9 \ud835\udc52\ud835\udccd\ud835\udcbe\ud835\udcc9\n</code></pre>"},{"location":"exceptions/","title":"Exception Handling","text":"<p>Clikt uses exceptions internally to signal that processing has ended early for any reason. This includes incorrect command line usage, or printing a help page.</p>"},{"location":"exceptions/#where-are-exceptions-handled","title":"Where are Exceptions Handled?","text":"<p>When you call <code>CliktCommand.main</code>, it will parse the command line and catch any <code>CliktError</code> exceptions. If it catches one, it will then print out the error\u2019s message and exit the process with the error\u2019s <code>statusCode</code>. The message is printed to stderr or stdout depending on the error\u2019s <code>printError</code> property.</p> <p>For exceptions raised by Clikt, <code>PrintMessage</code> and <code>PrintHelpMessage</code> have a <code>statusCode</code> of 0 and print to stdout. Other exceptions have a <code>statusCode</code> of 1 and print to stderr.</p> <p>Any other types of exceptions indicate a programming error, and are not caught by <code>main</code>. However, <code>convert</code> and the other parameter transformations will wrap exceptions thrown inside them in a <code>UsageError</code>, so if you define a custom transformation, you don\u2019t have to worry about an exception escaping to the user.</p>"},{"location":"exceptions/#handling-exceptions-manually","title":"Handling Exceptions Manually","text":"<p><code>CliktCommand.main</code> is just a <code>try</code>/<code>catch</code> block surrounding <code>CliktCommand.parse</code>, so if you don\u2019t want exceptions to be caught, you can call <code>parse</code> wherever you would normally call <code>main</code>.</p> <p>Tip</p> <p>You can use echoFormattedHelp to print the help or error message to any exception, or getFormattedHelp to get the help message as a string.</p> <pre><code>fun main(args: Array&lt;String&gt;) {\n    val cli = Cli()\n    try {\n        cli.parse(args)\n    } catch (e: CliktError) {\n        cli.echoFormattedHelp(e)\n        exitProcess(e.statusCode)\n    }\n}\n</code></pre>"},{"location":"exceptions/#which-exceptions-exist","title":"Which Exceptions Exist?","text":"<p>All exceptions thrown by Clikt are subclasses of <code>CliktError</code>.</p> <p>The following subclasses exist:</p> <ul> <li><code>Abort</code> : The command should exit immediately with the given <code>statusCode</code> without printing any messages.</li> <li><code>PrintMessage</code> : The exception\u2019s message should be printed.</li> <li><code>PrintHelpMessage</code> : The help page for the exception\u2019s command should be printed.</li> <li><code>PrintCompletionMessage</code> : Shell completion code for the command should be printed.</li> <li><code>UsageError</code> : The command line was incorrect in some way. All the following exceptions subclass from this. These exceptions are automatically augmented with extra information about the current parameter, if possible.</li> <li><code>MultiUsageError</code> : Multiple <code>UsageError</code>s occurred. The <code>errors</code> property contains the list of the errors.</li> <li><code>ProgramResult</code> : The program should exit with the <code>statusCode</code> from this exception.</li> <li><code>BadParameterValue</code> : A parameter was given the correct number of values, but of invalid format or type.</li> <li><code>MissingOption</code> and <code>MissingArgument</code>: A required parameter was not provided.</li> <li><code>NoSuchOption</code> : An option was provided that does not exist.</li> <li><code>NoSuchSubcommand</code> : A subcommand was called that does not exist.</li> <li><code>IncorrectOptionValueCount</code> : An option was supplied but the number of values supplied to the option was incorrect.</li> <li><code>IncorrectArgumentValueCount</code> : An argument was supplied but the number of values supplied was incorrect.</li> <li><code>MutuallyExclusiveGroupException</code> : Multiple options in a mutually exclusive group were supplied when the group is restricted to a single value.</li> <li><code>FileNotFound</code> : A required configuration file or @-file was not found.</li> <li><code>InvalidFileFormat</code> : A configuration file or @-file failed to parse correctly.</li> </ul>"},{"location":"migration/","title":"Upgrading to Newer Releases","text":"<p>See the [changelog] for a full list of changes in each release. This guide contains information on the most significant changes that may require updating to your code.</p>"},{"location":"migration/#upgrading-to-50","title":"Upgrading to 5.0","text":""},{"location":"migration/#some-methods-like-main-are-now-extensions","title":"some methods like <code>main</code> are now extensions","text":"<p>The <code>CliktCommand.main</code> and <code>CliktCommand.parse</code> methods are now extension functions, so you\u2019ll need to import them.</p> <pre><code>+ import com.github.ajalt.clikt.core.main\nfun main(args: Array&lt;String&gt;) = MyCommand().main(args)\n</code></pre> <p><code>Context.obj</code> and <code>Context.terminal</code>, and <code>OptionTransformContext.terminal</code> are also now extensions.</p> <pre><code>+ import com.github.ajalt.clikt.core.obj\n+ import com.github.ajalt.clikt.core.terminal\n\nfun main() {\n    val ctx = MyCommand().currentContext\n    ctx.terminal.info(ctx.obj)\n}\n</code></pre>"},{"location":"migration/#cliktcommand-constructor-no-longer-takes-most-parameters","title":"<code>CliktCommand</code> constructor no longer takes most parameters","text":"<p>All parameters of the <code>CliktCommand</code> except for <code>name</code> have been moved to open properties.</p> In 5.0In 4.0 <pre><code>class MyCommand : CliktCommand(name=\"mycommand\") {\n    override fun help(context: Context) = \"command help\"\n    override fun helpEpilog(context: Context) = \"command epilog\"\n    override val invokeWithoutSubcommand = true\n    override val printHelpOnEmptyArgs = true\n    override val helpTags = mapOf(\"tag\" to \"value\")\n    override val autoCompleteEnvvar = \"MYCOMMAND_COMPLETE\"\n    override val allowMultipleSubcommands = true\n    override val treatUnknownOptionsAsArgs = true\n    override val hiddenFromHelp = true\n}\n</code></pre> <pre><code>class MyCommand : CliktCommand(\n    name = \"mycommand\",\n    help = \"command help\",\n    helpEpilog = \"command epilog\",\n    invokeWithoutSubcommand = true,\n    printHelpOnEmptyArgs = true,\n    helpTags = mapOf(\"tag\" to \"value\"),\n    autoCompleteEnvvar = \"MYCOMMAND_COMPLETE\",\n    allowMultipleSubcommands = true,\n    treatUnknownOptionsAsArgs = true,\n    hiddenFromHelp = true,\n) {\n}\n</code></pre> <p>The full list of moved parameters:</p> removed parameter new replacement property <code>help</code> <code>fun help</code> <code>epilog</code> <code>fun helpEpilog</code> <code>invokeWithoutSubcommand</code> <code>val invokeWithoutSubcommand</code> <code>printHelpOnEmptyArgs</code> <code>val printHelpOnEmptyArgs</code> <code>helpTags</code> <code>val helpTags</code> <code>autoCompleteEnvvar</code> <code>val autoCompleteEnvvar</code> <code>allowMultipleSubcommands</code> <code>val allowMultipleSubcommands</code> <code>treatUnknownOptionsAsArgs</code> <code>val treatUnknownOptionsAsArgs</code> <code>hidden</code> <code>val hiddenFromHelp</code>"},{"location":"migration/#markdown-moved-to-a-separate-module","title":"Markdown moved to a separate module","text":"<p>In order to reduce executable size, the Markdown rendering functionality has been moved to a separate module.</p> <p>To use Markdown rendering first, add the <code>:clitk-markdown</code> dependency to your project:</p> <pre><code>dependencies {\n   implementation(\"com.github.ajalt.clikt:clikt-markdown:$cliktVersion\")\n}\n</code></pre> <p>Then install the markdown help formatter on your command:</p> <pre><code>val command = MyCommand().installMordantMarkdown()\n</code></pre>"},{"location":"migration/#context-builder-properties-renamed","title":"<code>Context</code> builder properties renamed","text":"<p>Some of the properties on <code>Context</code> and its builder have been renamed to be more consistent:</p> old name new name <code>Context.envvarReader</code> <code>Context.readEnvvar</code> <code>Context.correctionSuggestor</code> <code>Context.suggestTypoCorrection</code> <code>Context.argumentFileReader</code> <code>Context.readArgumentFile</code> <code>Context.tokenTransformer</code> <code>Context.transformToken</code> <p>The old names are still available as deprecated properties.</p>"},{"location":"migration/#removed-termui","title":"Removed <code>TermUi</code>","text":"<p>The remaining methods in <code>TermUi</code> have been removed. If you were using it, you can open an editor manually with <code>ProcessBuilder</code> or similar.</p>"},{"location":"migration/#upgrading-to-40","title":"Upgrading to 4.0","text":""},{"location":"migration/#help-formatting","title":"Help formatting","text":"<p>The <code>CliktHelpFormatter</code> class has been removed and replaced with the <code>MordantHelpFormatter</code>. The <code>MordantHelpFormatter</code> constructor takes a <code>Context</code> instead of a <code>Localization</code>, and the parameters controlling size and spacing have been removed. See the documentation for details on how to set the help formatter on the Context.</p> <p>If you were subclassing <code>CliktHelpFormatter</code>, <code>MordantHelpFormatter</code>\u2019s open methods are different. See the <code>helpformat</code> sample for an example of how to use the new formatter.</p>"},{"location":"migration/#prompting","title":"Prompting","text":"<p>The <code>CliktConsole</code> class has been removed. If you were using it, use your command\u2019s Mordant <code>terminal</code> instead.</p> <p>The <code>prompt</code> and <code>confirm</code> methods now use Mordant\u2019s prompting functionality, and some of their arguments have changed. In particular, conversion lambdas now return a <code>ConversionResult</code>  instead of throwing an exception.</p> In 4.0In 3.0 <pre><code>val input = prompt(\"Enter a number\") {\n    it.toIntOrNull()\n        ?.let { ConversionResult.Valid(it) }\n        ?: ConversionResult.Invalid(\"$it is not a valid integer\")\n}\n</code></pre> <pre><code>val input = prompt(\"Enter a number\") {\n    it.toIntOrNull() ?: throw BadParameterValue(\"$it is not a valid integer\")\n}\n</code></pre>"},{"location":"migration/#upgrading-to-30","title":"Upgrading to 3.0","text":""},{"location":"migration/#maven-coordinates","title":"Maven Coordinates","text":"<p>Clikt\u2019s Maven groupId changed from <code>com.github.ajalt</code> to <code>com.github.ajalt.clikt</code>. So the full coordinate is now <code>com.github.ajalt.clikt:clikt:3.0.0</code>.</p> <p>With the new Multiplatform plugin in Kotlin 1.4, there is no longer a separate <code>clikt-multiplatform</code> artifact. You can use <code>com.github.ajalt.clikt:clikt:3.0.0</code> for both JVM-only and Multiplatform projects.</p>"},{"location":"migration/#environment-variable-splitting","title":"Environment variable splitting","text":"<p>There used to be an <code>envvarSplit</code> parameter to <code>option()</code> and its <code>convert()</code> that would split values coming from an environment variable. This parameter is removed, and values from environment variables are no longer split automatically.</p> <p>If you still want to split option values, you can do so explicitly with <code>split()</code>.</p>"},{"location":"migration/#experimental-apis","title":"Experimental APIs","text":"<p>The Value Source API and Completion Generation APIs no longer require opt-in. You can use these APIs without needing the <code>ExperimentalValueSourceApi</code> or <code>ExperimentalCompletionCandidates</code> annotations.</p>"},{"location":"migration/#localization","title":"Localization","text":"<p>By default, all strings are defined in the <code>Localization</code> object set on your context.</p> <p>This means that string parameters like <code>usageTitle</code> in the constructor for <code>CliktHelpFormatter</code> have been removed in favor of functions like <code>Localization.usageTitle()</code>.</p> <p><code>Context.helpOptionMessage</code> has also been removed in favor of <code>Localization.helpOptionMessage()</code>. See Help Option Customization for an example.</p>"},{"location":"options/","title":"Options","text":"<p>Options are added to commands by defining a property delegate with the <code>option</code> function.</p>"},{"location":"options/#basic-options","title":"Basic Options","text":"<p>The default option takes one value of type <code>String</code>. The property is nullable. If the option is not given on the command line, the property value will be null. If the option is given at least once, the property will return the value of the last occurrence of the option.</p> ExampleUsage <pre><code>class Hello: CliktCommand() {\n    val name by option(help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello --name=Foo\nHello, Foo!\n</code></pre>"},{"location":"options/#option-names","title":"Option Names","text":"<p>If you don\u2019t specify names for an option, a lowercase hyphen-separated name is automatically inferred from the property. For example, <code>val myOpt by option()</code> will create an option that can be called with <code>--my-opt</code>.</p> <p>You can also specify any number of names for an option manually:</p> <pre><code>class Hello: CliktCommand() {\n    val name by option(\"-n\", \"--name\", help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <p>Option names that are two characters long (like <code>-n</code>) are treated as POSIX-style short options. You call them with a value like this:</p> Usage 1Usage 2 <pre><code>$ ./hello -nfoo\nHello, foo!\n</code></pre> <pre><code>$ ./hello -n foo\nHello, foo!\n</code></pre> <p>All other option names are considered long options, and can be called like this:</p> Usage 1Usage 2 <pre><code>$ ./hello --name=foo\nHello, foo!\n</code></pre> <pre><code>$ ./hello --name foo\nHello, foo!\n</code></pre>"},{"location":"options/#customizing-options","title":"Customizing Options","text":"<p>The option behavior and delegate type can be customized by calling extension functions on the <code>option</code> call. For example, here are some different option declarations:</p> <pre><code>val a: String? by option()\nval b: Int? by option().int()\nval c: Pair&lt;Int, Int&gt;? by option().int().pair()\nval d: Pair&lt;Int, Int&gt; by option().int().pair().default(0 to 0)\nval e: Pair&lt;Float, Float&gt; by option().float().pair().default(0f to 0f)\n</code></pre> <p>There are three main types of behavior that can be customized independently:</p> <ol> <li>The type of each value in the option.    The value type is <code>String</code> by default, but can be customized with built-in functions like    <code>int</code> or <code>choice</code>, or manually with <code>convert</code>.    This is detailed in the parameters page.</li> <li>The number of values that the option requires.    Options take one value by default, but this can be changed with    built-in functions like <code>pair</code> and <code>triple</code>, or manually with    <code>transformValues</code>.</li> <li>How to handle all calls to the option (i.e. if the option is not present, or is present more than once).    By default, the option delegate value is the null if the option is not given on the command line,    and will use the value of the last occurrence if the option is given more than once. You can    change this behavior with functions like <code>default</code> and <code>multiple</code>.</li> </ol> <p>Since the three types of customizations are orthogonal, you can choose which ones you want to use, and if you implement a new customization, it can be used with all the existing functions without any repeated code.</p>"},{"location":"options/#default-values","title":"Default Values","text":"<p>By default, option delegates return <code>null</code> if the option wasn\u2019t provided on the command line. You can instead return a default value with <code>default</code>.</p> ExampleUsage 1Usage 2 <pre><code>class Pow : CliktCommand() {\n    val exp by option(\"-e\", \"--exp\").double().default(1.0)\n    override fun run() {\n        echo(\"2 ^ $exp = ${(2.0).pow(exp)}\")\n    }\n}\n</code></pre> <pre><code>$ ./pow -e 8\n2 ^ 8.0 = 256.0\n</code></pre> <pre><code>$ ./pow\n2 ^ 1.0 = 2.0\n</code></pre> <p>If the default value is expensive to compute, or you want to use another parameter as the default, you can use <code>defaultLazy</code> instead of <code>default</code>. It has the same effect, but you give it a lambda returning the default value, and the lambda will only be called if the option isn\u2019t present on the command line.</p> <p>Warning</p> <p>The lambda you pass to <code>defaultLazy</code> is normally called at most once. But the lambda references another parameter, it may be called more than once in order to make sure the parameter it references is available.</p>"},{"location":"options/#multi-value-options","title":"Multi Value Options","text":"<p>Options can take a fixed number of values separated by whitespace, a variable number of values separated by a delimiter, or a variable number of values separated by a whitespace.</p>"},{"location":"options/#options-with-fixed-number-of-values","title":"Options With Fixed Number of Values","text":"<p>There are built in functions for options that take two values (<code>pair</code>, which uses a <code>Pair</code>), or three values (<code>triple</code>, which uses a <code>Triple</code>). You can change the type of each value as normal with functions like <code>int</code>.</p> <p>If you need more values, you can provide your own container with <code>transformValues</code>. You give that function the number of values you want, and a lambda that will transform a list of values into the output container. The list will always have a size equal to the number you specify. If the user provides a different number of values, Clikt will inform the user and your lambda won\u2019t be called.</p> ExampleUsage <pre><code>data class Quad&lt;out T&gt;(val a: T, val b: T, val c: T, val d: T)\nfun &lt;T&gt; Quad&lt;T&gt;.toList(): List&lt;T&gt; = listOf(a, b, c, d)\n\nclass Geometry : CliktCommand() {\n    val square by option().int().pair()\n    val cube by option().int().triple()\n    val tesseract by option().int().transformValues(4) { Quad(it[0], it[1], it[2], it[3]) }\n    override fun run() {\n        echo(\"Square has dimensions ${square?.toList()?.joinToString(\"x\")}\")\n        echo(\"Cube has dimensions ${cube?.toList()?.joinToString(\"x\")}\")\n        echo(\"Tesseract has dimensions ${tesseract?.toList()?.joinToString(\"x\")}\")\n    }\n}\n</code></pre> <pre><code>$ ./geometry --square 1 2 --cube 3 4 5 --tesseract 6 7 8 9\nSquare has dimensions 1x2\nCube has dimensions 3x4x5\nTesseract has dimensions 6x7x8x9\n</code></pre>"},{"location":"options/#splitting-an-option-value-on-a-delimiter","title":"Splitting an Option Value on a Delimiter","text":"<p>You can use <code>split</code> to allow a variable number of values to a single option invocation by separating the values with non-whitespace delimiters. This will also split values from environment variables.</p> ExampleUsageUsage with Environment Variable <pre><code>class C : CliktCommand() {\n    val profiles by option(\"-P\", envvar=\"PROFILES\").split(\",\")\n    override fun run() {\n        for (profile in profiles) {\n            echo(profile)\n        }\n    }\n}\n</code></pre> <pre><code>$ ./split -P profile-1,profile-2\nprofile-1\nprofile-2\n</code></pre> <pre><code>$ export PROFILES=profile-1,profile-2\n$ ./split\nprofile-1\nprofile-2\n</code></pre>"},{"location":"options/#options-with-an-optional-value","title":"Options with an Optional Value","text":"<p>You can create options that take zero or one values with <code>optionalValue</code> or <code>optionalValueLazy</code>.</p> ExampleUsage with no option valueUsage with option valueUsage with no option <pre><code>class C : CliktCommand() {\n    val log by option().optionalValue(\"debug\").default(\"none\")\n    override fun run() {\n        echo(\"log level: $log\")\n    }\n}\n</code></pre> <pre><code>$ ./command --log\nlog level: debug\n</code></pre> <pre><code>$ ./command --log=verbose\nlog level: verbose\n</code></pre> <pre><code>$ ./command\nlog level: none\n</code></pre> <p>Warning</p> <p>If a user specifies the value without an <code>=</code>, as in <code>--log debug</code>, the <code>debug</code> will always be interpreted as a value for the option, even if the command accepts arguments. This might be confusing to your users, so you can require that the option value always be specified with <code>=</code> by passing <code>optionalValue(acceptsUnattachedValue=false)</code>.</p>"},{"location":"options/#options-with-a-variable-number-of-values","title":"Options With a Variable Number of Values","text":"<p>If you want your option to take a variable number of values, but want to split the value on whitespace  rather than a delimiter, you can use <code>varargValues</code>.</p> ExampleUsage <pre><code>class Order : CliktCommand() {\n    val sizes: List&lt;String&gt; by option().varargValues()\n    override fun run() {\n        echo(\"You ordered: $sizes\")\n    }\n}\n</code></pre> <pre><code>$ ./order --sizes small medium\nYou ordered: [\"small\", \"medium\"]\n</code></pre> <p>By default, <code>varargValues</code> requires at least one value, and has no maximum limit. You can configure the limits by passing <code>min</code> and <code>max</code> arguments to <code>varargValues</code>.</p>"},{"location":"options/#multiple-options","title":"Multiple Options","text":"<p>Normally, when an option is provided on the command line more than once, only the values from the last occurrence are used. But sometimes you want to keep all values provided. For example, <code>git commit -m foo -m bar</code> would create a commit message with two lines: <code>foo</code> and <code>bar</code>. To get this behavior with Clikt, you can use <code>multiple</code>. This will cause the property delegate value to be a list, where each item in the list is the value of from one occurrence of the option. If the option is never given, the list will be empty (or you can specify a default to use).</p> ExampleUsage <pre><code>class Commit : CliktCommand() {\n    val message: List&lt;String&gt; by option(\"-m\").multiple()\n    override fun run() {\n        echo(message.joinToString(\"\\n\"))\n    }\n}\n</code></pre> <pre><code>$ ./commit -m foo -m bar\nfoo\nbar\n</code></pre> <p>You can combine <code>multiple</code> with item type conversions and multiple values.</p> <pre><code>val opt: List&lt;Pair&lt;Int, Int&gt;&gt; by option().int().pair().multiple()\n</code></pre>"},{"location":"options/#default-values-for-optionmultiple","title":"Default values for option().multiple()","text":"<p>You can also supply a default value to <code>multiple</code> or require at least one value be present on the command line. These are specified as arguments rather than with separate extension functions since they don\u2019t change the type of the delegate.</p> RequiredDefault <pre><code>val opt: List&lt;String&gt; by option().multiple(required=true)\n</code></pre> <pre><code>val opt: List&lt;String&gt; by option().multiple(default=listOf(\"default message\"))\n</code></pre>"},{"location":"options/#deduplicating-optionmultiple-into-a-unique-set","title":"Deduplicating option().multiple() into a unique set","text":"<p>You can discard duplicate values from a <code>multiple</code> option with <code>unique</code>.</p> ExampleUsage <pre><code>class Build : CliktCommand() {\n    val platforms: Set&lt;String&gt; by option(\"-p\").multiple().unique()\n    override fun run() {\n        echo(\"Building for platforms: $platforms\")\n    }\n}\n</code></pre> <pre><code>$ ./build -p android -p ios -p android\nBuilding for platforms: [android, ios]\n</code></pre>"},{"location":"options/#key-value-and-map-options","title":"Key-Value and Map Options","text":"<p>You can split an option\u2019s value into a key-value pair with <code>splitPair</code>. By default, the delimiter <code>=</code> will be used to split. You can also use <code>associate</code> to allow the option to be specified multiple times, and have its values collected in a map.</p> ExampleUsage <pre><code>class Build : CliktCommand() {\n    val systemProp: Map&lt;String, String&gt; by option(\"-D\", \"--system-prop\").associate()\n\n    override fun run() {\n        echo(systemProp)\n    }\n}\n</code></pre> <pre><code>$ ./build -Dplace=here --system-prop size=small\n{place=here, size=small}\n</code></pre>"},{"location":"options/#boolean-flag-options","title":"Boolean Flag Options","text":"<p>Flags are options that don\u2019t take a value. Boolean flags can be enabled or disabled, depending on the name used to invoke the option. You can turn an option into a boolean flag with <code>flag</code>. That function takes an optional list of secondary names that will be added to any existing or inferred names for the option. If the option is invoked with one of the secondary names, the delegate will return false. It\u2019s a good idea to always set secondary names so that a user can disable the flag if it was enabled previously.</p> ExampleUsage 1Usage 2 <pre><code>class Cli : CliktCommand() {\n    val flag by option(\"--on\", \"-o\").flag(\"--off\", \"-O\", default = false)\n    override fun run() {\n        echo(flag)\n    }\n}\n</code></pre> <pre><code>$ ./cli -o\ntrue\n</code></pre> <pre><code>$ ./cli --on --off\nfalse\n</code></pre> <p>Multiple short flag options can be combined when called on the command line:</p> ExampleUsage <pre><code>class Cli : CliktCommand() {\n    val flagA by option(\"-a\").flag()\n    val flagB by option(\"-b\").flag()\n    val foo by option(\"-f\")\n    override fun run() {\n        echo(\"$flagA $flagB $foo\")\n    }\n}\n</code></pre> <pre><code>$ ./cli -abfFoo\ntrue true Foo\n</code></pre> <p>Tip</p> <p>You can diasable short option grouping by setting <code>Context.allowGroupedShortOptions</code> to <code>false</code>.</p>"},{"location":"options/#counted-flag-options","title":"Counted Flag Options","text":"<p>You might want a flag option that counts the number of times it occurs on the command line. You can use <code>counted</code> for this.</p> <p>You can specify a <code>limit</code> for the number of times the <code>counted</code> option can be given, and either <code>clamp</code> the value or show an error if the limit is exceeded.</p> ExampleUsage <pre><code>class Log : CliktCommand() {\n    val verbosity by option(\"-v\").counted(limit=3, clamp=true)\n    override fun run() {\n        echo(\"Verbosity level: $verbosity\")\n    }\n}\n</code></pre> <pre><code>$ ./log -vvv\nVerbosity level: 3\n</code></pre>"},{"location":"options/#feature-switch-flags","title":"Feature Switch Flags","text":"<p>Another way to use flags is to assign a value to each option name. You can do this with <code>switch</code>, which takes a map of option names to values. Note that the names in the map replace any previously specified or inferred names.</p> ExampleUsage <pre><code>class Size : CliktCommand() {\n    val size by option().switch(\n        \"--large\" to \"large\",\n        \"--small\" to \"small\"\n    ).default(\"unknown\")\n    override fun run() {\n        echo(\"You picked size $size\")\n    }\n}\n</code></pre> <pre><code>$ ./size --small\nYou picked size small\n</code></pre>"},{"location":"options/#choice-options","title":"Choice Options","text":"<p>You can restrict the values that a regular option can take to a set of values using <code>choice</code>. You can also map the input values to new types.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>class Digest : CliktCommand() {\n    val hash by option().choice(\"md5\", \"sha1\")\n    override fun run() {\n        echo(hash)\n    }\n}\n</code></pre> <pre><code>$ ./digest --hash=md5\nmd5\n</code></pre> <pre><code>$ ./digest --hash=sha256\nUsage: digest [&lt;options&gt;]\n\nError: Invalid value for \"--hash\": invalid choice: sha256. (choose from md5, sha1)\n</code></pre> <pre><code>$ ./digest --help\nUsage: digest [&lt;options&gt;]\n\nOptions:\n  --hash [md5|sha1]\n  -h, --help         Show this message and exit\n</code></pre>"},{"location":"options/#mutually-exclusive-option-groups","title":"Mutually Exclusive Option Groups","text":"<p>If <code>choice</code> or <code>switch</code> options aren\u2019t flexible enough, you can use <code>mutuallyExclusiveOptions</code> to group any nullable options into a mutually exclusive group. If more than one of the options in the group is given on the command line, the last value is used.</p> <p>If you want different types for each option, you can wrap them in a sealed class.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>sealed class Fruit {\n    data class Oranges(val size: String): Fruit()\n    data class Apples(val count: Int): Fruit()\n}\nclass Order : CliktCommand() {\n    val fruit: Fruit? by mutuallyExclusiveOptions&lt;Fruit&gt;(\n        option(\"--oranges\").convert { Oranges(it) },\n        option(\"--apples\").int().convert { Apples(it) }\n    )\n\n    override fun run() = echo(fruit)\n}\n</code></pre> <pre><code>$ ./order --apples=10\nApples(count=10)\n</code></pre> <pre><code>$ ./order --oranges=small\nOranges(size=small)\n</code></pre> <pre><code>$ ./order --apples=10 --oranges=large\nOranges(size=large)\n</code></pre> <p>You can enforce that only one of the options is given with <code>single</code>:</p> ExampleUsage <pre><code>val fruit: Fruit? by mutuallyExclusiveOptions&lt;Fruit&gt;(\n        option(\"--apples\").convert { Apples(it.toInt()) },\n        option(\"--oranges\").convert { Oranges(it) }\n).single()\n</code></pre> <pre><code>$ ./order --apples=10 --oranges=small\nUsage: order [&lt;options&gt;]\n\nError: option --apples cannot be used with --oranges\n</code></pre> <p>Like regular options, you can make the entire group <code>required</code>, or give it a <code>default</code> value.</p> <p>Like other option groups, you can specify a <code>name</code> and <code>help</code> text for the group if you want to set the group apart in the help output.</p>"},{"location":"options/#co-occurring-option-groups","title":"Co-Occurring Option Groups","text":"<p>Sometimes you have a set of options that only make sense when specified together. To enforce this, you can make an option group <code>cooccurring</code>.</p> <p>Co-occurring groups must have at least one <code>required</code> option, and may also have non-required options. The <code>required</code> constraint is enforced if any of the options in the group are given on the command line. If none of the options are given, the value of the group is null.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>class UserOptions : OptionGroup() {\n    val name by option().required()\n    val age by option().int()\n}\nclass Tool : CliktCommand() {\n    val userOptions by UserOptions().cooccurring()\n    override fun run() {\n        userOptions?.let {\n            echo(it.name)\n            echo(it.age)\n        } ?: echo(\"No user options\")\n    }\n}\n</code></pre> <pre><code>$ ./tool\nNo user options\n</code></pre> <pre><code>$ ./tool --name=jane --age=30\njane\n30\n</code></pre> <pre><code>$ ./tool --age=30\nUsage: tool [&lt;options&gt;]\n\nError: Missing option \"--name\".\n</code></pre> <p>Like other option groups, you can specify a <code>name</code> and <code>help</code> text for the group if you want to set the group apart in the help output.</p>"},{"location":"options/#choice-and-switch-options-with-groups","title":"Choice and Switch Options With Groups","text":"<p>If you have different groups of options that only make sense when another option has a certain value, you can use <code>groupChoice</code> and <code>groupSwitch</code>.</p> <p><code>groupChoice</code> options are similar to <code>choice</code> options, but instead of mapping a value to a single new type, they map a value to a co-occurring <code>OptionGroup</code>. Options for groups other than the selected one are ignored, and only the selected group\u2019s <code>required</code> constraints are enforced. In the same way, <code>groupSwitch</code> options are similar to <code>switch</code> options.</p> ExampleUsage 1Usage 2Usage 3Usage 4 <pre><code>sealed class LoadConfig(name: String): OptionGroup(name)\nclass FromDisk : LoadConfig(\"Options for loading from disk\") {\n    val path by option().file().required()\n    val followSymlinks by option().flag()\n}\n\nclass FromNetwork: LoadConfig(\"Options for loading from network\") {\n    val url by option().required()\n    val username by option().prompt()\n    val password by option().prompt(hideInput = true)\n}\n\nclass Tool : CliktCommand() {\n    val load by option().groupChoice(\n            \"disk\" to FromDisk(),\n            \"network\" to FromNetwork()\n    )\n\n    override fun run() {\n        when(val it = load) {\n            is FromDisk -&gt; echo(\"Loading from disk: ${it.path}\")\n            is FromNetwork -&gt; echo(\"Loading from network: ${it.url}\")\n            null -&gt; echo(\"Not loading\")\n        }\n    }\n}\n</code></pre> <pre><code>$ ./tool --load=disk --path=./config --follow-symlinks\nLoading from disk: .\\config\n</code></pre> <pre><code>$ ./tool --load=network --url=www.example.com --username=admin\nPassword: *******\nLoading from network: www.example.com\n</code></pre> <pre><code>$ ./tool --load=disk\nUsage: cli [&lt;options&gt;]\n\nError: Missing option \"--path\".\n</code></pre> <pre><code>$ ./tool --load=whoops\nUsage: cli [&lt;options&gt;]\n\nError: Invalid value for \"--load\": invalid choice: whoops. (choose from disk, network)\n</code></pre>"},{"location":"options/#number-options-without-a-name","title":"Number Options Without a Name","text":"<p>If you have an int or long option, you might want to allow it to be specified without need the option name. For example, <code>git log -2</code> and <code>git log -n 2</code> are equivalent. You can add an option like this by passing <code>acceptsValueWithoutName=true</code> to <code>int()</code> or <code>long()</code>.</p> ExampleUsage 1Usage 2Help Output <pre><code>class Tool : CliktCommand() {\n    val level by option(\"-l\", \"--level\", metavar = \"&lt;number&gt;\")\n        .int(acceptsValueWithoutName = true)\n\n    override fun run() {\n        echo(\"Level: $level\")\n    }\n}\n</code></pre> <pre><code>$ ./tool -20\nLevel: 20\n</code></pre> <pre><code>$ ./tool --level=3\nLevel: 3\n</code></pre> <pre><code>$ ./tool --help\nUsage: tool [&lt;options&gt;]\n\nOptions:\n-&lt;number&gt;, -l, --level &lt;number&gt;\n-h, --help             Show this message and exit\n</code></pre> <p>Caution</p> <p>You may only have one option with <code>acceptsValueWithoutName=true</code> per command</p>"},{"location":"options/#prompting-for-input","title":"Prompting For Input","text":"<p>In some cases, you might want to create an option that uses the value given on the command line if there is one, but prompt the user for input if one is not provided. Clikt can take care of this for you with the <code>prompt</code> function.</p> ExampleUsage 1Usage 2 <pre><code>class Hello : CliktCommand() {\n    val name by option().prompt()\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>./hello --name=foo\nHello foo\n</code></pre> <pre><code>./hello\nName: foo\nHello foo\n</code></pre> <p>The default prompt string is based on the option name, but <code>prompt</code> takes a number of parameters to customize the output.</p>"},{"location":"options/#password-prompts","title":"Password Prompts","text":"<p>You can also create an option that uses a hidden prompt and asks for confirmation. This combination of behavior is commonly used for passwords.</p> ExampleUsage <pre><code>class Login : CliktCommand() {\n    val password by option().prompt(requireConfirmation = true, hideInput = true)\n    override fun run() {\n        echo(\"Your hidden password: $password\")\n    }\n}\n</code></pre> <pre><code>$ ./login\nPassword:\nYour hidden password: hunter2\n</code></pre>"},{"location":"options/#eager-options","title":"Eager Options","text":"<p>Sometimes you want an option to halt execution immediately and print a message. For example, the built-in <code>--help</code> option, or the <code>--version</code> option that many programs have.</p> <p>The <code>--help</code> option is added automatically to commands, and <code>--version</code> can be added using <code>versionOption</code>. Since these options don\u2019t have values, you can\u2019t define them using property delegates. Instead, call the function on a command directly, either in an <code>init</code> block, or on a command instance.</p> <p>These definitions are equivalent:</p> Version 1Version 2Usage <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        versionOption(\"1.0\")\n    }\n}\nfun main(args: Array&lt;String&gt;) = Cli().main(args)\n</code></pre> <pre><code>class Cli : NoOpCliktCommand()\nfun main(args: Array&lt;String&gt;) = Cli().versionOption(\"1.0\").main(args)\n</code></pre> <pre><code>$ ./cli --version\ncli version 1.0\n</code></pre>"},{"location":"options/#custom-eager-options","title":"Custom Eager Options","text":"<p>If you want to define your own option with a similar behavior, you can do so by calling <code>eagerOption</code>. This function takes an <code>action</code> that is called when the option is encountered on the command line. To print a message and halt execution normally from the callback, you can throw a <code>PrintMessage</code> exception, and <code>CliktCommand.main</code> will take care of printing the message. If you want to exit normally without printing a message, you can throw <code>Abort(error=false)</code> instead.</p> <p>You can define your own version option like this:</p> <pre><code>class Cli : NoOpCliktCommand() {\n    init {\n        eagerOption(\"--version\") {\n            throw PrintMessage(\"$name version 1.0\")\n        }\n    }\n}\n</code></pre>"},{"location":"options/#custom-eager-options-with-values","title":"Custom Eager Options With Values","text":"<p>If you need an eager option that takes a value, pass <code>eager=true</code> to <code>option()</code>.</p> <pre><code>val color by option(eager=true).flag(\"--no-color\", default=true)\n</code></pre> <p>Warning</p> <p>Eager options can\u2019t reference other options or arguments, since they\u2019re evaluated before parsing the rest of the command line. They can be declared in regular <code>OptionGroups</code>, but not in other types of groups like switch groups.</p>"},{"location":"options/#deprecating-options","title":"Deprecating Options","text":"<p>You can communicate to users that an option is deprecated with <code>option().deprecated()</code>. By default, this function will add a tag to the option\u2019s help message, and print a warning to stderr if the option is used.</p> <p>You can customize or omit the warning message and help tags, or change the warning into an error.</p> ExampleUsage 1Usage 2Usage 3Usage 4Help Output <pre><code>class Cli : CliktCommand() {\n   val opt by option(help = \"option 1\").deprecated()\n   val opt2 by option(help = \"option 2\").deprecated(\"WARNING: --opt2 is deprecated, use --new-opt instead\", tagName = null)\n   val opt3 by option(help = \"option 3\").deprecated(tagName = \"pending deprecation\", tagValue = \"use --new-opt instead\")\n   val opt4 by option(help = \"option 4\").deprecated(error = true)\n\n   override fun run() = echo(\"command run\")\n}\n</code></pre> <pre><code>$ ./cli --opt=x\nWARNING: option --opt is deprecated\ncommand run\n</code></pre> <pre><code>$ ./cli --opt2=x\nWARNING: --op2 is deprecated, use --new-opt instead\ncommand run\n</code></pre> <pre><code>$ ./cli --opt3=x\nWARNING: option --opt3 is deprecated\ncommand run\n</code></pre> <pre><code>$ ./cli --opt4=x\nERROR: option --opt4 is deprecated\n</code></pre> <pre><code>$ ./cli --help\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  --opt &lt;text&gt;   option 1 (deprecated)\n  --opt2 &lt;text&gt;  option 2\n  --opt3 &lt;text&gt;  option 3 (pending deprecation: use --new-opt instead)\n  --opt4 &lt;text&gt;  option 4 (deprecated)\n</code></pre>"},{"location":"options/#unknown-options","title":"Unknown Options","text":"<p>You may want to collect unknown options for manual processing. You can do this by overriding <code>treatUnknownOptionsAsArgs = true</code> in your command. This will cause Clikt to treat unknown options as positional arguments rather than reporting an error when one is encountered. You\u2019ll need to define an <code>argument().multiple()</code> property to collect the options, otherwise an error will still be reported.</p> ExampleUsage <pre><code>class Wrapper : CliktCommand() {\n    init { context { allowInterspersedArgs = false }}\n    override val treatUnknownOptionsAsArgs = true\n\n    val command by option().required()\n    val arguments by argument().multiple()\n\n    override fun run() {\n        val cmd = (listOf(command) + arguments).joinToString(\" \")\n        val proc = Runtime.getRuntime().exec(cmd)\n        echo(proc.inputStream.bufferedReader().readText())\n        proc.waitFor()\n    }\n}\n</code></pre> <pre><code>$ ./wrapper --command=git tag --help | head -n4\nGIT-TAG(1)                        Git Manual                        GIT-TAG(1)\n\nNAME\n       git-tag - Create, list, delete or verify a tag object signed with GPG\n</code></pre> <p>Warning</p> <p>Multiple short options in a single token (e.g. using <code>-abc</code> to specify <code>-a</code>, <code>-b</code>, and <code>-c</code> in a single token) will still report an error if it contains a mixture of known and unknown options. To avoid this, don\u2019t declare single-letter names for options in commands that use <code>treatUnknownOptionsAsArgs</code>.</p> <p>You\u2019ll often want to set <code>allowInterspersedArgs = false</code> on your Context when using <code>treatUnknownOptionsAsArgs</code>. You may also find that subcommands are a better fit than <code>treatUnknownOptionsAsArgs</code> for your use case.</p>"},{"location":"options/#values-from-environment-variables","title":"Values From Environment Variables","text":"<p>Clikt supports reading option values from environment variables if they aren\u2019t given on the command line. This feature is helpful when automating tools. For example, when using <code>git commit</code>, you can set the author date with a command line parameter: <code>git commit --date=10/21/2015</code>. But you can also set it with an environment variable: <code>GIT_AUTHOR_DATE=10/21/2015 git commit</code>.</p> <p>Clikt will read option values from environment variables as long as it has an envvar name for the option. There are two ways to set that name: you can set the name manually for an option, or you can enable automatic envvar name inference.</p> <p>To set the envvar name manually, pass the name to <code>option</code>:</p> ExampleUsage 1Usage 2 <pre><code>class Hello : CliktCommand() {\n    val name by option(envvar = \"MY_NAME\")\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>$ export MY_NAME=Foo\n$ ./hello\nHello Foo\n</code></pre> <pre><code>$ export MY_NAME=Foo\n$ ./hello --name=Bar\nHello Bar\n</code></pre> <p>You can enable automatic envvar name inference by setting the <code>autoEnvvarPrefix</code> on a command\u2019s <code>context</code>. This will cause all options without an explicit envvar name to be given an uppercase underscore-separated envvar name. Since the prefix is set on the <code>context</code>, it is propagated to subcommands. If you have a subcommand called <code>foo</code> with an option <code>--bar</code>, and your prefix is <code>MY_TOOL</code>, the option\u2019s envvar name will be <code>MY_TOOL_FOO_BAR</code>.</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    init {\n        context { autoEnvvarPrefix = \"HELLO\" }\n    }\n    val name by option()\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>$ export HELLO_NAME=Foo\n$ ./hello\nHello Foo\n</code></pre>"},{"location":"options/#multiple-values-from-environment-variables","title":"Multiple Values from Environment Variables","text":"<p>You might need to allow users to specify multiple values for an option in a single environment variable. You can do this by creating an option with <code>split</code>.</p>"},{"location":"options/#flag-option-values-from-environment-variables","title":"Flag Option Values from Environment Variables","text":"<p>For flag options, any of the following (case-insensitive) environment variable values will be interpreted as <code>true</code>:</p> <ul> <li><code>\"true\"</code>, <code>\"t\"</code>, <code>\"1\"</code>, <code>\"yes\"</code>, <code>\"y\"</code>, <code>\"on\"</code></li> </ul> <p>The following (case-insensitive) values wil be interpreted as <code>false</code>:</p> <ul> <li><code>\"false\"</code>, <code>\"f\"</code>, <code>\"0\"</code>, <code>\"no\"</code>, <code>\"n\"</code>, <code>\"off\"</code></li> </ul> <p>All other values are invalid.</p>"},{"location":"options/#overriding-system-environment-variables","title":"Overriding system environment variables","text":"<p>You can set a custom function that will be used instead of the system environment variables with ContextBuilder.readEnvvar.</p> <pre><code>@Test\nfun `test envvar`() {\n    val envvars = mapOf(\"MY_TOOL_OPTION\" to \"value\")\n    val tool = MyTool().context {\n        readEnvvar = { envvars[it] }\n    }\n    tool.parse(emptyList())\n    assertEquals(\"value\", tool.option)\n}\n</code></pre>"},{"location":"options/#values-from-configuration-files","title":"Values from Configuration Files","text":"<p>Clikt also supports reading option values from one or more configuration files (or other sources) when they aren\u2019t present on the command line. For example, when using <code>git commit</code>, you can set the author email with a command line parameter: <code>git commit --author='Clikt &lt;clikt@example.com&gt;</code>. But you can also set it in your git configuration file: <code>user.email=clikt@example.com</code>.</p> <p>Clikt allows you to specify one or more sources of option values that will be read from with the <code>Context.valueSource</code> builder.</p> ExampleUsage <pre><code>class Hello : CliktCommand() {\n    init {\n        context {\n            valueSource = PropertiesValueSource.from(\"myconfig.properties\")\n        }\n    }\n    val name by option()\n    override fun run() {\n        echo(\"Hello $name\")\n    }\n}\n</code></pre> <pre><code>$ echo \"name=Foo\" &gt; myconfig.properties\n$ ./hello\nHello Foo\n</code></pre> <p>You can also pass multiple sources to <code>Context.valueSources</code>, and each source will be searched for the value in order.</p> <p>Clikt includes support for reading values from a map, and (on JVM) from Java Properties files. For these two sources, you can customize the keys used to look up options by passing the result of <code>ValueSource.getKey</code> or <code>ValueSource.envvarKey</code> to the source\u2019s <code>getKey</code> constructor parameter.</p> <p>You can add any other file type by implementing ValueSource. See the JSON sample for an implementation that uses kotlinx.serialization to load values from JSON files.</p>"},{"location":"options/#configuration-files-and-environment-variables","title":"Configuration Files and Environment Variables","text":"<p>Every option can read values from both environment variables and configuration files. By default, Clikt will use the value from an environment variable before the value from a configuration file, but you can change this by setting <code>Context.readEnvvarBeforeValueSource</code> to <code>false</code>.</p>"},{"location":"options/#windows-and-java-style-option-prefixes","title":"Windows and Java-Style Option Prefixes","text":"<p>When specifying option names manually, you can use any prefix (as long as it\u2019s entirely punctuation).</p> <p>For example, you can make a Windows-style interface with slashes:</p> ExampleUsage <pre><code>class Hello: CliktCommand() {\n    val name by option(\"/name\", help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello /name Foo\nHello, Foo!\n</code></pre> <p>Or you can make a Java-style interface that uses single-dashes for long options:</p> ExampleUsage <pre><code>class Hello: CliktCommand() {\n    val name by option(\"-name\", help=\"your name\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <pre><code>$ ./hello -name Foo\nHello, Foo!\n</code></pre> <p>Note</p> <p>Inferred names will always have a POSIX-style prefix like <code>--name</code>. If you want to use a different prefix, you should specify all option names manually.</p>"},{"location":"options/#option-transformation-order","title":"Option Transformation Order","text":"<p>Clikt has a large number of extension functions that can modify options. When applying multiple functions to the same option, there\u2019s only one valid order for the functions to be applied. For example, <code>option().default(3).int()</code> will not compile, because <code>default</code> must be applied after the value type conversion. </p> <p>You can call <code>convert</code> multiple times, but you can only apply one transform of each other type. So <code>option().default(\"\").multiple()</code> is invalid, since <code>default</code> and <code>multiple</code> both transform the call list (if you need a custom default value for <code>multiple</code>, you can pass it one as an argument).</p> <p>Here\u2019s an integer option with one of each available transform in a valid order:</p> <pre><code>val opt: Pair&lt;Int, Int&gt; by option(\"-o\", \"--opt\")\n        .int()\n        .restrictTo(1..100)\n        .pair()\n        .default(1 to 2)\n        .validate { require(it.second % 2 == 0) }\n</code></pre>"},{"location":"parameters/","title":"Parameters","text":"<p>Clikt supports two types of parameters: options and positional arguments. If you\u2019re following Unix conventions with your interface, you should use options for most parameters. Options are usually optional, and arguments are frequently required.</p>"},{"location":"parameters/#differences","title":"Differences","text":"<p>Arguments have the advantage of being able to accept a variable number of values, while Options are limited to a fixed number of values. Other than that restriction, options have more capabilities than arguments.</p> <p>Options can:</p> <ul> <li>Act as flags (options don\u2019t have to take values)</li> <li>Prompt for missing input</li> <li>Load values from environment variables</li> </ul> <p>In general, arguments are usually used for values like file paths or URLs, or for required values, and options are used for everything else.</p>"},{"location":"parameters/#parameter-names","title":"Parameter Names","text":"<p>Both options and arguments can infer their names (or the metavar in the case of arguments) from the name of the property. You can also specify the names manually. Options can have any number of names, where arguments only have a single metavar.</p> ExampleHelp Output <pre><code>class Cli : CliktCommand() {\n    val inferredOpt by option()\n    val inferred by argument()\n    val explicitOpt by option(\"-e\", \"--explicit\")\n    val explicitArg by argument(\"&lt;explicit&gt;\")\n    override fun run() = Unit\n}\n</code></pre> <pre><code>Usage: cli [&lt;options&gt;] &lt;inferred&gt; &lt;explicit&gt;\n\nOptions:\n  --inferred-opt &lt;text&gt;\n  -e, --explicit &lt;text&gt;\n  -h, --help           Show this message and exit\n</code></pre>"},{"location":"parameters/#parameter-types","title":"Parameter Types","text":"<p>Both options and arguments can convert the String that the user inputs to other types.</p> <p>Types work by transforming the return value of the property delegate. By default, parameters have a string type:</p> <pre><code>val opt: String? by option(help=\"an option\")\nval arg: String by argument(help=\"an argument\")\n</code></pre> <p>To convert the input to an integer, for example, use the <code>int()</code> extension function:</p> <pre><code>val opt: Int? by option(help=\"an option\").int()\nval arg: Int by argument(help=\"an argument\").int()\n</code></pre>"},{"location":"parameters/#built-in-types","title":"Built-In Types","text":"<p>There are a number of built-in types that can be applied to options and arguments.</p>"},{"location":"parameters/#int-and-long","title":"Int and Long","text":"<ul> <li><code>option().int()</code> and <code>argument().int()</code></li> <li><code>option().long()</code> and <code>argument().long()</code></li> <li><code>option().uint()</code> and <code>argument().uint()</code></li> <li><code>option().ulong()</code> and <code>argument().ulong()</code></li> </ul> <p>By default, any value that fits in the integer type is accepted. You can restrict the values to a range with <code>restrictTo()</code>, which allows you to either clamp the input to the range, or fail with an error if the input is outside the range.</p>"},{"location":"parameters/#float-and-double","title":"Float and Double","text":"<ul> <li><code>option().float()</code> and <code>argument().float()</code></li> <li><code>option().double()</code> and <code>argument().double()</code></li> </ul> <p>As with integers, you can restrict the input to a range with <code>restrictTo()</code>.</p>"},{"location":"parameters/#boolean","title":"Boolean","text":"<ul> <li><code>option().flag()</code></li> <li><code>option().boolean()</code> and <code>argument().boolean()</code></li> </ul> <p>You will normally want to use flags for boolean options. Explicit boolean value conversion is also available if you need, for example, a tri-state <code>Boolean?</code> parameter.</p>"},{"location":"parameters/#choice","title":"Choice","text":"<ul> <li><code>option().choice()</code> and <code>argument().choice()</code></li> </ul> <p>You can restrict the values to a set of values, and optionally map the input to a new value. For example, to create an option that only accepts the value \u201ca\u201d or \u201cb\u201d:</p> <pre><code>val opt: String? by option().choice(\"a\", \"b\")\n</code></pre> <p>You can also convert the restricted set of values to a new type:</p> <pre><code>val color: Int? by argument().choice(\"red\" to 1, \"green\" to 2)\n</code></pre> <p>Choice parameters accept values that are case-sensitive by default. This can be configured by passing <code>ignoreCase = true</code>.</p>"},{"location":"parameters/#enum","title":"Enum","text":"<ul> <li><code>option().enum()</code> and <code>argument().enum()</code></li> </ul> <p>Like <code>choice</code>, but uses the values of an enum type.</p> <pre><code>enum class Color { RED, GREEN }\nval color: Color? by option().enum&lt;Color&gt;()\n</code></pre> <p>Enum parameters accept case-insensitive values by default. This can be configured by passing <code>ignoreCase = false</code>. </p> <p>You can also pass a lambda to map the enum values to option names.</p> <pre><code>val color: Color? by option().enum&lt;Color&gt; { it.name.lowercase() }\n</code></pre>"},{"location":"parameters/#file-paths","title":"File paths","text":"<ul> <li><code>option().file()</code> and <code>argument().file()</code></li> <li><code>option().path()</code> and <code>argument().path()</code></li> </ul> <p>These conversion functions take extra parameters that allow you to require that values are file paths that have certain attributes, such as that they are directories, or they are writable files.</p>"},{"location":"parameters/#file-path-inputstream-and-outputstreams","title":"File path <code>InputStream</code> and <code>OutputStream</code>s","text":"<ul> <li><code>option().inputStream()</code> and <code>argument().inputStream()</code></li> <li><code>option().outputStream()</code> and <code>argument().outputStream()</code></li> </ul> <p>Like file and path, these conversions take file path values, but expose them as open streams for reading or writing. They support the unix convention of passing <code>-</code> to specify stdin or stdout rather than a file on the filesystem. You\u2019ll need to close the streams yourself. You can also use stdin or stdout as their default values.</p> <p>If you need to check if one of these streams is pointing to a file rather than stdin or stdout, you can use <code>isCliktParameterDefaultStdin</code> or <code>isCliktParameterDefaultStdout</code>.</p>"},{"location":"parameters/#custom-types","title":"Custom Types","text":"<p>You can convert parameter values to a custom type by using <code>argument().convert()</code> and <code>option().convert()</code>. These functions take a lambda that converts the input <code>String</code> to any type. If the parameter takes multiple values, or an option appears multiple times in <code>argv</code>, the conversion lambda is called once for each value.</p> <p>Any errors that are thrown from the lambda are automatically caught and a usage message is printed to the user. If you need to trigger conversion failure, you can use <code>fail(\"error message\")</code> instead of raising an exception.</p> <p>For example, you can create an option of type <code>BigDecimal</code> like this:</p> ExampleUsage 1Usage 2 <pre><code>class Cli: CliktCommand() {\n    val opt by option().convert { it.toBigDecimal() }\n    override fun run() = echo(\"opt=$opt\")\n}\n</code></pre> <pre><code>$ ./cli --opt=1.5\nopt=1.5\n</code></pre> <pre><code>$ ./cli --opt=foo\nUsage: cli [&lt;options&gt;]\n\nError: Invalid value for \"--opt\": For input string: \"foo\"\n</code></pre>"},{"location":"parameters/#metavars","title":"Metavars","text":"<p>You can also pass <code>option().convert()</code> a metavar that will be printed in the help page instead of the default of <code>value</code>. We can modify the above example to use a metavar and an explicit error message:</p> ExampleUsage 1Usage 2 <pre><code>class Cli: CliktCommand() {\n    val opt by option(help=\"a real number\").convert(\"float\") {\n        it.toBigDecimalOrNull() ?: fail(\"A real number is required\")\n    }\n    override fun run() = echo(\"opt=$opt\")\n}\n</code></pre> <pre><code>$ ./cli --opt=foo\nUsage: cli [&lt;options&gt;]\n\nError: Invalid value for \"--opt\": A real number is required\n</code></pre> <pre><code>$ ./cli --help\nUsage: cli [&lt;options&gt;]\n\nOptions:\n  --opt &lt;float&gt;  a real number\n  -h, --help     Show this message and exit\n</code></pre>"},{"location":"parameters/#chaining","title":"Chaining","text":"<p>You can call <code>convert</code> more than once on the same parameter. This allows you to reuse existing conversion functions. For example, you could automatically read the text of a file parameter.</p> ExampleUsage <pre><code>class FileReader: CliktCommand() {\n    val file: String by argument()\n        .file(mustExist=true, canBeDir=false)\n        .convert { it.readText() }\n    override fun run() {\n        echo(\"Your file contents: $file\")\n    }\n}\n</code></pre> <pre><code>$ echo 'some text' &gt; myfile.txt\n$ ./filereader ./myfile.txt\nYour file contents: some text\n</code></pre>"},{"location":"parameters/#parameter-validation","title":"Parameter Validation","text":"<p>After converting a value to a new type, you can perform additional validation on the converted value with <code>check()</code> and <code>validate()</code> (or the argument equivalents).</p>"},{"location":"parameters/#check","title":"<code>check()</code>","text":"<p><code>check()</code> is similar the stdlib function of the same name: it takes lambda that returns a boolean to indicate if the parameter value is valid or not, and reports an error if it returns false. The lambda is only called if the parameter value is non-null.</p> ExampleUsage 1Usage 2Usage 3 <pre><code>class Tool : CliktCommand() {\n    val number by option(help = \"An even number\").int()\n            .check(\"value must be even\") { it % 2 == 0 }\n\n    override fun run() {\n        echo(\"number=$number\")\n    }\n}\n</code></pre> <pre><code>$ ./tool --number=2\nnumber=2\n</code></pre> <pre><code>$ ./tool\nnumber=null\n</code></pre> <pre><code>$ ./tool --number=1\nUsage: tool [&lt;options&gt;]\n\nError: invalid value for --number: value must be even\n</code></pre>"},{"location":"parameters/#validate","title":"<code>validate()</code>","text":"<p>For more complex validation, you can use <code>validate()</code>. This function takes a lambda that returns nothing, but can call <code>fail(\"error message\")</code> if the value is invalid. You can also call <code>require()</code>, which will fail if the provided expression is false. Like <code>check</code>, the lambda is only called if the value is non-null.</p> <p>The lambdas you pass to <code>validate</code> are called after the values for all options and arguments have been set, so (unlike in transforms) you can reference other parameters:</p> ExampleUsage 1Usage 2 <pre><code>class Tool : CliktCommand() {\n    val number by option().int().default(0)\n    val biggerNumber by option().int().validate {\n        require(it &gt; number) {\n            \"--bigger-number must be bigger than --number\"\n        }\n    }\n\n    override fun run() {\n        echo(\"number=$number, biggerNumber=$biggerNumber\")\n    }\n}\n</code></pre> <pre><code>$ ./tool --number=1\nnumber=1, biggerNumber=null\n</code></pre> <pre><code>$ ./tool --number=1 --bigger-number=0\nUsage: tool [&lt;options&gt;]\n\nError: --bigger-number must be bigger than --number\n</code></pre>"},{"location":"quickstart/","title":"Quick Start","text":"<p>You can get the library using any maven-compatible build system. Installation instructions can be found in the README.</p>"},{"location":"quickstart/#basic-concepts","title":"Basic Concepts","text":"<p>Clikt command line interfaces are created by using property delegates inside a <code>CliktCommand</code>. The normal way to use Clikt is to forward <code>argv</code> from your <code>main</code> function to <code>CliktCommand.main</code>.</p> <p>The simplest command with no parameters would look like this:</p> <pre><code>import com.github.ajalt.clikt.core.CliktCommand\nimport com.github.ajalt.clikt.core.main\n\nclass Hello: CliktCommand() {\n    override fun run() {\n        echo(\"Hello World!\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Hello().main(args)\n</code></pre> <p>And what it looks like to use:</p> <pre><code>$ ./hello\nHello World!\n</code></pre> <p>A help page is generated automatically:</p> <pre><code>$ ./hello --help\nUsage: hello [&lt;options&gt;]\n\nOptions:\n  -h, --help  Show this message and exit\n</code></pre>"},{"location":"quickstart/#printing-to-stdout-and-stderr","title":"Printing to Stdout and Stderr","text":"<p>Why does this example use <code>echo</code> instead of <code>println</code>? Although <code>println</code> works, it can cause problems with multi-platform support. <code>echo</code> uses Mordant to print, so it supports colors and detects the current terminal to make sure that colors work on the current system. You can also pass <code>err=true</code> to <code>echo</code> to print to stderr instead of stdout.</p> <p>Additionally, if you use Clikt\u2019s testing utilities, output sent  to <code>echo</code> will be captured for testing, but output sent to <code>println</code> will not.</p>"},{"location":"quickstart/#coroutine-commands-with-suspend-functions","title":"Coroutine commands with suspend functions","text":"<p>If you want to use coroutines in your command, you can use a SuspendingCliktCommand:</p> <pre><code>class Hello : SuspendingCliktCommand() {\n    val count by option(help=\"Number of greetings\").int().default(1)\n    val name by argument()\n\n    override suspend fun run() {\n        for (i in 1..count) {\n            echo(\"Hello $name!\")\n            delay(1000)\n        }\n    }\n}\n\nsuspend fun main(args: Array&lt;String&gt;) = Hello().main(args)\n</code></pre>"},{"location":"quickstart/#nesting-commands","title":"Nesting Commands","text":"<p>Instances of any command can be attached to other commands, allowing arbitrary nesting of commands. For example, you could write a script to manage a database:</p> ExampleUsageHelp Output <pre><code>class Database : CliktCommand(name = \"db\") {\n    override fun run() = Unit\n}\n\nclass Init : CliktCommand() {\n    override fun help(context: Context) = \"Initialize the database\"\n    override fun run() {\n        echo(\"Initialized the database.\")\n    }\n}\n\nclass Drop : CliktCommand() {\n    override fun help(context: Context) = \"Drop the database\"\n    override fun run() {\n        echo(\"Dropped the database.\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Database()\n        .subcommands(Init(), Drop())\n        .main(args)\n</code></pre> <pre><code>$ ./db init\nInitialized the database.\n\n$ ./db drop\nDropped the database.\n</code></pre> <pre><code>$ ./db --help\nUsage: database [&lt;options&gt;] &lt;command&gt; [&lt;args&gt;]...\n\nOptions:\n  -h, --help  Show this message and exit\n\nCommands:\n  init  Initialize the database\n  drop  Drop the database\n</code></pre>"},{"location":"quickstart/#adding-parameters","title":"Adding Parameters","text":"<p>To add parameters, use the <code>option</code> and <code>argument</code> property delegates:</p> ExampleHelp Output <pre><code>class Hello : CliktCommand() {\n    val count by option(help=\"Number of greetings\").int().default(1)\n    val name by argument()\n\n    override fun run() {\n        for (i in 1..count) {\n            echo(\"Hello $name!\")\n        }\n    }\n}\n</code></pre> <pre><code>$ ./hello --help\nUsage: hello [&lt;options&gt;] &lt;name&gt;\n\nOptions:\n  --count &lt;int&gt;  Number of greetings\n  -h, --help     Show this message and exit\n</code></pre>"},{"location":"quickstart/#developing-command-line-applications-with-gradle","title":"Developing Command Line Applications With Gradle","text":"<p>When you write a command line application, you probably want to be able to run it without invoking <code>java -jar ...</code> every time. If you\u2019re using Gradle, the application plugin provides a gradle task that bundles your program jars and scripts to launch them. It makes it easy to build a zip or tarball that you can distribute to your users without them needing to perform any incantations like setting up a classpath. You can see this plugin in use the in Clikt samples.</p> <p>The application plugin also creates tasks that will build then run your main function directly from within gradle. You can pass command line arguments through to your app with the <code>--args</code> flag:</p> <pre><code>$ ./gradlew run --args=\"--count=3 Clikt\"\n</code></pre> <p>A drawback to using the <code>run</code> gradle task is that it redirects stdout, so Clikt will not print colors or prompt for input. You can configure the Mordant terminal that Clikt uses to always print with color, but this will cause ANSI codes to be printed even if you redirect the app\u2019s output to a file.</p> <pre><code>MyCommand().context {\n    terminal = Terminal(ansiLevel = AnsiLevel.TRUECOLOR, interactive = true)\n}.main(args)\n</code></pre> <p>Another approach is to use the <code>installDist</code> task provided by the plugin. This builds all the distribution scripts in your build folder, which you can then execute normally. See Clikt\u2019s runsample script for an example of this approach.</p>"},{"location":"testing/","title":"Testing Clikt Commands","text":"<p>Clikt includes the <code>test</code> extension to help testing commands and their output.</p> TestCommand <pre><code>@Test\nfun testHello() {\n    val command = Hello()\n    val result = command.test(\"--name Foo\")\n    assertEqual(result.stdout, \"Hello, Foo!\")\n    assertEqual(result.exitCode, 0)\n    assertEqual(command.name, \"Foo\")\n}\n</code></pre> <pre><code>class Hello: CliktCommand() {\n    val name by option()\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <p>Calling <code>test</code> will run the command with the given arguments and return a result object that contains the captured outputs and result status code. You can check the captured output with the <code>stdout</code> property of the result, errors output with <code>stderr</code>, or both combined in with <code>output</code>.</p> <p>Caution</p> <p>Output printed with Kotlin\u2019s <code>print</code> and <code>println</code> functions are not captured.  Use <code>echo</code> instead.</p>"},{"location":"testing/#testing-environment-variables","title":"Testing Environment Variables","text":"<p>You can set environment variables for your command by passing in a map of <code>envvars</code>.</p> TestCommand <pre><code>@Test\nfun testHello() {\n    val command = Hello()\n    val result = command.test(\"\", envvars=mapOf(\"HELLO_NAME\" to \"Foo\"))\n    assertEqual(result.stdout, \"Hello, Foo!\")\n}\n</code></pre> <pre><code>class Hello: CliktCommand() {\n    val name by option(envvar=\"HELLO_NAME\")\n    override fun run() {\n        echo(\"Hello, $name!\")\n    }\n}\n</code></pre> <p>To keep tests reproducible, only the envvar values you provide to <code>test</code> are visible to the command. To include system envvars as well, pass <code>includeSystemEnvvars=true</code> to <code>test</code>.</p>"},{"location":"testing/#testing-prompt-options","title":"Testing Prompt Options","text":"<p>If you use <code>prompt</code> options, you can use the <code>stdin</code> parameter of <code>test</code> to pass a string containing all the lines of input. If you have multiple prompts, each input should be separated by <code>\\n</code>.</p> TestCommand <pre><code>@Test\nfun testAdder() {\n    val command = Adder()\n    val result = command.test(\"\", stdin = \"2\\n3\")\n    assertEqual(result.stdout, \"first: second: result: 2 + 3 = 5\")\n}\n</code></pre> <pre><code>class Adder : TestCommand() {\n    val first by option().prompt()\n    val second by option().prompt()\n\n    override fun run_() {\n        echo(\"result: $first + $second = ${first + second}\")\n    }\n}\n</code></pre>"},{"location":"testing/#custom-testing","title":"Custom Testing","text":"<p>If the <code>test</code> helper doesn\u2019t cover all the use cases you need to test, you can run your command yourself.</p> <p>If your command uses environment variables, you can configure the context to return test values for them.</p> <p>To capture output, override the command\u2019s console.</p> <p>By default <code>CliktCommand.main</code>, calls <code>exitProcess</code> when errors occur, which would stop tests from running. You have a couple of choices to handle this:</p>"},{"location":"testing/#configuring-exitprocess","title":"Configuring <code>exitProcess</code>","text":"<p><code>CliktCommand.main</code> calls <code>Context.exitProcess</code> to exit the process. You can set that to an empty lambda to skip it, or one that captures the status value if you want to check it in you tests.</p>"},{"location":"testing/#using-parse-instead-of-main","title":"Using <code>parse</code> instead of <code>main</code>","text":"<p>Instead of calling <code>main</code>, you can use <code>CliktCommand.parse</code>, which throws exceptions with error details rather than printing the details and exiting the process. See the documentation on exceptions for more information on the exceptions that can be thrown.</p>"},{"location":"whyclikt/","title":"Why Clikt?","text":"<p>There are existing Kotlin libraries for creating command line interfaces, and many Java libraries work in Kotlin as well. However, none of them had all the following features:</p> <ul> <li>Unrestricted composability of commands</li> <li>Fully static type safety for parameters</li> <li>Composable parameter customization that doesn\u2019t require registering converter objects.</li> <li>Full support for Unix command line conventions</li> <li>Capable of reading parameter values from environment variables out of the box</li> <li>Included support for common functionality (keyboard interactivity, line ending normalization, launching editors, etc.)</li> <li>Built-in support for multi-token command aliases</li> </ul> <p>Clikt is focused on making writing robust, posix-compliant command line interfaces as easy as possible. A good CLI does more than just parse <code>argv</code>. It allows users to specify values in environment variables, and in some cases prompts for additional input, or opens an editor. Clikt supports all of this out of the box.</p> <p>Sometimes you need to make a CLI that doesn\u2019t follow Unix conventions. You might be writing for windows, or you want to use the Java style of long options with a single dash. Maybe you need to use a bunch of required options instead of arguments, or you want the help page formatted differently. \u201cBest practices\u201d might not be the best for you, so Clikt tries to make implementing uncommon use-cases as easy as possible.</p>"},{"location":"whyclikt/#why-not-a-kotlin-library-like-kotlin-argparser-or-kotlinxcli","title":"Why not a Kotlin library like kotlin-argparser or kotlinx.cli?","text":"<p>Clikt isn\u2019t the only Kotlin CLI library. kotlin-argparser and kotlinx.cli both predate Clikt\u2019s creation.</p> <p>Both, like Clikt, use property delegates to define parameters, but they\u2019re missing most of Clikt features and its extensible design.</p> <p>kotlinx.cli was written by JetBrains and mostly copied kotlin-argparser\u2019s design (and, later, some of Clikt\u2019s).</p> <p>kotlin-argparser works well for simple cases. It\u2019s missing a lot of features that Clikt has, but features could be added. Its real drawback is that it fundamentally does not support composition of commands or parameter values. The lack of subcommand support was already a non-starter, but there are other design decisions that make it unsuitable.</p> <p>In the simple cases, the two libraries are similar. Here\u2019s an example from its README:</p> <pre><code>class MyArgs(parser: ArgParser) {\n    val v: Boolean by parser.flagging(help=\"enable verbose mode\")\n    val username: String? by parser.storing(help=\"name of the user\")\n    val count: Int? by parser.storing(help=\"number of the widgets\") { toInt() }\n    val source: List&lt;String&gt; by parser.positionalList(help=\"source filenames\")\n    val destination: String by parser.positional(help=\"destination\")\n}\n\nfun main(args: Array&lt;String&gt;) = mainBody {\n    ArgParser(args).parseInto(::MyArgs).run {\n        println(\"Hello, $username!\")\n        println(\"Moving $count widgets from $source to $destination.\")\n    }\n}\n</code></pre> <p>Here\u2019s the same thing with Clikt:</p> <pre><code>class Cli : CliktCommand() {\n    val v: Boolean by option(help = \"enable verbose mode\").flag()\n    val username: String? by option(help = \"name of the user\")\n    val count: Int? by option(help = \"number of the widgets\").int()\n    val source: List&lt;String&gt; by argument(help = \"source filenames\").multiple()\n    val destination: String by argument(help = \"destination\")\n    override fun run() {\n        println(\"Hello, $name!\")\n        println(\"Moving $count widgets from $source to $destination.\")\n    }\n}\n\nfun main(args: Array&lt;String&gt;) = Cli().main(args)\n</code></pre> <p>Both work fine, although you may find Clikt more consistent and a bit less verbose. The differences become more pronounced once you try to do anything that isn\u2019t built in to kotlin-argparser.</p> <p>Maybe you need an option to take two values. Here\u2019s another example from the <code>kotlin-argparser</code> README showing how to do that:</p> <pre><code>fun ArgParser.putting(vararg names: String, help: String) =\n          option&lt;MutableMap&lt;String, String&gt;&gt;(*names,\n                  argNames = listOf(\"KEY\", \"VALUE\"),\n                  help = help) {\n              value.orElse { mutableMapOf&lt;String, String&gt;() }.apply {\n                  put(arguments.first(), arguments.last()) }\n          }\n\n fun ArgParser.putting(help: String) =\n          ArgParser.DelegateProvider { identifier -&gt;\n              putting(identifierToOptionName(identifier), help = help) }\n\nclass MyArgs(parser: ArgParser) {\n    val v by parser.putting(help=\"this takes two values\")\n}\n</code></pre> <p>Clikt has that functionality built in as <code>option().pair()</code>, but you could implement it yourself like this:</p> <pre><code>class Cli : CliktCommand() {\n    val v by option(help=\"this takes two values\").transformValues(2) { it[0] to it[1] }\n}\n</code></pre> <p>The Clikt version is of course much simpler, but there are more fundamental issues with the <code>kotlin-argparser</code> version that drove the creation of Clikt:</p> <ul> <li>Its inheritance-based design means that if you wanted to change the type of each value, you would have to copy all the code for each type. With Clikt, you could just do <code>option().int().transformValues(2) { it[0] to it[1] }</code></li> <li>Its inheritance-based design means that supporting types, multiple values, and multiple option occurrences would require a combinatorial number of copies of the above code. With Clikt, these are all orthogonal.</li> <li>You have to do all error checking yourself. The <code>argparser</code> example silently discards extra values, or copies the single value, rather than inform the user of the mistake. You could write more code to do so, but Clikt takes care of it for you.</li> <li>Option name inference is not automatic, requiring you to wrap the delegate with yet another function.</li> <li>Each delegate function has a different name, with no indication of whether it\u2019s creating an option or positional argument. With Clikt, all options are created with <code>option()</code>, and all arguments with <code>argument()</code>.</li> </ul> <p>Some of these problems can be solved by writing more code, and some can\u2019t. On the other hand, Clikt attempts to have a consistent, intuitive, composable design that does the right thing without forcing you to think about edge cases.</p>"},{"location":"whyclikt/#why-not-a-java-library-like-jcommander-or-picocli","title":"Why not a Java library like JCommander or Picocli?","text":"<p>There are a lot of command line libraries for Java. Most are verbose and not composable. Two popular Java libraries that are usable from Kotlin are JCommander and picocli.</p> <p>These libraries use annotations to define parameters, and reflection to set fields. This is functional for simple types, but defining your own types requires you to register a type adapter with the library. This means that type errors are not caught until runtime, and many types of customization are not possible.</p> <p>For example, in JCommander, options that take multiple values cannot be converted to other types. The JCommander docs explain:</p> <p>\u2026 only List is allowed for parameters that define an arity. You will have to convert these values yourself if the parameters you need are of type Integer or other (this limitation is due to Java\u2019s erasure). <p>You also can\u2019t customize many aspects of parsing in JCommander. It can\u2019t infer parameter names. With JCommander, you can\u2019t have an option with multiple values and multiple occurrences at the same time. You can\u2019t have more than one argument, and it can only take one value or an unlimited number of values. You can\u2019t nest subcommands.</p> <p>JCommander and piocli are great libraries if you\u2019re writing code in Java, but we can do much better with Kotlin.</p>"}]}
\ No newline at end of file
diff --git a/sitemap.xml.gz b/sitemap.xml.gz
index 82af0560682f2324adca07b25516e4fee95bca2f..5723fe7c0c8207166ae2c8e88ffdb5036244f684 100755
GIT binary patch
delta 13
Ucmb=gXP58h;COiB#YFZB03xXcaR2}S

delta 13
Ucmb=gXP58h;Bd=%K9Riw037E8X#fBK

diff --git a/testing/index.html b/testing/index.html
index b43e2937..2e50f511 100755
--- a/testing/index.html
+++ b/testing/index.html
@@ -16,7 +16,7 @@
         <link rel="prev" href="../advanced/">
       
       
-        <link rel="next" href="../utilities/">
+        <link rel="next" href="../autocomplete/">
       
       
       <link rel="icon" href="../img/favicon.ico">
@@ -2231,7 +2231,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2240,111 +2240,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2455,10 +2350,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2469,8 +2364,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2560,10 +2455,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2574,8 +2469,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2728,10 +2623,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2742,8 +2637,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>
diff --git a/utilities/index.html b/utilities/index.html
deleted file mode 100755
index 7d72b05a..00000000
--- a/utilities/index.html
+++ /dev/null
@@ -1,2960 +0,0 @@
-
-<!doctype html>
-<html lang="en" class="no-js">
-  <head>
-    
-      <meta charset="utf-8">
-      <meta name="viewport" content="width=device-width,initial-scale=1">
-      
-        <meta name="description" content="Clikt: Multiplatform command line parser for Kotlin">
-      
-      
-        <meta name="author" content="AJ Alt">
-      
-      
-      
-        <link rel="prev" href="../testing/">
-      
-      
-        <link rel="next" href="../autocomplete/">
-      
-      
-      <link rel="icon" href="../img/favicon.ico">
-      <meta name="generator" content="mkdocs-1.5.3, mkdocs-material-9.5.13">
-    
-    
-      
-        <title>Launching Editors - Clikt</title>
-      
-    
-    
-      <link rel="stylesheet" href="../assets/stylesheets/main.7e359304.min.css">
-      
-        
-        <link rel="stylesheet" href="../assets/stylesheets/palette.06af60db.min.css">
-      
-      
-
-
-    
-    
-      
-    
-    
-      
-        
-        
-        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
-        <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Roboto:300,300i,400,400i,700,700i%7CRoboto+Mono:400,400i,700,700i&display=fallback">
-        <style>:root{--md-text-font:"Roboto";--md-code-font:"Roboto Mono"}</style>
-      
-    
-    
-      <link rel="stylesheet" href="../css/extra.css">
-    
-    <script>__md_scope=new URL("..",location),__md_hash=e=>[...e].reduce((e,_)=>(e<<5)-e+_.charCodeAt(0),0),__md_get=(e,_=localStorage,t=__md_scope)=>JSON.parse(_.getItem(t.pathname+"."+e)),__md_set=(e,_,t=localStorage,a=__md_scope)=>{try{t.setItem(a.pathname+"."+e,JSON.stringify(_))}catch(e){}}</script>
-    
-      
-
-    
-    
-    
-  </head>
-  
-  
-    
-    
-      
-    
-    
-    
-    
-    <body dir="ltr" data-md-color-scheme="default" data-md-color-primary="deep-purple" data-md-color-accent="deep-purple">
-  
-    
-    <input class="md-toggle" data-md-toggle="drawer" type="checkbox" id="__drawer" autocomplete="off">
-    <input class="md-toggle" data-md-toggle="search" type="checkbox" id="__search" autocomplete="off">
-    <label class="md-overlay" for="__drawer"></label>
-    <div data-md-component="skip">
-      
-        
-        <a href="#utilities" class="md-skip">
-          Skip to content
-        </a>
-      
-    </div>
-    <div data-md-component="announce">
-      
-    </div>
-    
-    
-      
-
-  
-
-<header class="md-header md-header--shadow" data-md-component="header">
-  <nav class="md-header__inner md-grid" aria-label="Header">
-    <a href=".." title="Clikt" class="md-header__button md-logo" aria-label="Clikt" data-md-component="logo">
-      
-  <img src="../img/wordmark_small.svg" alt="logo">
-
-    </a>
-    <label class="md-header__button md-icon" for="__drawer">
-      
-      <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M3 6h18v2H3V6m0 5h18v2H3v-2m0 5h18v2H3v-2Z"/></svg>
-    </label>
-    <div class="md-header__title" data-md-component="header-title">
-      <div class="md-header__ellipsis">
-        <div class="md-header__topic">
-          <span class="md-ellipsis">
-            Clikt
-          </span>
-        </div>
-        <div class="md-header__topic" data-md-component="header-topic">
-          <span class="md-ellipsis">
-            
-              Launching Editors
-            
-          </span>
-        </div>
-      </div>
-    </div>
-    
-      
-        <form class="md-header__option" data-md-component="palette">
-  
-    
-    
-    
-    <input class="md-option" data-md-color-media="(prefers-color-scheme: light)" data-md-color-scheme="default" data-md-color-primary="deep-purple" data-md-color-accent="deep-purple"  aria-label="Switch to dark mode"  type="radio" name="__palette" id="__palette_0">
-    
-      <label class="md-header__button md-icon" title="Switch to dark mode" for="__palette_1" hidden>
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 6H7c-3.31 0-6 2.69-6 6s2.69 6 6 6h10c3.31 0 6-2.69 6-6s-2.69-6-6-6zm0 10H7c-2.21 0-4-1.79-4-4s1.79-4 4-4h10c2.21 0 4 1.79 4 4s-1.79 4-4 4zM7 9c-1.66 0-3 1.34-3 3s1.34 3 3 3 3-1.34 3-3-1.34-3-3-3z"/></svg>
-      </label>
-    
-  
-    
-    
-    
-    <input class="md-option" data-md-color-media="(prefers-color-scheme: dark)" data-md-color-scheme="slate" data-md-color-primary="deep-purple" data-md-color-accent="deep-orange"  aria-label="Switch to light mode"  type="radio" name="__palette" id="__palette_1">
-    
-      <label class="md-header__button md-icon" title="Switch to light mode" for="__palette_0" hidden>
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M17 7H7a5 5 0 0 0-5 5 5 5 0 0 0 5 5h10a5 5 0 0 0 5-5 5 5 0 0 0-5-5m0 8a3 3 0 0 1-3-3 3 3 0 0 1 3-3 3 3 0 0 1 3 3 3 3 0 0 1-3 3Z"/></svg>
-      </label>
-    
-  
-</form>
-      
-    
-    
-      <script>var media,input,key,value,palette=__md_get("__palette");if(palette&&palette.color){"(prefers-color-scheme)"===palette.color.media&&(media=matchMedia("(prefers-color-scheme: light)"),input=document.querySelector(media.matches?"[data-md-color-media='(prefers-color-scheme: light)']":"[data-md-color-media='(prefers-color-scheme: dark)']"),palette.color.media=input.getAttribute("data-md-color-media"),palette.color.scheme=input.getAttribute("data-md-color-scheme"),palette.color.primary=input.getAttribute("data-md-color-primary"),palette.color.accent=input.getAttribute("data-md-color-accent"));for([key,value]of Object.entries(palette.color))document.body.setAttribute("data-md-color-"+key,value)}</script>
-    
-    
-    
-      <label class="md-header__button md-icon" for="__search">
-        
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
-      </label>
-      <div class="md-search" data-md-component="search" role="dialog">
-  <label class="md-search__overlay" for="__search"></label>
-  <div class="md-search__inner" role="search">
-    <form class="md-search__form" name="search">
-      <input type="text" class="md-search__input" name="query" aria-label="Search" placeholder="Search" autocapitalize="off" autocorrect="off" autocomplete="off" spellcheck="false" data-md-component="search-query" required>
-      <label class="md-search__icon md-icon" for="__search">
-        
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M9.5 3A6.5 6.5 0 0 1 16 9.5c0 1.61-.59 3.09-1.56 4.23l.27.27h.79l5 5-1.5 1.5-5-5v-.79l-.27-.27A6.516 6.516 0 0 1 9.5 16 6.5 6.5 0 0 1 3 9.5 6.5 6.5 0 0 1 9.5 3m0 2C7 5 5 7 5 9.5S7 14 9.5 14 14 12 14 9.5 12 5 9.5 5Z"/></svg>
-        
-        <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M20 11v2H8l5.5 5.5-1.42 1.42L4.16 12l7.92-7.92L13.5 5.5 8 11h12Z"/></svg>
-      </label>
-      <nav class="md-search__options" aria-label="Search">
-        
-        <button type="reset" class="md-search__icon md-icon" title="Clear" aria-label="Clear" tabindex="-1">
-          
-          <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M19 6.41 17.59 5 12 10.59 6.41 5 5 6.41 10.59 12 5 17.59 6.41 19 12 13.41 17.59 19 19 17.59 13.41 12 19 6.41Z"/></svg>
-        </button>
-      </nav>
-      
-    </form>
-    <div class="md-search__output">
-      <div class="md-search__scrollwrap" data-md-scrollfix>
-        <div class="md-search-result" data-md-component="search-result">
-          <div class="md-search-result__meta">
-            Initializing search
-          </div>
-          <ol class="md-search-result__list" role="presentation"></ol>
-        </div>
-      </div>
-    </div>
-  </div>
-</div>
-    
-    
-      <div class="md-header__source">
-        <a href="https://github.com/ajalt/clikt" title="Go to repository" class="md-source" data-md-component="source">
-  <div class="md-source__icon md-icon">
-    
-    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
-  </div>
-  <div class="md-source__repository">
-    Clikt
-  </div>
-</a>
-      </div>
-    
-  </nav>
-  
-</header>
-    
-    <div class="md-container" data-md-component="container">
-      
-      
-        
-          
-        
-      
-      <main class="md-main" data-md-component="main">
-        <div class="md-main__inner md-grid">
-          
-            
-              
-              <div class="md-sidebar md-sidebar--primary" data-md-component="sidebar" data-md-type="navigation" >
-                <div class="md-sidebar__scrollwrap">
-                  <div class="md-sidebar__inner">
-                    
-
-
-
-<nav class="md-nav md-nav--primary" aria-label="Navigation" data-md-level="0">
-  <label class="md-nav__title" for="__drawer">
-    <a href=".." title="Clikt" class="md-nav__button md-logo" aria-label="Clikt" data-md-component="logo">
-      
-  <img src="../img/wordmark_small.svg" alt="logo">
-
-    </a>
-    Clikt
-  </label>
-  
-    <div class="md-nav__source">
-      <a href="https://github.com/ajalt/clikt" title="Go to repository" class="md-source" data-md-component="source">
-  <div class="md-source__icon md-icon">
-    
-    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 496 512"><!--! Font Awesome Free 6.5.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2023 Fonticons, Inc.--><path d="M165.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6zm-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3zm44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9zM244.8 8C106.1 8 0 113.3 0 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C428.2 457.8 496 362.9 496 252 496 113.3 383.5 8 244.8 8zM97.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1zm-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7zm32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1zm-11.4-14.7c-1.6 1-1.6 3.6 0 5.9 1.6 2.3 4.3 3.3 5.6 2.3 1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2z"/></svg>
-  </div>
-  <div class="md-source__repository">
-    Clikt
-  </div>
-</a>
-    </div>
-  
-  <ul class="md-nav__list" data-md-scrollfix>
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_1" >
-        
-          
-          <label class="md-nav__link" for="__nav_1" id="__nav_1_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Quickstart
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_1_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_1">
-            <span class="md-nav__icon md-icon"></span>
-            Quickstart
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../quickstart/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Basic Concepts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../quickstart/#printing-to-stdout-and-stderr" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Printing to Stdout and Stderr
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../quickstart/#nesting-commands" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Nesting Commands
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../quickstart/#adding-parameters" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Adding Parameters
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../quickstart/#developing-command-line-applications-with-gradle" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Developing Command Line Applications With Gradle
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_2" >
-        
-          
-          <label class="md-nav__link" for="__nav_2" id="__nav_2_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Why Clikt?
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_2_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_2">
-            <span class="md-nav__icon md-icon"></span>
-            Why Clikt?
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../whyclikt/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Why not a Kotlin library like kotlin-argparser or kotlinx.cli?
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../whyclikt/#why-not-a-java-library-like-jcommander" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Why not a Java library like JCommander?
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_3" >
-        
-          
-          <label class="md-nav__link" for="__nav_3" id="__nav_3_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Parameters
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_3_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_3">
-            <span class="md-nav__icon md-icon"></span>
-            Parameters
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../parameters/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Differences
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../parameters/#parameter-names" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Parameter Names
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../parameters/#parameter-types" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Parameter Types
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../parameters/#built-in-types" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Built-In Types
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../parameters/#custom-types" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Custom Types
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../parameters/#parameter-validation" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Parameter Validation
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_4" >
-        
-          
-          <label class="md-nav__link" for="__nav_4" id="__nav_4_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Options
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_4_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_4">
-            <span class="md-nav__icon md-icon"></span>
-            Options
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Basic Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#option-names" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Option Names
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#customizing-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Customizing Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#multi-value-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Multi Value Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#multiple-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Multiple Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#key-value-and-map-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Key-Value and Map Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#boolean-flag-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Boolean Flag Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#counted-flag-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Counted Flag Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#feature-switch-flags" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Feature Switch Flags
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#choice-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Choice Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#mutually-exclusive-option-groups" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Mutually Exclusive Option Groups
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#co-occurring-option-groups" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Co-Occurring Option Groups
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#choice-and-switch-options-with-groups" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Choice and Switch Options With Groups
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#number-options-without-a-name" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Number Options Without a Name
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#prompting-for-input" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Prompting For Input
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#password-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Password Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#eager-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Eager Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#deprecating-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Deprecating Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#unknown-options" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Unknown Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#values-from-environment-variables" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Values From Environment Variables
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#values-from-configuration-files" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Values from Configuration Files
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#windows-and-java-style-option-prefixes" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Windows and Java-Style Option Prefixes
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../options/#option-transformation-order" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Option Transformation Order
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_5" >
-        
-          
-          <label class="md-nav__link" for="__nav_5" id="__nav_5_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Arguments
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_5_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_5">
-            <span class="md-nav__icon md-icon"></span>
-            Arguments
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../arguments/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Basic Arguments
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../arguments/#variadic-arguments" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Variadic Arguments
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../arguments/#option-like-arguments-using-" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Option-Like Arguments ("--")
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_6" >
-        
-          
-          <label class="md-nav__link" for="__nav_6" id="__nav_6_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Commands
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_6_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_6">
-            <span class="md-nav__icon md-icon"></span>
-            Commands
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Executing Nested Commands
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#customizing-command-name" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Customizing Command Name
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#passing-parameters" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Passing Parameters
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#nested-handling-and-contexts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Nested Handling And Contexts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#running-parent-command-without-children" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Running Parent Command Without Children
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#customizing-contexts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Customizing Contexts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#printing-the-help-message-when-no-arguments-are-given" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Printing the Help Message When No Arguments Are Given
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#warnings-and-other-messages" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Warnings and Other Messages
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../commands/#chaining-and-repeating-subcommands" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Chaining and Repeating Subcommands
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_7" >
-        
-          
-          <label class="md-nav__link" for="__nav_7" id="__nav_7_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Documenting Scripts
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_7_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_7">
-            <span class="md-nav__icon md-icon"></span>
-            Documenting Scripts
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Help Texts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#preformatting-paragraphs" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Preformatting Paragraphs
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#manual-line-breaks" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Manual Line Breaks
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#subcommand-short-help" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Subcommand Short Help
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#help-option-customization" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Help Option Customization
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#default-values-in-help" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Default Values in Help
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#required-options-in-help" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Required Options in Help
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#grouping-options-in-help" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Grouping Options in Help
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#suggesting-corrections-for-mistyped-parameters" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Suggesting Corrections for Mistyped Parameters
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../documenting/#localization" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Localization
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_8" >
-        
-          
-          <label class="md-nav__link" for="__nav_8" id="__nav_8_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Advanced Patterns
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_8_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_8">
-            <span class="md-nav__icon md-icon"></span>
-            Advanced Patterns
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Common Options With Subcommands
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#command-aliases" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Command Aliases
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#token-normalization" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Token Normalization
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#replacing-stdin-and-stdout" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Replacing stdin and stdout
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#command-line-argument-files-files" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Argument Files ("@-files")
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#managing-shared-resources" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Managing Shared Resources
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#custom-exit-status-codes" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Custom exit status codes
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#custom-run-function-signature" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Custom run function signature
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#custom-run-behavior" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Custom run behavior
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../advanced/#multiplatform-support" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Multiplatform Support
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_9" >
-        
-          
-          <label class="md-nav__link" for="__nav_9" id="__nav_9_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Testing
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_9_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_9">
-            <span class="md-nav__icon md-icon"></span>
-            Testing
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../testing/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Testing Your Commands
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../testing/#testing-environment-variables" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Testing Environment Variables
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../testing/#custom-testing" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Custom Testing
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-    
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--active md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_10" checked>
-        
-          
-          <label class="md-nav__link" for="__nav_10" id="__nav_10_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Utilities
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="true">
-          <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-    
-  
-  
-  
-    <li class="md-nav__item md-nav__item--active">
-      
-      <input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
-      
-      
-        
-      
-      
-        <label class="md-nav__link md-nav__link--active" for="__toc">
-          
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-          <span class="md-nav__icon md-icon"></span>
-        </label>
-      
-      <a href="./" class="md-nav__link md-nav__link--active">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-      
-        
-
-<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
-  
-  
-  
-    
-  
-  
-    <label class="md-nav__title" for="__toc">
-      <span class="md-nav__icon md-icon"></span>
-      Table of contents
-    </label>
-    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
-      
-        <li class="md-nav__item">
-  <a href="#launching-editors" class="md-nav__link">
-    <span class="md-ellipsis">
-      Launching Editors
-    </span>
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#input-prompts" class="md-nav__link">
-    <span class="md-ellipsis">
-      Input Prompts
-    </span>
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#confirmation-prompts" class="md-nav__link">
-    <span class="md-ellipsis">
-      Confirmation Prompts
-    </span>
-  </a>
-  
-</li>
-      
-    </ul>
-  
-</nav>
-      
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
-            <span class="md-nav__icon md-icon"></span>
-            Shell Completion
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../autocomplete/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Supported Functionality
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../autocomplete/#enabling-completion" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Enabling Completion
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../autocomplete/#customizing-completions" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Customizing Completions
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../autocomplete/#limitations" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Limitations
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
-        
-          
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Exception Handling
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
-            <span class="md-nav__icon md-icon"></span>
-            Exception Handling
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../exceptions/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Where are Exceptions Handled?
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../exceptions/#handling-exceptions-manually" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Handling Exceptions Manually
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../exceptions/#which-exceptions-exist" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Which Exceptions Exist?
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
-        
-          
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    API reference
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
-            <span class="md-nav__icon md-icon"></span>
-            API reference
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../api/clikt/com.github.ajalt.clikt.core/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Commands and Exceptions
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../api/clikt/com.github.ajalt.clikt.parameters.options/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Options
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../api/clikt/com.github.ajalt.clikt.parameters.arguments/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Arguments
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../api/clikt/com.github.ajalt.clikt.parameters.types/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Parameter Type Conversions
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../api/clikt/com.github.ajalt.clikt.output/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Output Formatting
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../api/clikt/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    All Modules
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
-        
-          
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Releases
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
-            <span class="md-nav__icon md-icon"></span>
-            Releases
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../changelog/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Change Log
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../migration/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Upgrading to Newer Releases
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-  </ul>
-</nav>
-                  </div>
-                </div>
-              </div>
-            
-            
-              
-              <div class="md-sidebar md-sidebar--secondary" data-md-component="sidebar" data-md-type="toc" >
-                <div class="md-sidebar__scrollwrap">
-                  <div class="md-sidebar__inner">
-                    
-
-<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
-  
-  
-  
-    
-  
-  
-    <label class="md-nav__title" for="__toc">
-      <span class="md-nav__icon md-icon"></span>
-      Table of contents
-    </label>
-    <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
-      
-        <li class="md-nav__item">
-  <a href="#launching-editors" class="md-nav__link">
-    <span class="md-ellipsis">
-      Launching Editors
-    </span>
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#input-prompts" class="md-nav__link">
-    <span class="md-ellipsis">
-      Input Prompts
-    </span>
-  </a>
-  
-</li>
-      
-        <li class="md-nav__item">
-  <a href="#confirmation-prompts" class="md-nav__link">
-    <span class="md-ellipsis">
-      Confirmation Prompts
-    </span>
-  </a>
-  
-</li>
-      
-    </ul>
-  
-</nav>
-                  </div>
-                </div>
-              </div>
-            
-          
-          
-            <div class="md-content" data-md-component="content">
-              <article class="md-content__inner md-typeset">
-                
-                  
-
-  
-  
-
-
-<h1 id="utilities">Utilities<a class="headerlink" href="#utilities" title="Permanent link">&para;</a></h1>
-<p>Writing command line interfaces often involves more than just parsing
-the command line. Clikt also provides functions to perform actions
-commonly used in command line programs.</p>
-<h2 id="launching-editors">Launching Editors<a class="headerlink" href="#launching-editors" title="Permanent link">&para;</a></h2>
-<p>If you need to ask users for multi-line input, or need to have the user edit a file, you can do so
-through <a href="../api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-text.html"><code>editText</code></a> and <a href="../api/clikt/com.github.ajalt.clikt.output/-term-ui/edit-file.html"><code>editFile</code></a>. These functions open the
-program defined in the <code>VISUAL</code> or <code>EDITOR</code> environment variables, or a sensible default if neither
-are defined. The functions return the edited text if the user saved their changes.</p>
-<div class="tabbed-set tabbed-alternate" data-tabs="1:1"><input checked="checked" id="__tabbed_1_1" name="__tabbed_1" type="radio" /><div class="tabbed-labels"><label for="__tabbed_1_1">Example</label></div>
-<div class="tabbed-content">
-<div class="tabbed-block">
-<div class="highlight"><pre><span></span><code><span class="kd">fun</span><span class="w"> </span><span class="nf">getCommitMessage</span><span class="p">():</span><span class="w"> </span><span class="kt">String?</span><span class="w"> </span><span class="p">{</span>
-<span class="w">    </span><span class="kd">val</span><span class="w"> </span><span class="nv">message</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="s">&quot;&quot;&quot;</span>
-<span class="s">    # Enter your message.</span>
-<span class="s">    # Lines starting with # are ignored</span>
-<span class="s">    &quot;&quot;&quot;</span><span class="p">.</span><span class="na">trimIndent</span><span class="p">()</span>
-<span class="w">    </span><span class="k">return</span><span class="w"> </span><span class="n">editText</span><span class="p">(</span><span class="n">message</span><span class="p">,</span><span class="w"> </span><span class="n">requireSave</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span>
-<span class="w">            </span><span class="o">?.</span><span class="na">replace</span><span class="p">(</span><span class="n">Regex</span><span class="p">(</span><span class="s">&quot;#[^\n]*\n&quot;</span><span class="p">),</span><span class="w"> </span><span class="s">&quot;&quot;</span><span class="p">)</span>
-<span class="p">}</span>
-</code></pre></div>
-</div>
-</div>
-</div>
-<h2 id="input-prompts">Input Prompts<a class="headerlink" href="#input-prompts" title="Permanent link">&para;</a></h2>
-<p>Options can <a href="../options/#prompting-for-input">prompt for values automatically</a>, but you can also do so manually
-by using Mordant&rsquo;s prompt functionality directly. By default, it accepts any input string, but you
-can also pass in a conversion function. If the conversion returns a <code>ConversionResult.Invalid</code>, the
-prompt will ask the user to enter a different value.</p>
-<div class="tabbed-set tabbed-alternate" data-tabs="2:2"><input checked="checked" id="__tabbed_2_1" name="__tabbed_2" type="radio" /><input id="__tabbed_2_2" name="__tabbed_2" type="radio" /><div class="tabbed-labels"><label for="__tabbed_2_1">Example</label><label for="__tabbed_2_2">Interactive Session</label></div>
-<div class="tabbed-content">
-<div class="tabbed-block">
-<div class="highlight"><pre><span></span><code><span class="kd">val</span><span class="w"> </span><span class="nv">input</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="n">terminal</span><span class="p">.</span><span class="na">prompt</span><span class="p">(</span><span class="s">&quot;Enter a number&quot;</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
-<span class="w">    </span><span class="nb">it</span><span class="p">.</span><span class="na">toIntOrNull</span><span class="p">()</span>
-<span class="w">        </span><span class="o">?.</span><span class="na">let</span><span class="w"> </span><span class="p">{</span><span class="w"> </span><span class="n">ConversionResult</span><span class="p">.</span><span class="na">Valid</span><span class="p">(</span><span class="nb">it</span><span class="p">)</span><span class="w"> </span><span class="p">}</span>
-<span class="w">        </span><span class="o">?:</span><span class="w"> </span><span class="n">ConversionResult</span><span class="p">.</span><span class="na">Invalid</span><span class="p">(</span><span class="s">&quot;</span><span class="si">$</span><span class="n">it</span><span class="s"> is not a valid integer&quot;</span><span class="p">)</span>
-<span class="p">}</span>
-<span class="n">echo</span><span class="p">(</span><span class="s">&quot;Twice your number is </span><span class="si">${</span><span class="n">input</span><span class="w"> </span><span class="o">*</span><span class="w"> </span><span class="m">2</span><span class="si">}</span><span class="s">&quot;</span><span class="p">)</span>
-</code></pre></div>
-</div>
-<div class="tabbed-block">
-<div class="highlight"><pre><span></span><code>Enter a number: foo
-Error: foo is not a valid integer
-Enter a number: 11
-Twice your number is 22
-</code></pre></div>
-</div>
-</div>
-</div>
-<h2 id="confirmation-prompts">Confirmation Prompts<a class="headerlink" href="#confirmation-prompts" title="Permanent link">&para;</a></h2>
-<p>You can also ask the user for a yes or no response with Mordant&rsquo;s <a href="https://ajalt.github.io/mordant/api/mordant/com.github.ajalt.mordant.terminal/-yes-no-prompt/index.html"><code>YesNoPrompt</code></a>:</p>
-<div class="highlight"><pre><span></span><code><span class="k">if</span><span class="w"> </span><span class="p">(</span><span class="n">YesNoPrompt</span><span class="p">(</span><span class="s">&quot;Continue?&quot;</span><span class="p">,</span><span class="w"> </span><span class="n">terminal</span><span class="p">).</span><span class="na">ask</span><span class="p">()</span><span class="w"> </span><span class="o">==</span><span class="w"> </span><span class="kc">true</span><span class="p">)</span><span class="w"> </span><span class="p">{</span>
-<span class="w">    </span><span class="n">echo</span><span class="p">(</span><span class="s">&quot;Ok!&quot;</span><span class="p">)</span>
-<span class="p">}</span>
-</code></pre></div>
-
-
-
-
-
-
-
-
-
-
-
-
-                
-              </article>
-            </div>
-          
-          
-<script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script>
-        </div>
-        
-      </main>
-      
-        <footer class="md-footer">
-  
-  <div class="md-footer-meta md-typeset">
-    <div class="md-footer-meta__inner md-grid">
-      <div class="md-copyright">
-  
-    <div class="md-copyright__highlight">
-      Copyright &copy; 2018 AJ Alt
-    </div>
-  
-  
-    Made with
-    <a href="https://squidfunk.github.io/mkdocs-material/" target="_blank" rel="noopener">
-      Material for MkDocs
-    </a>
-  
-</div>
-      
-    </div>
-  </div>
-</footer>
-      
-    </div>
-    <div class="md-dialog" data-md-component="dialog">
-      <div class="md-dialog__inner md-typeset"></div>
-    </div>
-    
-    
-    <script id="__config" type="application/json">{"base": "..", "features": [], "search": "../assets/javascripts/workers/search.b8dbb3d2.min.js", "translations": {"clipboard.copied": "Copied to clipboard", "clipboard.copy": "Copy to clipboard", "search.result.more.one": "1 more on this page", "search.result.more.other": "# more on this page", "search.result.none": "No matching documents", "search.result.one": "1 matching document", "search.result.other": "# matching documents", "search.result.placeholder": "Type to start searching", "search.result.term.missing": "Missing", "select.version": "Select version"}}</script>
-    
-    
-      <script src="../assets/javascripts/bundle.c8d2eff1.min.js"></script>
-      
-    
-  </body>
-</html>
\ No newline at end of file
diff --git a/whyclikt/index.html b/whyclikt/index.html
index b6ab6831..b6d75796 100755
--- a/whyclikt/index.html
+++ b/whyclikt/index.html
@@ -2198,7 +2198,7 @@
             
   
   <span class="md-ellipsis">
-    Utilities
+    Shell Completion
   </span>
   
 
@@ -2207,111 +2207,6 @@
         
         <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_10_label" aria-expanded="false">
           <label class="md-nav__title" for="__nav_10">
-            <span class="md-nav__icon md-icon"></span>
-            Utilities
-          </label>
-          <ul class="md-nav__list" data-md-scrollfix>
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Launching Editors
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#input-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Input Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-              
-                
-  
-  
-  
-  
-    <li class="md-nav__item">
-      <a href="../utilities/#confirmation-prompts" class="md-nav__link">
-        
-  
-  <span class="md-ellipsis">
-    Confirmation Prompts
-  </span>
-  
-
-      </a>
-    </li>
-  
-
-              
-            
-          </ul>
-        </nav>
-      
-    </li>
-  
-
-    
-      
-      
-  
-  
-  
-  
-    
-    
-    
-    
-    <li class="md-nav__item md-nav__item--nested">
-      
-        
-        
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
-        
-          
-          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
-            
-  
-  <span class="md-ellipsis">
-    Shell Completion
-  </span>
-  
-
-            <span class="md-nav__icon md-icon"></span>
-          </label>
-        
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Shell Completion
           </label>
@@ -2422,10 +2317,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_11" >
         
           
-          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_11" id="__nav_11_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2436,8 +2331,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_12">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_11_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_11">
             <span class="md-nav__icon md-icon"></span>
             Exception Handling
           </label>
@@ -2527,10 +2422,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_12" >
         
           
-          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_12" id="__nav_12_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2541,8 +2436,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_13">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_12_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_12">
             <span class="md-nav__icon md-icon"></span>
             API reference
           </label>
@@ -2695,10 +2590,10 @@
       
         
         
-        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_14" >
+        <input class="md-nav__toggle md-toggle " type="checkbox" id="__nav_13" >
         
           
-          <label class="md-nav__link" for="__nav_14" id="__nav_14_label" tabindex="0">
+          <label class="md-nav__link" for="__nav_13" id="__nav_13_label" tabindex="0">
             
   
   <span class="md-ellipsis">
@@ -2709,8 +2604,8 @@
             <span class="md-nav__icon md-icon"></span>
           </label>
         
-        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_14_label" aria-expanded="false">
-          <label class="md-nav__title" for="__nav_14">
+        <nav class="md-nav" data-md-level="1" aria-labelledby="__nav_13_label" aria-expanded="false">
+          <label class="md-nav__title" for="__nav_13">
             <span class="md-nav__icon md-icon"></span>
             Releases
           </label>