There is an optional utility tool called **Typer CLI**, additional to **Typer** itself.
It's main feature is to provide ✨ completion ✨ in the Terminal for your own small programs built with **Typer**.
...without you having to create a complete installable Python package.
It's probably most useful if you have a small custom Python script using **Typer** (maybe as part of some project), for some small tasks, and it's not complex/important enough to create a whole installable Python package for it (something to be installed with `pip`).
In that case, you can install **Typer CLI**, and run your program with the `typer` command in your Terminal, and it will provide completion for your script.
You can also use **Typer CLI** to generate Markdown documentation for your own **Typer** programs 📝.
**Source Code for Typer CLI**: <ahref="https://github.com/tiangolo/typer-cli"target="_blank">https://github.com/tiangolo/typer-cli</a>
---
## **Typer** or **Typer CLI**
**Typer** is a library for building CLIs (Command Line Interface applications).
You use **Typer** in your Python scripts. Like in:
```Python
import typer
def main():
typer.echo("Hello World")
if __name__ == "__main__":
typer.run(main)
```
**Typer CLI** is a command line application to run simple programs created with **Typer**, with completion in your terminal 🚀.
You use **Typer CLI** in your terminal, to run your scripts (as an alternative to calling `python` directly). Like in:
<divclass="termy">
```console
$ typer my_script.py run
Hello World
```
</div>
But you never import anything from **Typer CLI** in your own scripts.
## Usage
### Install
Install **Typer CLI**:
<divclass="termy">
```console
$ python -m pip install typer-cli
---> 100%
Successfully installed typer-cli
```
</div>
That creates a `typer` command you can call in your terminal, much like `python`, `git`, or `echo`.
You can then install completion for it:
<divclass="termy">
```console
$ typer --install-completion
zsh completion installed in /home/user/.bashrc.
Completion will take effect once you restart the terminal.
```
</div>
### Sample script
Let's say you have a script that uses **Typer** in `my_custom_script.py`:
```Python
import typer
app = typer.Typer()
@app.command()
def hello(name: str = None):
if name:
typer.echo(f"Hello {name}")
else:
typer.echo("Hello World!")
@app.command()
def bye(name: str = None):
if name:
typer.echo(f"Bye {name}")
else:
typer.echo("Goodbye!")
if __name__ == "__main__":
app()
```
For it to work, you would also install **Typer**:
<divclass="termy">
```console
$ python -m pip install typer
---> 100%
Successfully installed typer
```
</div>
### Run with Python
Then you could run your script with normal Python:
<divclass="termy">
```console
$ python my_custom_script.py hello
Hello World!
$ python my_custom_script.py hello --name Camila
Hello Camila!
$ python my_custom_script.py bye --name Camila
Bye Camila
```
</div>
There's nothing wrong with using Python directly to run it. And, in fact, if some other code or program uses your script, that would probably be the best way to do it.
⛔️ But in your terminal, you won't get completion when hitting <kbd>TAB</kbd> for any of the subcommands or options, like `hello`, `bye`, and `--name`.
### Run with **Typer CLI**
Here's where **Typer CLI** is useful.
You can also run the same script with the `typer` command you get after installing `typer-cli`:
<divclass="termy">
```console
$ typer my_custom_script.py run hello
Hello World!
$ typer my_custom_script.py run hello --name Camila
Hello Camila!
$ typer my_custom_script.py run bye --name Camila
Bye Camila
```
</div>
* Instead of using `python` directly you use the `typer` command.
* After the name of the file, add the subcommand `run`.
✔️ If you installed completion for **Typer CLI** (for the `typer` command) as described above, when you hit <kbd>TAB</kbd> you will have ✨ completion for everything ✨, including all the subcommands and options of your script, like `hello`, `bye`, and `--name` 🚀.
## If main
Because **Typer CLI** won't use the block with:
```Python
if __name__ == "__main__":
app()
```
...you can also remove it if you are calling that script only with **Typer CLI** (using the `typer` command).
## Run other files
**Typer CLI** can run any script with **Typer**, but the script doesn't even have to use **Typer** at all.
**Typer CLI** could even run a file with a function that could be used with `typer.run()`, even if the script doesn't use `typer.run()` or anything else.
For example, a file `main.py` like this will still work:
```Python
def main(name: str = "World"):
"""
Say hi to someone, by default to the World.
"""
print(f"Hello {name}")
```
Then you can call it with:
<divclass="termy">
```console
$ typer main.py run --help
Usage: typer run [OPTIONS]
Say hi to someone, by default to the World.
Options:
--name TEXT
--help Show this message and exit.
$ typer main.py run --name Camila
Hello Camila
```
</div>
And it will also have completion for things like the `--name`*CLI Option*.
## Run a package or module
Instead of a file path you can pass a module (possibly in a package) to import.
