Language: English | Indonesia
PyArtisan is a multi-framework Python web development CLI, inspired by Laravel Artisan. pyartisan new clones a framework template into a new project; later commands such as make read that project's .pyartisan/manifest.yaml to generate code. The core is framework-agnostic: framework knowledge lives in the template repos, FlaskIQ for Flask and FastIQ for FastAPI.
new: clone a framework template and set up the project (venv and dependencies, optional)make: generate code from the generators declared in the project's manifest, with no hardcoded generator per frameworkserve: Docker first, then the project's venvbuild: run the build script from the manifestplugin: package-manager-style plugins (install,apply,remove, ...), see docs/en/CLI.mdconfig: persistent settings in~/.pyartisan/config.tomldoctor: check your local environment- Works with uv (isolated install, no venv needed); pip also works
- Python 3.10+
Recommended, with uv. It installs into an isolated environment, so you do not need to create a venv and your system Python is untouched:
uv tool install git+https://github.com/bijoaja/pyartisan
# or run without installing:
uvx --from git+https://github.com/bijoaja/pyartisan pyartisan --helpFrom source:
git clone https://github.com/bijoaja/pyartisan.git
cd pyartisan
uv tool install . # or: uv tool install --editable . (for contributors)
# without uv: pip install -e .If pyartisan is not found afterwards, run uv tool update-shell and open a new terminal.
When uv is on PATH, pyartisan new also creates the project venv and installs dependencies with uv. Otherwise it falls back to python -m venv and pip.
- Python ≥ 3.10 (uv can download it for you)
- Git (
pyartisan newand GitHub plugin installs usegit clone) - Runtime dependencies are declared in
pyproject.toml:click,flask,sqlalchemy,jinja2,pyyaml, andtomlion Python < 3.11.flaskandsqlalchemyare not imported by PyArtisan's own code.
pyartisan --helppyartisan new flask myapp
pyartisan new fastapi myapiRuns git clone of the template (FlaskIQ for flask, FastIQ for fastapi; see pyartisan config show for the URLs), writes .pyartisan/project.yaml, then asks whether to create ./venv and install requirements.txt. Template URLs can be changed with pyartisan config set templates.<framework> <url>.
There is no auto-detection from files. The framework is recorded once, by pyartisan new, in .pyartisan/project.yaml. make and serve read .pyartisan/manifest.yaml, so run them from inside a project created by pyartisan new.
pyartisan make <target> <name> [--force] [--<option> <value> ...]<target> must be a generator declared in the project's .pyartisan/manifest.yaml. For FlaskIQ these are controller, service, repository, model and routes; FastIQ declares module and model. Extra --option value pairs go straight into the Jinja2 render context (defaults: type = view, version = 1).
pyartisan make model Post
pyartisan make repository Post
pyartisan make service Post --type view
pyartisan make controller Post --type api --version 2An unknown target, or running outside a project that has .pyartisan/manifest.yaml, fails with an error and exit code 1.
pyartisan serveNo flags. serve picks a strategy automatically:
- Docker (
docker compose up) ifdocker-compose.ymlexists and Docker is running. - Otherwise, the
scripts.servecommand from the manifest, run inside the project's own venv (./venvor./.venv). This also works when PyArtisan itself was installed withuv tool. - Otherwise, an error with instructions (exit code 1).
pyartisan buildRuns scripts.build from .pyartisan/manifest.yaml. Fails with exit code 1 if the manifest defines no build script.
pyartisan config # same as: config show
pyartisan config show
pyartisan config set templates.flask https://github.com/you/your-flaskiq-fork.git
pyartisan config resetpyartisan doctor # Python, uv, pip, Git, virtual environment
pyartisan versionpyartisan plugin init my-plugin # scaffold a plugin and link it for development
pyartisan plugin install user/repo # clone from GitHub into ~/.pyartisan/plugins
pyartisan plugin apply my-plugin # apply it to the current project
pyartisan plugin list --globalSee docs/en/CLI.md for every plugin command and docs/en/HOW_TO_CREATE_PLUGIN.md to write one.
The folder layout of a generated project comes from its template, not from PyArtisan. Look at the template repo (FlaskIQ, FastIQ) for the current layout.
PyArtisan itself is one package, src/pyartisan/:
| Folder | Role |
|---|---|
cli/commands/ |
one file per command, parses arguments only |
core/ |
engine.py (dispatch), manifest loading, registration, ProjectContext for plugin hooks |
marketplace/ |
global plugin registry in ~/.pyartisan/plugins |
renderer/, config/, shared/, utils/ |
Jinja2 rendering, config.toml, doctor logic, helpers |
templates/plugin_init/ |
skeleton used by plugin init |
~/.pyartisan/config.toml is created on first use:
theme = "default"
author = ""
license = "MIT"
default_framework = "flask"
[templates]
flask = "https://github.com/bijoaja/flaskiq.git"
fastapi = "https://github.com/bijoaja/fastiq.git"Only templates.* is read by a command today (new); the other keys are stored but not used yet.
| Document | English | Indonesia |
|---|---|---|
| CLI reference | docs/en/CLI.md | docs/id/CLI.md |
| Writing a plugin | docs/en/HOW_TO_CREATE_PLUGIN.md | docs/id/HOW_TO_CREATE_PLUGIN.md |
| Product requirements and status | docs/en/PRD.md | docs/id/PRD.md |
| Contributor guide | docs/en/CONTRIBUTING.md | docs/id/CONTRIBUTING.md |
Contributions are welcome. Start with CONTRIBUTING.md.
MIT, see LICENSE.