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