The command-line tool for creating and managing DBBasic apps: thin scripts over git, cp and sed.
DBBasic CLI Project Context
Project Overview
dbbasic-cli is a command-line tool for creating and managing DBBasic applications. It follows the Unix philosophy: tools not frameworks, scripts not magic.
Philosophy
The design follows these principles:
- Optional - Can use dbbasic without the CLI (just use git, cp, python)
- Simple - Core CLI is ~200 lines
- Thin wrapper - Just automates Unix commands (git clone, cp, etc.)
- Extensible - Modules can add commands (like Django's manage.py)
- No Magic - Everything is visible and debuggable
Architecture
Core Components
- dbbasic_cli/cli.py - Main CLI implementation (~200 lines)
- Core commands: new, list, run, test
- Module command discovery via
discover_commands() - Uses
pkg_resourcesto find installed dbbasic-* packages
- dbbasic_cli/__init__.py - Package initialization
- setup.py - Standard setuptools configuration
- Entry point:
dbbasic=dbbasic_cli.cli:main - No dependencies (pure Python)
Command Discovery Mechanism
The CLI automatically discovers commands from installed dbbasic modules:
# Any dbbasic module can provide commands by creating cli.py:
# dbbasic_queue/cli.py
def worker_command(args):
"""Run the queue worker"""
# implementation here
COMMANDS = {
'queue:worker': worker_command,
'queue:stats': stats_command,
}
The discover_commands() function:
- Iterates through all installed packages using
pkg_resources.working_set - Finds packages starting with
dbbasic- - Converts package names to module names (dbbasic-queue → dbbasic_queue)
- Imports
{module_name}.cliand looks forCOMMANDSdict - Merges all discovered commands into a single registry
Module CLI Extensions
dbbasic-queue CLI Commands
Located at: /Users/danq/dbbasic-queue/dbbasic_queue/cli.py
Commands:
queue:worker- Run the queue worker (looks for HANDLERS in app.py)queue:stats- Show queue statistics (pending, processing, completed, failed, cancelled)queue:failed- List all failed jobs with detailsqueue:retry <job_id>- Reset a failed job to pendingqueue:clear- Remove completed/failed jobs, keep only pending/processing
dbbasic-logs CLI Commands
Located at: /Users/danq/dbbasic-logs/dbbasic_logs/cli.py
Commands:
logs:tail- Tail application logs (supports --type, -n)logs:search <pattern>- Search logs with grep (supports --type, --days)logs:compress- Compress logs older than N days (default 7)logs:stats- Show log file statistics (size, count by type)
Directory Structure
dbbasic-cli-new/
├── dbbasic_cli/
│ ├── __init__.py # Package init with version
│ └── cli.py # Main CLI implementation
├── tmp/ # Test directory (not committed)
├── setup.py # Package setup
├── README.md # User documentation
├── LICENSE # MIT license
├── .gitignore # Git ignore rules
└── CLAUDE.md # This file (project context)
Testing
Manual Testing Done
- Installation:
pip install -e .- ✓ Works - Core commands:
dbbasic help- ✓ Shows all commandsdbbasic list- ✓ Lists templates (with fallback)dbbasic new- ✓ Shows usage
- Module discovery: ✓ Finds dbbasic-queue and dbbasic-logs commands
- Module commands:
dbbasic queue:stats- ✓ Shows queue statisticsdbbasic logs:stats- ✓ Shows log statistics
Test Location
Temporary test directory: /Users/danq/dbbasic-cli-new/tmp/
- Not committed to git
- Used for integration testing
- Safe to delete
Known Issues & Notes
pkg_resources Deprecation Warning
The CLI currently uses pkg_resources which shows a deprecation warning:
UserWarning: pkg_resources is deprecated as an API
Why it's used: It's the most reliable way to discover installed packages across different Python environments.
Future fix: Consider migrating to importlib.metadata (Python 3.8+) or packaging library. However, pkg_resources still works fine and will be supported through at least 2025.
Impact: None - just a warning, functionality is unaffected.
Template Repository
The CLI expects templates at: https://github.com/askrobots/dbbasic-examples
This repository doesn't exist yet. The CLI:
- Will try to clone it on first
dbbasic newordbbasic list - Has fallback template descriptions built-in
- Gracefully handles missing repo
Action needed: Create the examples repository with these templates:
- blog (WordPress-like)
- microblog (Twitter-like)
- api (REST API)
- shop (E-commerce)
- intranet (Basecamp-like)
Integration with Other Modules
Module Requirements
For a dbbasic module to add CLI commands:
- Create
{module_name}/cli.py - Define command functions with signature:
def cmd_name(args: list) - Add docstrings to functions (first line appears in help)
- Export
COMMANDSdict mapping command names to functions
Example:
# dbbasic_yourmodule/cli.py
def hello_command(args):
"""Say hello from your module"""
print("Hello!")
COMMANDS = {
'yourmodule:hello': hello_command,
}
Installed Modules with CLI Support
Currently implemented:
- ✓ dbbasic-queue - 5 commands (worker, stats, failed, retry, clear)
- ✓ dbbasic-logs - 4 commands (tail, search, compress, stats)
Ready to add:
- dbbasic-accounts - Could add: accounts:create, accounts:list, accounts:reset-password
- dbbasic-sessions - Could add: sessions:clean (remove expired)
- dbbasic-tsv - Could add: tsv:export, tsv:import, tsv:optimize
- dbbasic-web - Could add: web:routes (list all routes)
Standard Directory Structure (Apps Created by CLI)
When dbbasic new <type> <name> creates an app:
myapp/
├── app.py # Main application file
├── data/ # TSV data files
│ └── *.tsv
├── templates/ # HTML templates
│ └── *.html
├── static/ # CSS, JS, images
│ ├── css/
│ ├── js/
│ └── img/
├── tests/ # Test files
│ └── test_*.py
├── requirements.txt # Python dependencies
└── README.md # Documentation
Development Workflow
Making Changes to CLI
- Edit files in
/Users/danq/dbbasic-cli-new/ - Changes are immediately available (editable install)
- Test with
dbbasic <command>
Adding New Commands
Core commands (edit cli.py):
- Add
cmd_<name>(args)function - Add command to
main()function - Update
print_help()if needed
Module commands (edit module's cli.py):
- Add function to module's cli.py
- Add to COMMANDS dict
- Reinstall module:
pip install -e .
Testing Checklist
Before release:
- [ ] All core commands work
- [ ] Module discovery finds all installed modules
- [ ] Help text is clear and complete
- [ ] Error messages are helpful
- [ ] Works without any modules installed
- [ ] Works with modules that don't have CLI
- [ ] Examples repository exists and is accessible
Related Files & Projects
- GitHub Repository: https://github.com/askrobots/dbbasic-cli-new.git
- Specification: http://dbbasic.com/cli-spec
- Main site: http://dbbasic.com/
- Old CLI (different design):
/Users/danq/websheet/dbbasic-cli/
Differences from Old CLI
The old CLI at /Users/danq/websheet/dbbasic-cli/:
- Uses Typer framework (heavy dependency)
- Has built-in app generators (crm, shop, blog)
- Manages services (start, stop, status)
- More opinionated and complex
The new CLI (this project):
- Zero dependencies (pure Python)
- Simpler (just templates + module commands)
- More Unix-like (thin wrapper)
- Follows the spec at dbbasic.com/cli-spec
Future Enhancements
Short Term
- ✓ Add CLI support to dbbasic-queue
- ✓ Add CLI support to dbbasic-logs
- Create dbbasic-examples repository
- Add CLI support to other modules
Medium Term
- Replace
pkg_resourceswithimportlib.metadata - Add
dbbasic scaffoldgenerator (CRUD operations) - Add completion support (bash, zsh)
- Better error handling for missing dependencies
Long Term
- Plugin system for third-party commands
- Configuration file support (~/.dbbasicrc)
- Template marketplace/registry
- Project initialization wizard
Contributing
When adding features:
- Keep it simple - follow Unix philosophy
- No heavy dependencies (prefer stdlib)
- Make everything optional
- Preserve backward compatibility
- Update this CLAUDE.md file
Package Publishing
Build Distribution
python setup.py sdist bdist_wheel
Upload to PyPI
pip install twine
twine upload dist/*
Version Bumping
Update version in:
dbbasic_cli/__init__.pysetup.py
Session Context for Claude
When working on this project:
- Main code:
/Users/danq/dbbasic-cli-new/ - Test area:
/Users/danq/dbbasic-cli-new/tmp/ - Module examples:
/Users/danq/dbbasic-queue/,/Users/danq/dbbasic-logs/ - Spec reference: Use WebFetch to get http://dbbasic.com/cli-spec
Quick Commands for Testing
# Reinstall CLI
cd /Users/danq/dbbasic-cli-new && pip install -e .
# Test core
dbbasic help
dbbasic list
# Test module commands
dbbasic queue:stats
dbbasic logs:stats
# Test in clean environment
cd /Users/danq/dbbasic-cli-new/tmp
Summary
This is a working, spec-compliant implementation of dbbasic-cli that:
- ✓ Implements core commands (new, list, run, test)
- ✓ Auto-discovers module commands from installed packages
- ✓ Has no dependencies
- ✓ Is ~200 lines of code
- ✓ Works with existing dbbasic modules
- ✓ Includes working CLI extensions for queue and logs modules
The main outstanding item is creating the dbbasic-examples repository with template applications.