Quick Start

In this guide, we will look at two examples of creating a CLI application with Argenta:

• Simple example: a minimal application for quick introduction to the main components.

• Medium-complexity example: the Calculator app using and setting flags.

• More complex example: a full-featured “Task Manager” application with dependency injection and business logic.

Simple Example

Installation

pip install argenta

This example demonstrates the absolute minimum required to create and run an application. You can copy this code, run it, and immediately see the result.

from argenta import App, Command, Orchestrator, Router, Response
from argenta.command import Flag

# 1. Create app and orchestrator instances
app = App(
    prompt=">> ",
    initial_message="Simple App",
    farewell_message="Goodbye!",
    repeat_command_groups_printing=False,
)
orchestrator = Orchestrator()

# 2. Create router for grouping commands
main_router = Router(title="Main commands")


# 3. Define command and its handler
@main_router.command(Command("hello", description="Prints greeting message", flags=Flag("name")))
def hello_handler(response: Response):
    """This handler will be called for 'hello' command."""
    name = response.input_flags.get_flag_by_name("name")
    if name:
        print(f"Hello, {name.input_value}!")
    else:
        print("Hello, world!")


# 4. Include router to application
app.include_router(main_router)

# 5. Start application
if __name__ == "__main__":
    orchestrator.start_polling(app)

Running

Save the code to a file (for example, main.py) and run:

python main.py

Result

---

Intermediate Example: Calculator with Flags

Before moving to a complex example with DI, let’s consider an intermediate option — a calculator that uses flags to control behavior.

import operator
import re

from argenta import App, Orchestrator, Response, Router
from argenta.app import DynamicDividingLine
from argenta.command import Command, Flag, Flags
from argenta.response.status import ResponseStatus

router = Router("Calculator")

operations = {"mul": operator.mul, "sub": operator.sub, "add": operator.add}


@router.command(
    Command(
        "calc",
        description="Calculator with two numbers",
        flags=Flags(
            [
                Flag("a", possible_values=re.compile(r"^\d{,5}$")),  # First number
                Flag("b", possible_values=re.compile(r"^\d{,5}$")),  # Second number
                Flag(
                    "operation", possible_values=["add", "sub", "mul"]
                ),  # Operation: add, sub, mul
            ]
        ),
    )
)
def calc_handler(response: Response):
    # Get flag values
    a_flag = response.input_flags.get_flag_by_name("a")
    b_flag = response.input_flags.get_flag_by_name("b")
    op_flag = response.input_flags.get_flag_by_name("op")

    # Check that all flags are provided
    if response.status != ResponseStatus.ALL_FLAGS_VALID or not all([a_flag, b_flag, op_flag]):
        print("Error: must specify --a, --b and --op")
        return

    a = float(a_flag.input_value)
    b = float(b_flag.input_value)
    operation = op_flag.input_value

    try:
        result = operations[operation](a, b)
    except ZeroDivisionError:
        print("Can't divide by zero")
    else:
        print(f"Result: {result}")


app = App(
    initial_message="Calculator",
    repeat_command_groups_printing=False,
    prompt=">> ",
    dividing_line=DynamicDividingLine("~"),
)
orchestrator = Orchestrator()


def main():
    app.include_router(router)
    orchestrator.start_polling(app)


if __name__ == "__main__":
    main()

Running:

Save the code to a file calculator.py and run:

python calculator.py

Usage:

calc --a 10 --b 5 --operation add
calc --a 10 --b 5 --operation mul

This example shows how to work with flags without using DI. Now let’s move on to a more complex example.

---

Complex Example: Task Manager with DI

In this guide, we will create a full-featured CLI application “Task Manager” that will demonstrate working with dependency injection.

1. Installation

pip install argenta

2. Defining Data Models and Repository

First, let’s define data models for tasks and a repository to store them.

from dataclasses import dataclass
from typing import Literal

Priority = Literal["low", "medium", "high"]


@dataclass
class Task:
    description: str
    priority: Priority = "medium"


class TaskRepository:
    def __init__(self):
        self._tasks: list[Task] = []

    def add_task(self, task: Task):
        self._tasks.append(task)

    def get_all_tasks(self) -> list[Task]:
        return self._tasks

3. Creating a Provider for DI

To allow Argenta to inject TaskRepository into our handlers, we will create a provider for dishka.

from dishka import Provider, Scope, provide

from .repository import TaskRepository


class TaskProvider(Provider):
    @provide(scope=Scope.APP)
    def get_repository(self) -> TaskRepository:
        return TaskRepository()

4. Creating Command Handlers

Now let’s create handlers for the add-task and list-tasks commands. Notice how we use flags and inject TaskRepository.

from typing import cast

from argenta import Command, Response, Router
from argenta.command.flag import Flag, ValidationStatus
from argenta.command import Flags
from argenta.di import FromDishka

from .repository import Priority, Task, TaskRepository

router = Router(title="Task Manager")


@router.command(
    Command(
        "add-task",
        description="Add a new task",
        flags=Flags(
            [
                Flag("description"),
                Flag("priority", possible_values=["low", "medium", "high"]),
            ]
        ),
    )
)
def add_task(response: Response, repo: FromDishka[TaskRepository]):
    description_flag = response.input_flags.get_flag_by_name("description")

    if not description_flag or not description_flag.status == ValidationStatus.VALID:
        print("Error: --description flag is required.")
        return

    task_description = description_flag.input_value or ""

    priority_flag = response.input_flags.get_flag_by_name("priority")

    if priority_flag and priority_flag.status == ValidationStatus.VALID:
        priority_value = priority_flag.input_value
    else:
        priority_value = "medium"

    priority = cast(Priority, priority_value)

    task = Task(description=task_description, priority=priority)
    repo.add_task(task)

    print(f"Added task: '{task.description}' with priority '{task.priority}'")


@router.command(Command("list-tasks", description="List all tasks"))
def list_tasks(response: Response, repo: FromDishka[TaskRepository]):
    tasks = repo.get_all_tasks()

    if not tasks:
        print("No tasks found.")
        return

    print("Tasks:")
    for i, task in enumerate(tasks, 1):
        print(f"  {i}. {task.description} (Priority: {task.priority})")

5. Building and Running the Application

Finally, let’s put it all together: create an App instance, connect the router and provider, and then run the application.

from argenta import App, Orchestrator

from .handlers import router
from .provider import TaskProvider

# 1. Create app and orchestrator instances
app = App(
    initial_message="Task Manager",
    prompt="Enter a command: ",
)
orchestrator = Orchestrator(custom_providers=[TaskProvider()])

# 2. Include router with our commands
app.include_router(router)

# 3. Start polling via orchestrator
if __name__ == "__main__":
    orchestrator.start_polling(app)

6. Result

Now you can run main.py and interact with your new CLI application.