Metadata-Version: 2.4
Name: shemul
Version: 1.0.1
Summary: Shemul CLI is an advanced project-aware task runner based on JSON configuration.
Author-email: "Md. Ashraful Alam Shemul" <shemul@stechbd.net>, S Technologies <contact@stechbd.net>
License-Expression: MIT
Project-URL: Homepage, https://www.stechbd.net/product/Shemul-PIP
Project-URL: Repository, https://github.com/STechBD/Shemul-PIP
Project-URL: Issues, https://github.com/STechBD/Shemul-PIP/issues
Keywords: cli,task-runner,devtools,automation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.9
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rich>=13.7.0
Requires-Dist: jsonschema>=4.22.0
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Dynamic: license-file

# Shemul

Shemul is an advanced project-aware CLI tool for task automation based on JSON configuration for PIP. 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](#requirements)
- [Features](#features)
- [Change log](#change-log)
- [Installation](#installation)
- [Usage](#usage)
- [FAQs](#faqs)
- [License](#license)
- [Security](#security)
- [Future Plan](#future-plan)
- [Author](#author)
- [Contributors](#contributors)
- [About S Technologies](#about-s-technologies)
- [Support](#support)
- [Hire Us](#hire-us)
- [Contribute](#contribute)
- [More](#more)
- [Copyright](#copyright)

## Requirements

- Python >= 3.9
- Optional: shell completion (bash, zsh, or fish) via scripts in `completion/`

## Features

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

## Change log

### Version 1.0.1 (March 20, 2026)

- Fixed Python version requirement to >= 3.9 across package metadata and docs.

### Version 1.0.0 (February 11, 2026)

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

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

## Installation

Shemul can be installed using pip:

```bash
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

```bash
shemul init -g
```

### Initialize project config

```bash
shemul init --list
shemul init fastapi-backend
```

### List and run commands

```bash
shemul ls
shemul <command>
```

### Init behavior

- `shemul init [template]` creates project `shemul.json`; without template uses `none`.
- `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

```bash
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

```json
{
	"name": "example-project",
	"version": "1.0.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:

```bash
python -m pytest -q
```

## FAQs

### What is Shemul?

Shemul is an advanced project-aware CLI tool for task automation based on JSON configuration for PIP.

### What is `shemul.json`?

It is the project or global JSON config that defines your commands, variables, and environment presets.

### Do I need both global and project configs?

No. You can use either. If both exist, project commands override global commands with the same name.

### How do I create a blank Shemul config?

Run `shemul init` to create a minimal config using the `none` template.

### How do I see the built-in schema for Shemul?

Run `shemul schema` to print the bundled JSON Schema.

### Where is the global config stored?

Windows: `%APPDATA%\Shemul\shemul.json`  
macOS: `~/Library/Application Support/Shemul/shemul.json`  
Linux: `$XDG_CONFIG_HOME/shemul/shemul.json` (fallback: `~/.config/shemul/shemul.json`)

## License

Shemul is open-sourced software licensed under the [MIT License](LICENSE).

## Security

If you discover any security-related issues, please email [product@stechbd.net](mailto:product@stechbd.net) 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
- [ ] Support for custom terminal colors and themes

## Author

- [Md. Ashraful Alam Shemul](https://github.com/AAShemul)

## 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](https://www.stechbd.net/open-source).

## Support

If you are having general issues with this package, feel free to contact us on [STechBD.Net/support](https://www.stechbd.net/support).

If you believe you have found an issue, please report it using the [GitHub issue tracker](https://github.com/STechBD/Shemul-PIP/issues), or better yet, fork the repository and submit a pull request.

- [Home Page](https://www.stechbd.net/product/Shemul-PIP)
- [GitHub Repository](https://github.com/STechBD/Shemul-PIP)
- [GitHub Issues](https://github.com/STechBD/Shemul-PIP/issues)
- [PyPI Package](https://pypi.org/project/shemul/)
- [Email](mailto:product@stechbd.net)
- [Support Page](https://www.stechbd.net/support)
- [Contact Form](https://www.stechbd.net/contact)
- [Facebook](https://www.facebook.com/STechBD.Net)
- [X (Twitter)](https://twitter.com/STechBD_Net)
- [LinkedIn](https://www.linkedin.com/company/STechBD)
- [Instagram](https://www.instagram.com/STechBD.Net)
- [YouTube](https://www.youtube.com/channel/STechBD)

## Hire Us

- [AI App Development](https://www.stechbd.net/ai-development)
- [Web App Development](https://www.stechbd.net/web-development)
- [Android App Development](https://www.stechbd.net/android-app-development)
- [iOS App Development](https://www.stechbd.net/ios-app-development)

## Contribute

- [GitHub](https://github.com/STechBD/Shemul-PIP)

## More

- [Privacy Policy](https://www.stechbd.net/privacy)
- [Terms & Conditions](https://www.stechbd.net/terms)
- [Refund Policy](https://www.stechbd.net/refund-policy)
- [Software License Agreement](https://www.stechbd.net/software-license-agreement)

## Copyright

© 2013–26 **[S Technologies](https://www.stechbd.net)**. All rights reserved.
