Shemul CLI v2.0.0: A Cross-Platform JSON Task Runner for Python

Shemul CLI v2.0.0 is here 🎉 Shemul CLI is an advanced project-aware tool for task automation based on JSON configuration for PIP. It centralizes repetitive development commands in shemul.json, supports both project-local and user-global command scopes, and runs everything with built-in safety controls. v2.0.0 roughly doubles the feature set — and stays fully backward compatible.

📌 The gist

• Shemul CLI v2.0.0 is a cross-platform task automation tool for Python — pip install shemul, define commands once in shemul.json, run them anywhere with shemul <command>.
• What's new: cross-OS commands, interpreter maps + magic variables, task pipelines (needs/pre/post/parallel), safe execution, an update notifier, the s alias, plugins, and requires version gating.
• Migration: fully backward compatible — for almost everyone, just run pip install --upgrade shemul. Only two changes matter: command-dispatch precedence and a new questionary dependency.
• Why it matters: one config that runs the same on Windows, macOS, and Linux — no more open . vs start . vs xdg-open ..

☕ A Monday morning you probably recognize

It's 9:14 on a Monday. Your coffee is still too hot to drink. You pull up a project you haven't touched in three weeks, and the cursor blinks at you like it's waiting for a password you've clearly forgotten.

How do I start this thing again?

You scroll your shell history. You crack open the README — half the commands are outdated. You find a scripts/ folder with four files and no clue which one is current. Ten minutes later you finally remember it was docker compose up --build, except this project used a custom compose file, so it wasn't even that.

Now multiply that by every repository you own. By every teammate who runs a slightly different command on a slightly different OS. By every new hire who pings you to ask, "Hey, how do I run this locally?"

None of this is hard work. That's exactly the problem — it's friction disguised as work. It quietly taxes your focus before you've written a single line of code.

Shemul CLI was built for that Monday morning. The idea is almost embarrassingly simple: write the command down once, in a place your whole team can find, and never go hunting again.

😵‍💫 The problem we all know

You open a project, and your brain instantly switches to command memory mode:

• docker compose up --build
• python manage.py migrate
• uvicorn main:app --reload
• random scripts you know exist somewhere

Some are in your shell history. Some are in README files. Some… just gone.

And it gets worse the moment your team is on Windows, macOS, and Linux at the same time. open . vs start . vs xdg-open .. python vs python3. The same task, three different incantations.

💡 How Shemul CLI fixes it

You define your commands once inside a clean JSON file — shemul.json — then you run them like this:

shemul up

That's it. No digging. No remembering long commands. No switching context. It's especially powerful for Python workflows where pip install shemul gives you a lightweight CLI that fits naturally into your existing setup 🐍

🧠 Built around how you actually work

• ✨ Project-aware by default — if a shemul.json exists, Shemul CLI understands your project instantly.
• 🌍 Dual scope system — project-level commands and global user commands.
• 🎯 Smart precedence — project commands always override global ones. No surprises.
• 🛡️ Safety first — confirm prompts, danger warnings, dry runs and trace mode.

🚀 What's new in v2.0.0

This is the big one. v2.0.0 takes Shemul CLI from "a tidy command list" to a portable, cross-OS task runner with real pipelines.

🌐 Cross-OS commands (os)

One command, per-OS variants. Lookup order: current OS → default → base run.

{ "open": { "run": "xdg-open .", "os": { "windows": "start .", "macos": "open ." } } }

🧰 Interpreter maps (bin) and magic variables

Define a tool once per OS, reuse it everywhere as {{py}}. Plus auto-injected vars — {{os}}, {{arch}}, {{python}}, {{shell}}, {{sep}}, {{home}} — no config needed.

{ "bin": { "py": { "windows": "python", "default": "python3" } } }

🔗 Task pipelines (needs, pre, post, parallel)

Compose commands into dependency chains. Shared deps run once, cycles are detected, and parallel: true runs them concurrently.

{ "ci": { "run": "echo green", "needs": ["lint", "types", "test"], "parallel": true } }

Run order for any command: needs → pre → the command → post.

🛡️ Safe execution (shell / exec)

For commands handling untrusted input, opt into argument-vector execution — no shell parsing.

{ "safe": { "exec": ["python3", "tool.py", "--name", "value"] } }

More

• ⚙️ Default shell via runtime — pick the default shell (bash, pwsh, zsh, …) for your whole config.
• 🔔 Update notifier + opt-in auto-update — a non-blocking PyPI check (≤ once per 24h) prints a one-line notice when a newer release exists. shemul settings auto-update on lets Shemul CLI update itself. Off by default; never blocks your command.
• ⌨️ The s alias — type s build instead of shemul build. The installer refuses to clobber an existing s.
• 🧩 Plugins (runner) — third-party packages can register custom runners via the shemul.plugins entry point. Missing or failing runners fall back to normal execution — never a crash.
• 📌 requires + version codes — declare "requires": ">=2.0.0" so older installs show a clean upgrade hint instead of a cryptic error. Each release also carries a monotonic version code (shemul version --code → 2.0.0 (code 3)).
• ✨ Interactive arrow-key prompts — on a real terminal, confirm/danger, the init template chooser, and shemul settings use arrow keys. In CI/pipes it falls back to plain typed prompts automatically.

🥊 How Shemul CLI compares to Make, Just, Task and npm scripts

Legend: ✅ native · 🟡 partial / workaround · ❌ none

The short version: Shemul CLI matches the modern task-running leaders on per-OS commands, dependency graphs, parallelism, and completion — and stands alone on the combination that actually bites you day to day: safety gating, dual project + global scope, interactive prompts, background auto-update, and a JSON-first, schema-validated config that pip installs in seconds. No new DSL to learn, no .PHONY footguns, no "works on my machine."

It's honest about what it isn't, too: Shemul CLI is a task runner, not a build system (no content-hash incremental rebuilds) and not a language-version manager — it composes cleanly with tools like mise/asdf instead of competing with them.

🔁 Migration guide: v1.0.1 → v2.0.0

TL;DR — for almost everyone, there's nothing to do. The shemul.json format is fully backward compatible; every new capability is an optional key. Your existing configs load and run identically.

pip install --upgrade shemul
shemul /version --code      # 2.0.0 (code 3)

Version-code note: the version code counts releases (1.0.0 = 1, 1.0.1 = 2, 2.0.0 = 3). There is no 1.1.0 — this work shipped as 2.0.0.

It's a major release for two reasons only:

1. Command dispatch precedence changed. In 1.0.1, a bare built-in name always ran the built-in. In 2.0.0, a bare name prefers your project/global command of the same name, falling back to the built-in. This only affects you if your config defines a command named like a built-in — init, ls, info, help, doctor, or schema (these were unreachable before). To force the built-in, prefix it with a slash:

shemul /init        # always the built-in initializer
shemul /doctor      # always the built-in diagnostics

The new subcommands update, alias, version, settings and about follow the same rule. On Git Bash / MSYS2 on Windows, double the slash: //init.

2. New dependency: questionary. Added for the interactive arrow-key prompts. pip install -U shemul pulls it in automatically. If you vendor dependencies or run in a locked environment, add questionary>=2.0.0.

Good to know for CI and scripts (not breaking):

export SHEMUL_NO_UPDATE_CHECK=1     # silence the background PyPI check
export SHEMUL_NO_INTERACTIVE=1      # force plain typed prompts anywhere

Auto-update is off by default and skipped for editable installs. In CI/pipes, confirm/danger already fall back to typed prompts automatically.

Adopt the new features incrementally — none are required:

{ "requires": ">=2.0.0", "commands": { "run": { "run": "{{python}} app.py" } } }

📦 Install and upgrade

New to Shemul CLI? pip install shemul. Already using it? pip install --upgrade shemul.

❓ Frequently asked questions

What is Shemul CLI? Shemul CLI is a lightweight, project-aware task automation tool for Python, installable with pip install shemul. You define your project's commands once in a shemul.json file and run them with shemul <command> on Windows, macOS, or Linux.

How is Shemul CLI different from a Makefile or npm scripts? Shemul CLI is cross-platform by design (per-OS command variants, interpreter maps, and magic variables like {{python}} and {{os}}), installs with pip, and adds safety controls — confirm prompts, danger warnings, dry-run, and trace — that shell scripts don't give you out of the box. It sits in the gap between raw shell commands and heavy automation tools: lightweight, but structured.

Is Shemul CLI v2.0.0 backward compatible with v1.0.1? Yes. Every existing shemul.json keeps working unchanged. Every new 2.0.0 capability is an optional config key. The only behavior change is command-dispatch precedence, which affects you only if you defined a command named like a built-in (init, ls, doctor, etc.) — use the slash form (shemul /init) to force the built-in.

How do I upgrade Shemul CLI to v2.0.0? Run pip install --upgrade shemul, then verify with shemul version --code (it should print 2.0.0 (code 3)). The new questionary dependency installs automatically.

Where does Shemul CLI store its global config? Windows: %APPDATA%\Shemul\shemul.json · macOS: ~/Library/Application Support/Shemul/shemul.json · Linux: $XDG_CONFIG_HOME/shemul/shemul.json (fallback ~/.config/shemul/shemul.json). Project commands always override global ones.

Can Shemul CLI run the same command on Windows, macOS, and Linux? Yes — that's a headline v2.0.0 feature. Use the os key for per-OS variants, bin interpreter maps to define a tool once per platform, and magic variables ({{os}}, {{arch}}, {{python}}, {{shell}}, {{sep}}, {{home}}) for portable commands with zero extra config.

How do I preview a command without running it? Put the global flag before the command: shemul --dry deploy prints the resolved command without executing it, and shemul --trace deploy also shows its environment context.

Does Shemul CLI auto-update itself? No — not unless you opt in. The update notifier only prints a one-line notice (at most once per 24h, in the background). Auto-update is off by default; enable it with shemul settings auto-update on. It's skipped for editable (pip install -e) installs and can be fully disabled with SHEMUL_NO_UPDATE_CHECK=1.

How do I run task pipelines or chained commands? Use needs for dependencies (run first, deduped, cycle-checked), pre/post for hooks, and parallel: true to run dependencies concurrently. The run order is always needs → pre → command → post.

Is Shemul CLI safe for commands that take untrusted input? Yes. By default commands run through the shell (so &&, pipes, and globs work). For untrusted input, use "shell": false or "exec": ["arg", "vector"] to run argv directly with no shell parsing.

Is Shemul CLI a good alternative to a Makefile? Yes — especially for cross-platform and Python teams. A Makefile depends on a Unix-style shell and its own DSL (tabs, .PHONY, recursive expansion) that breaks or behaves differently on Windows. Shemul CLI uses plain JSON, runs the same on Windows, macOS, and Linux via per-OS command variants and magic variables, and adds safety gates and dry-run that Make doesn't offer out of the box.

Shemul CLI vs Just vs Task (go-task) — which should I choose? All three are solid modern task runners. Just and Task use their own file formats (justfile DSL, YAML) and ship as standalone binaries; Shemul CLI uses schema-validated JSON and installs with pip install shemul, so it fits naturally into Python projects and CI. Shemul CLI is also unique in combining confirm/danger safety gates, dual project + global command scope, interactive arrow-key prompts, and a background update notifier in one tool.

Is there a cross-platform alternative to npm scripts for non-JavaScript projects? Yes. npm scripts are convenient but tied to package.json and Node, and they have no first-class per-OS commands, dependency graph, or dry-run. Shemul CLI brings the same "define commands once, run by name" ergonomics to any stack — Python, Docker, Go, Rust, anything you can run from a shell — with portability and safety built in.

Does Shemul CLI replace a build system like Make or Bazel? No, and that's deliberate. Shemul CLI is a task runner, not a build system — it doesn't do content-hash incremental rebuilds or artifact dependency graphs. It focuses on running your project's commands reliably and portably, and composes well alongside a build system if you need one.

What's on the Shemul CLI roadmap after v2.0.0? Future 2.x releases are planned to land additively (no breaking changes), with candidate features like a watch mode, matrix commands, retry/timeout, config includes and profiles, a TUI command launcher, and a graph view of your task DAG. The next major (v3.0.0) is reserved for a single change that can't be additive: flipping execution to safe-by-default (arg-vector) with shell features available on request.

Where can I learn every feature? The Usage & Examples guide ships with the package and covers 1–3 examples of every feature, alongside a full migration guide and changelog. Issues and feedback: github.com/STechBD/Shemul-CLI/issues.

💬 Final thoughts

v1.0.0 built the foundation. v1.0.1 made it stronger. v2.0.0 makes it portable — one config that runs the same everywhere, with real pipelines and safer execution.

Shemul CLI is still about one simple idea: 👉 one config, 👉 one CLI, 👉 one place for your workflow.

So picture that Monday morning again — same project, same too-hot coffee. Except this time you type shemul up, the server spins to life, and you're writing code before the cup is cool enough to drink. No archaeology. No README spelunking. No "how do I run this again?"

That's the whole promise. And honestly… that's all most projects really need.

Give it a try: pip install shemul. Your future self — the one staring down next Monday — will thank you. ☕