shemul 1.0.0

Advanced project-aware task runner

Shemul

Shemul is a simple and lightweight project-aware task runner for development workflows. It is a free and open-source CLI that centralizes repetitive development commands in shemul.json and runs them with safety controls, supporting both project-local and user-global command scopes.

Table of Contents

• Requirements
• Features
• Change log
• Installation
• Usage
• License
• Security
• Future Plan
• Author
• Contributors
• About S Technologies
• Support
• Hire Us
• Contribute
• More
• Copyright

Requirements

• Python >= 3.14
• Optional: shell completion (bash, zsh, or fish) via scripts in completion/

Features

• Dual scope config: project and global
• Deterministic precedence: project overrides global on command conflicts
• Project discovery with shemul.json
• Command model supporting vars and env templating
• Safe execution controls: confirm, danger, --dry, --trace
• Diagnostics via shemul doctor
• Rich CLI output with grouped command lists and contextual help
• Built-in template-based initialization (shemul init)
• Global initializer: shemul init -g
• JSON Schema validation for shemul.json
• Friendly command listing, info, help, and suggestions
• Shell completion scripts for bash, zsh, and fish

Change log

Version 1.0.0 (February 11, 2026)

• Initial release.
• Project and global scope config.
• Template-based init and safety controls.

Please see CHANGELOG for more information on what has changed recently.

Installation

Shemul can be installed using pip:

pip install shemul

Usage

Scope model

Shemul supports two config scopes:

• Project scope: <project>/shemul.json
• Global scope (OS-native):
  • Windows: %APPDATA%\Shemul\shemul.json
  • macOS: ~/Library/Application Support/Shemul/shemul.json
  • Linux: $XDG_CONFIG_HOME/shemul/shemul.json (fallback: ~/.config/shemul/shemul.json)

If both scopes define the same command, project scope wins. If no config exists, Shemul suggests running shemul init -g.

Initialize global config

shemul init -g

Initialize project config

shemul init --list
shemul init fastapi-backend

List and run commands

shemul ls
shemul <command>

Init behavior

• shemul init <template> creates project shemul.json.
• shemul init -g [template] creates global shemul.json; without template uses none.
• If config already exists, init warns with path and opens the file for editing.
• Use --force to overwrite existing config.

Available templates: docker-fastapi-backend, fastapi-backend, django-drf-backend, expressjs-backend, nestjs-backend, react-native-expo-app, nextjs-frontend, none.

Common commands

shemul ls
shemul info
shemul help <name|group>
shemul doctor
shemul schema
shemul <command>

Safety flags

• confirm: true in config prompts before run.
• danger: true prompts with stronger warning.
• --dry prints resolved command.
• --trace prints resolved command and env context.

Configuration example

{
  "$schema": "https://shemul.dev/schema.json",
  "name": "example-project",
  "version": "1.0",
  "runtime": "docker",
  "env": {
    "local": {
      "compose": "docker-compose.yml"
    }
  },
  "vars": {
    "API": "api"
  },
  "commands": {
    "up": {
      "run": "docker compose up --build",
      "env": "local",
      "desc": "Start stack"
    },
    "migrate:up": {
      "run": "docker compose exec {{API}} alembic upgrade head",
      "confirm": true
    }
  }
}

Development

• Source layout uses src/. Tests are in test/.
• Run tests:

python -m pytest -q

License

Shemul is open-sourced software licensed under the MIT License.

Security

If you discover any security-related issues, please email [e-mail] instead of using the issue tracker.

Future Plan

• Plugin/extensibility system for custom resolvers and runners
• More built-in templates and community template registry
• Better cross-platform editor/open behavior and UX polish
• Optional remote/team-shared config patterns
• Additional command introspection and diagnostics

Author

• Md. Ashraful Alam Shemul

Contributors

None yet.

About S Technologies

S Technologies (STechBD.Net) is a research-based technology company in Bangladesh. It was founded in 2013. It provides services like domain registration, web hosting, web servers, software development, AI model development, software as a service (SaaS), UI/UX design, SEO, business solutions, etc. S Technologies has been working in research of new technologies especially in artificial intelligence, and developing new products. You'll find an overview of all our open source products on our website.

Support

If you are having general issues with this package, feel free to contact us on STechBD.Net/support.

If you believe you have found an issue, please report it using the GitHub issue tracker, or better yet, fork the repository and submit a pull request.

• Home Page
• GitHub Repository
• GitHub Issues
• PyPI Package
• Email
• Support Page
• Contact Form
• Facebook
• X (Twitter)
• LinkedIn
• Instagram
• YouTube

Hire Us

• AI App Development
• Web App Development
• Android App Development
• iOS App Development

Contribute

• GitHub

More

• Privacy Policy
• Terms & Conditions
• Refund Policy
• Software License Agreement

Copyright

© 2013–26 S Technologies. All rights reserved.