cmdweaver is a Python library for building custom command-line interfaces and ad-hoc shells.
It provides an engine for command matching, autocompletion, type verification, contextual commands, and help generation. Can be integrated with readline for advanced line editing and history.
- Command Definition: Define commands with keywords and typed parameters
- Autocompletion: Built-in completion engine for keywords and parameters
- Type System: Validate parameters with built-in types (String, Integer, Options, Regex, etc.)
- Contexts: Support for contextual command sets (like sub-menus)
- Help System: Automatic help generation for commands
pip install cmdweaverOr install in development mode:
pip install -e .from cmdweaver.interpreter import Interpreter
from cmdweaver.command import Command
from cmdweaver import basic_types
# Create interpreter
interpreter = Interpreter()
# Define command handler
def greet(name, **kwargs):
print(f"Hello, {name}!")
# Add command: "greet <name>"
interpreter.add_command(
Command(["greet", basic_types.StringType("name")], greet, help="Greet someone")
)
# Execute command
interpreter.eval("greet World") # Output: Hello, World!Commands are defined with a list of keywords and parameter types:
from cmdweaver.command import Command
from cmdweaver import basic_types
# Simple keyword-only command
Command(["show", "status"], show_status_func)
# Command with string parameter
Command(["set", "name", basic_types.StringType()], set_name_func)
# Command with options parameter
Command(["set", "mode", basic_types.OptionsType(["fast", "slow"])], set_mode_func)
# Command with multiple parameters
Command(
["copy", basic_types.StringType("source"), basic_types.StringType("dest")],
copy_func
)| Type | Description | Example |
|---|---|---|
StringType() |
Any non-empty string | "hello", "123" |
IntegerType(min, max) |
Integer with optional bounds | 42, -5 |
BoolType() |
Boolean (true/false) |
true, false |
OptionsType(options) |
One of predefined options | "opt1", "opt2" |
DynamicOptionsType(func) |
Options from a function | Dynamic list |
RegexType(pattern) |
String matching regex | Pattern match |
OrType(type1, type2, ...) |
Any of the given types | Union type |
Get completions for partial input:
interpreter.complete("gr") # Returns: {"greet "}
interpreter.complete("greet ") # Returns completions for the name parameterCommands can be scoped to specific contexts:
# Command only available in "config" context
Command(["set", "value"], set_func, context_name="config")
# Command always available regardless of context
Command(["exit"], exit_func, always=True)
# Enter/exit contexts
interpreter.push_context("config")
interpreter.pop_context()Get help for commands:
# Help for commands matching partial input
interpreter.help("set") # Returns dict of matching commands with their help text
# Help for all commands
interpreter.all_commands_help()This project is a fork of aleasoluciones/boscli. While we acknowledge and appreciate the original work, this fork follows its own direction with different goals and development priorities.
pip install -r requirements-dev.txt
pip install -e .make test # Run all tests
make test-coverage # Run tests with coverage report
make validate # Run tests + style + typing checksmake check-typing # Type checking with mypy
make check-style # Linting with ruff
make reformat # Auto-format codeIf you'd like to contribute, fork this repository and send a pull request.
MIT License - see LICENSE for details.