CLI Commands 🎛️¶
Master the Tatami command-line interface for rapid development.
Available Commands¶
Tatami provides several CLI commands to help you build and manage your applications.
tatami create¶
Create a new Tatami project with the standard structure.
Syntax:
tatami create <project_name>
Example:
tatami create my-blog-api
This creates a new directory my-blog-api with the standard Tatami project structure:
my-blog-api/
├── config.yaml # Main configuration
├── config-dev.yaml # Development config
├── README.md # Project documentation
├── favicon.ico # API favicon
├── routers/ # API endpoints
├── services/ # Business logic
├── middleware/ # Request processing
├── static/ # Static files
└── templates/ # HTML templates
tatami run¶
Run a Tatami application using the convention-based approach.
Syntax:
tatami run <project_path> [OPTIONS]
Options:
–host HOST - Host to bind to (default: localhost)
–port PORT - Port to bind to (default: 8000)
–mode MODE - Configuration mode (loads config-{mode}.yaml)
–verbose, -v - Increase verbosity (-v for info, -vv for debug)
Examples:
# Run with defaults
tatami run my-blog-api
# Run on all interfaces, port 8080
tatami run my-blog-api --host 0.0.0.0 --port 8080
# Run in development mode with verbose output
tatami run my-blog-api --mode dev --verbose
# Run with debug logging
tatami run my-blog-api -vv
What happens when you run:
🔧 Loads configuration from config.yaml (and config-{mode}.yaml if specified)
🔍 Auto-discovers routers in the routers/ directory
🧠 Auto-discovers services in the services/ directory
🔄 Loads middleware from the middleware/ directory
📁 Serves static files from static/ at /static
📄 Configures templates from the templates/ directory
🎨 Includes favicon (custom or default)
📚 Sets up automatic OpenAPI documentation
🚀 Starts the server with uvicorn
tatami doctor¶
Analyze your project structure and report potential issues.
Syntax:
tatami doctor <project_path>
Example:
tatami doctor my-blog-api
Sample Output:
🩺 Tatami is checking your project...
✔ Configuration file found: config.yaml
✔ Routers directory exists and contains 3 router(s)
✔ Services directory exists and contains 2 service(s)
✔ Static files directory configured
✔ Templates directory configured
⚠ No middleware found - consider adding authentication middleware
ℹ Consider adding a config-prod.yaml for production settings
✅ Your project looks good! Minor suggestions available.
What doctor checks:
✅ Configuration: Valid config files and structure
✅ Routers: Proper router definitions and naming
✅ Services: Service discovery and dependencies
✅ Structure: Correct directory organization
⚠️ Best Practices: Common patterns and recommendations
🔍 Performance: Potential optimization opportunities
Command Examples¶
Development Workflow¶
Typical development workflow using CLI commands:
# 1. Create new project
tatami create my-api
cd my-api
# 2. Check project health
tatami doctor .
# 3. Run in development mode
tatami run . --mode dev --verbose
# 4. Make changes to routers/services...
# 5. Check project again
tatami doctor .
# 6. Run with debug logging
tatami run . --mode dev -vv
Production Deployment¶
Prepare for production deployment:
# Check project is production-ready
tatami doctor my-api
# Run in production mode (using config.yaml)
tatami run my-api --host 0.0.0.0 --port 8000
Quick Prototyping¶
Rapid development cycle:
# Create and run immediately
tatami create quick-prototype
cd quick-prototype
tatami run . --mode dev &
# Open API docs
open http://localhost:8000/docs/swagger
Configuration Modes¶
The –mode flag loads additional configuration:
Default (no mode): - Loads config.yaml
Development mode (`–mode dev`): - Loads config.yaml - Overlays config-dev.yaml
Production mode (`–mode prod`): - Loads config.yaml - Overlays config-prod.yaml
Custom mode (`–mode staging`): - Loads config.yaml - Overlays config-staging.yaml
Example configuration files:
# config.yaml (base configuration)
app:
title: "My API"
version: "1.0.0"
server:
host: "localhost"
port: 8000
# config-dev.yaml (development overrides)
server:
port: 8080
features:
debug: true
auto_reload: true
# config-prod.yaml (production overrides)
server:
host: "0.0.0.0"
features:
debug: false
enable_cors: false
Verbose Output¶
Control logging verbosity with -v flags:
Normal output: .. code-block:
🌱 Tatami 0.0.1-pre.1
Running app my-api on http://localhost:8000
Verbose (`-v`): .. code-block:
🌱 Tatami 0.0.1-pre.1
Running app my-api on http://localhost:8000
• Config: config.yaml
• Routers: 3 discovered
• Services: 2 loaded
• Middleware: 1 loaded
• Static files: static/
• Templates: templates/
Debug (`-vv`): .. code-block:
🌱 Tatami 0.0.1-pre.1
DEBUG: Loading configuration from config.yaml
DEBUG: Discovered router: Users in routers/users.py
DEBUG: Discovered router: Posts in routers/posts.py
DEBUG: Discovered service: UserService in services/user_service.py
DEBUG: Loading middleware: AuthMiddleware
Running app my-api on http://localhost:8000
CLI Best Practices¶
🚀 Development¶
Use development mode with auto-reload:
tatami run . --mode dev --verbose
🏗️ Project Health¶
Run doctor regularly to catch issues early:
# Add to your development workflow
tatami doctor . && tatami run . --mode dev
📊 Production¶
Use production configuration:
tatami run . --mode prod --host 0.0.0.0 --port 8000
🔍 Debugging¶
Use debug logging for troubleshooting:
tatami run . --mode dev -vv
Troubleshooting¶
Common Issues¶
“Command not found: tatami” - Ensure Tatami is installed: pip install tatami - Check if you’re in the correct virtual environment
“No module named ‘tatami’” - Reinstall Tatami: pip uninstall tatami && pip install tatami
“Port already in use” - Use a different port: tatami run . –port 8080 - Kill existing processes: lsof -ti:8000 | xargs kill
“No routers found” - Check router files are in routers/ directory - Ensure router classes inherit from router(‘/path’) - Run tatami doctor . for detailed analysis
Getting Help¶
# General help
tatami --help
# Command-specific help
tatami run --help
tatami create --help
tatami doctor --help
What’s Next?¶
Now that you’ve mastered the CLI, learn about Docker deployment and production configuration.