PyCmd Tutorial: Build Powerful Command Line Apps Fast Command Line Interfaces (CLIs) are the backbone of developer tooling, automation scripts, and system administration. While Python offers built-in options like sys.argv and argparse, they often require extensive boilerplate code to handle complex command structures, input validation, and formatting.
Enter PyCmd—a lightweight, highly efficient Python library designed to help you build robust, interactive, and beautiful CLI applications with minimal code. In this tutorial, you will learn how to set up PyCmd, define commands, handle user inputs, and build a fully functional CLI app from scratch. Why Choose PyCmd?
When building CLI tools, developers often choose between simplicity and power. PyCmd bridges this gap by offering:
Declarative Syntax: Define commands and arguments using intuitive decorators.
Auto-Generated Help Menus: Standardized, readable –help screens without extra coding.
Type Safety: Automatic parsing and validation of inputs into Python data types.
Interactive Prompts: Built-in support for user confirmations, secret passwords, and selection menus. Getting Started Installation
First, ensure you have Python 3.7+ installed. Install PyCmd via pip: pip install pycmd-cli Use code with caution. Your First “Hello World” App
Let’s create a basic script to see PyCmd in action. Create a file named app.py:
from pycmd import CLI app = CLI(name=“MyFirstCLI”, description=“A simple greet application.”) @app.command() def greet(name: str, uppercase: bool = False): “”“Greet a user by their name.”“” message = f”Hello, {name}!” if uppercase: message = message.upper() print(message) if name == “main”: app.run() Use code with caution. Running the App
PyCmd automatically parses standard terminal inputs. Run your script using the following commands:
# View the auto-generated help menu python app.py –help # Run the command with arguments python app.py greet “Alice” # Output: Hello, Alice! # Use the optional boolean flag python app.py greet “Alice” –uppercase # Output: HELLO, ALICE! Use code with caution. Advanced Features: Building a Task Manager
To explore the true power of PyCmd, let’s build a multi-command Todo application. This app will feature nested subcommands, type validation, and interactive user prompts. 1. Initializing the Application Structure
Create a file named todo.py and set up the base CLI configuration:
from pycmd import CLI, prompt import json import os app = CLI(name=“todo”, description=“An advanced CLI Task Manager.”) DB_FILE = “tasks.json” def load_tasks(): if not os.path.exists(DB_FILE): return [] with open(DB_FILE, “r”) as f: return json.load(f) def save_tasks(tasks): with open(DB_FILE, “w”) as f: json.dump(tasks, f, indent=4) Use code with caution. 2. Adding Arguments and Validations
Let’s add a command to insert new tasks. PyCmd utilizes Python type hinting to enforce validation automatically.
@app.command(name=“add”) def add_task(title: str, priority: int = 2): “”“Add a new task to your todo list. Priority ranges from 1 (High) to 3 (Low).”“” if priority not in [1, 2, 3]: print(“Error: Priority must be 1, 2, or 3.”) return tasks = load_tasks() tasks.append({“id”: len(tasks) + 1, “title”: title, “priority”: priority, “done”: False}) save_tasks(tasks) print(f”Task ‘{title}’ added successfully!“) Use code with caution. 3. Listing Data with Clean Formatting Next, create a command to display the tasks.
@app.command(name=“list”) def list_tasks(all: bool = False): “”“List pending tasks. Use –all to see completed tasks.”“” tasks = load_tasks() filtered_tasks = tasks if all else [t for t in tasks if not t[“done”]] if not filtered_tasks: print(“No tasks found.”) return print(f”{‘ID’:<5} {'Task Title':<30} {'Priority':<10} {'Status':<10}") print("-"60) for t in filtered_tasks: status = "✅ Done" if t["done"] else "⏳ Pending" print(f"{t['id']:<5} {t['title']:<30} {t['priority']:<10} {status:<10}") Use code with caution. 4. Implementing Interactive Prompts
Sometimes you want to safeguard destructive actions (like deletions) or request input during execution instead of requiring command-line flags. PyCmd’s prompt utility handles this seamlessly.
@app.command(name=“complete”) def complete_task(task_id: int): “”“Mark a specific task as completed.”“” tasks = load_tasks() for t in tasks: if t[“id”] == task_id: t[“done”] = True save_tasks(tasks) print(f”Task {task_id} marked as complete!“) return print(f”Task ID {task_id} not found.“) @app.command(name=“clear”) def clear_all(): “”“Delete all tasks from the tracker.”“” # PyCmd built-in confirmation prompt if prompt.confirm(“Are you sure you want to delete ALL tasks?”, default=False): save_tasks([]) print(“All tasks cleared.”) else: print(“Operation cancelled.”) Use code with caution. Testing Your Advanced App
Your command line tool is now ready. Try out the execution flow in your terminal:
# Add tasks python todo.py add “Buy groceries” –priority 1 python todo.py add “Write PyCmd tutorial” –priority 2 # List pending tasks python todo.py list # Complete a task python todo.py complete 1 # View all tasks including completed ones python todo.py list –all # Destructive action with confirmation prompt python todo.py clear Use code with caution. Best Practices for PyCmd Applications
Leverage Docstrings: PyCmd uses your function docstrings to generate description texts for the –help flag. Keep them clear and concise.
Handle Errors Gracefully: Use standard Python try-except blocks within your functions to catch unexpected environment bugs (like missing files or network timeouts) to prevent unseemly stack traces.
Use Environment Variables: For sensitive data like API keys, combine PyCmd with packages like python-dotenv rather than passing secrets directly into terminal commands where they can be saved in shell history. Conclusion
PyCmd cuts out the boilerplate code of traditional Python command-line parsers, giving you a powerful, developer-friendly framework to deploy CLI utilities in minutes. By leveraging type hints, automated help generation, and interactive prompts, you can keep your focus where it belongs: writing the core logic of your application. If you’d like to expand this app further,g., todo tags add) Bundle your script into a distributable pip package
Leave a Reply