1Knack 2===== 3 4.. image:: https://img.shields.io/pypi/v/knack.svg 5 :target: https://pypi.python.org/pypi/knack 6 7.. image:: https://img.shields.io/pypi/pyversions/knack.svg 8 :target: https://pypi.python.org/pypi/knack 9 10.. image:: https://dev.azure.com/azure-sdk/public/_apis/build/status/cli/microsoft.knack?branchName=dev 11 :target: https://dev.azure.com/azure-sdk/public/_build/latest?definitionId=1643&branchName=dev 12 13 14------------ 15 16 17:: 18 19 _ _ 20 | | ___ __ __ _ ___| | __ 21 | |/ / '_ \ / _` |/ __| |/ / 22 | <| | | | (_| | (__| < 23 |_|\_\_| |_|\__,_|\___|_|\_\ 24 25 26**A Command-Line Interface framework** 27 28Installation is easy via pip: 29 30.. code-block:: bash 31 32 pip install knack 33 34Knack can be installed as a non-privileged user to your home directory by adding "--user" as below: 35 36.. code-block:: bash 37 38 pip install knack --user 39 40------------ 41 42.. note:: The project is in `initial development phase <https://semver.org/#how-should-i-deal-with-revisions-in-the-0yz-initial-development-phase>`__. We recommend pinning to at least a specific minor version when marking **knack** as a dependency in your project. 43 44------------ 45 46 47Usage 48===== 49 50 51.. code-block:: python 52 53 import sys 54 from collections import OrderedDict 55 56 from knack import CLI, ArgumentsContext, CLICommandsLoader 57 from knack.commands import CommandGroup 58 59 60 def abc_str(length=3): 61 import string 62 return string.ascii_lowercase[:length] 63 64 65 class MyCommandsLoader(CLICommandsLoader): 66 def load_command_table(self, args): 67 with CommandGroup(self, 'abc', '__main__#{}') as g: 68 g.command('str', 'abc_str') 69 return OrderedDict(self.command_table) 70 71 def load_arguments(self, command): 72 with ArgumentsContext(self, 'abc str') as ac: 73 ac.argument('length', type=int) 74 super(MyCommandsLoader, self).load_arguments(command) 75 76 77 mycli = CLI(cli_name='mycli', commands_loader_cls=MyCommandsLoader) 78 exit_code = mycli.invoke(sys.argv[1:]) 79 sys.exit(exit_code) 80 81 # $ python mycli.py abc str 82 # "abc" 83 84 # $ python mycli.py abc str --length 5 85 # "abcde" 86 87 # $ python mycli.py abc str --length 100 88 # "abcdefghijklmnopqrstuvwxyz" 89 90 91More samples and snippets are available at `examples <https://github.com/Microsoft/knack/tree/dev/examples>`__. 92 93 94Documentation 95============= 96 97Documentation is available at `docs <https://github.com/Microsoft/knack/tree/dev/docs>`__. 98 99Developer Setup 100=============== 101 102In a virtual environment, install the `requirements.txt` file. 103 104.. code-block:: bash 105 106 pip install -r requirements.txt 107 pip install -e . 108 109Run Automation 110============== 111 112This project supports running automation using `tox <https://tox.readthedocs.io/en/latest/>`__. 113 114.. code-block:: bash 115 116 pip install tox 117 tox 118 119 120Real-world uses 121=============== 122 123- `Azure CLI <https://github.com/Azure/azure-cli/>`__: The Azure CLI 2.0 is Azure's new command line experience for managing Azure resources. 124- `VSTS CLI <https://github.com/Microsoft/vsts-cli>`__: A command-line interface for Visual Studio Team Services (VSTS) and Team Foundation Server (TFS). With the VSTS CLI, you can manage and work with resources including pull requests, work items, builds, and more. 125- `Service Fabric CLI <https://github.com/Azure/service-fabric-cli>`__: A command-line interface for interacting with Azure Service Fabric clusters and their related entities. 126 127Do you use knack in your CLI as well? Open a pull request to include it here. We would love to have it in our list. 128 129 130Release History 131=============== 132 133See `GitHub Releases <https://github.com/Microsoft/knack/releases>`__. 134 135 136Contribute Code 137=============== 138 139This project has adopted the `Microsoft Open Source Code of Conduct <https://opensource.microsoft.com/codeofconduct/>`__. 140 141For more information see the `Code of Conduct FAQ <https://opensource.microsoft.com/codeofconduct/faq/>`__ or contact `opencode@microsoft.com <mailto:opencode@microsoft.com>`__ with any additional questions or comments. 142 143If you would like to become an active contributor to this project, please 144follow the instructions provided in `Contribution License Agreement <https://cla.microsoft.com/>`__. 145 146 147License 148======= 149 150Knack is licensed under `MIT <LICENSE>`__. 151