setup-wizard

setup-wizard is a small, configurable CLI that bootstraps a Python project’s local dev environment:

• picks a suitable Python interpreter (e.g. 3.14),
• creates/reuses a virtualenv,
• installs dependencies,
• ensures a .env file exists,
• optionally installs dev tools (Black, Ruff, …),
• wires up VS Code launch configuration,
• runs a basic health check,
• and gives you a clear summary of what happened.

You define what it should do for each repo in a simple setup_wizard.json file, and then run:

setup-wizard

from the project root.

---

Installation

You can install setup-wizard either as a global CLI (via pipx) or into a Python environment (via pip).

Option 1: Global CLI with pipx (recommended)

pipx install setup-wizard

After that, the setup-wizard command is available globally:

setup-wizard --help

Option 2: With pip

Inside any Python environment:

pip install setup-wizard
setup-wizard --help

---

How it works (high level)

When you run setup-wizard inside a project directory, it:

1. Loads configuration from ./setup_wizard.json (or uses defaults if missing).
2. Finds a Python interpreter that satisfies min_python (prefers preferred_python if available).
3. Creates or reuses a virtualenv in venv_dir (e.g. .venv), using virtualenv if available, falling back to stdlib venv.
4. Installs dependencies from requirements into that venv.
5. Ensures a .env file exists, copying from env_example if present.
6. Optionally installs dev tools (e.g. Black, Ruff) into the venv.
7. Optionally updates .vscode/launch.json by appending a debug configuration (without removing your existing ones) and can set Black as VS Code formatter.
8. Runs a health check by importing your configured application module (e.g. am.app), adding ./src to PYTHONPATH if it exists.
9. Optionally opens your project README at the end.
10. Prints a setup summary with ✅ / ⚠️ / ❌ for each step.

All steps are interactive by default: the wizard explains what it’s about to do and asks for confirmation.

---

Basic usage in a project

1. Add a setup_wizard.json to your repo

In your project root, create setup_wizard.json, for example:

{
  "project_name": "my-service",
  "runtime": {
    "min_python": "3.11",
    "preferred_python": "3.14"
  },
  "paths": {
    "venv_dir": ".venv",
    "env_file": ".env",
    "env_example": ".env.example",
    "requirements": "requirements.txt",
    "app_import": "my_service.app",
    "readme": "README.md"
  },
  "dev_tools": [
    "black",
    "ruff"
  ],
  "vscode": {
    "enable_launch": true,
    "entry_module": "my_service.app",
    "debug_name": "my-service",
    "use_black_formatter": true,
    "extra_env": {
      "PYTHONPATH": "${workspaceFolder}/src"
    },
    "cwd": "${workspaceFolder}"
  }
}

Then document this in your project’s README.md:

Local setup

This project uses the shared setup-wizard to set up a local dev environment.

setup-wizard

The wizard will create a virtualenv, install dependencies, ensure .env exists, set up VS Code debug configuration, and run a small health check.

2. Run the wizard

From your project root:

setup-wizard

If you keep the config in a different location (e.g. bootstrap/setup_wizard.json):

setup-wizard --config bootstrap/setup_wizard.json

---

Configuration reference (setup_wizard.json)

setup_wizard.json is a simple JSON file in the project directory. All fields are optional; sensible defaults are used when omitted.

Top-level

{
  "project_name": "my-service",
  "runtime": { },
  "paths": { },
  "dev_tools": [ ],
  "vscode": { }
}

project_name (string)

Human-readable name used in logs and as a default for VS Code debug config names (if vscode.debug_name is not set).

---

runtime section

"runtime": {
  "min_python": "3.11",
  "preferred_python": "3.14"
}

• min_python – minimum Python version required (major.minor); the wizard will refuse interpreters older than this.
• preferred_python – preferred version; if multiple interpreters satisfy min_python, the wizard tries to pick the highest, favoring this version when available.

---

paths section

"paths": {
  "venv_dir": ".venv",
  "env_file": ".env",
  "env_example": ".env.example",
  "requirements": "requirements.txt",
  "app_import": "my_service.app",
  "readme": "README.md"
}

• venv_dir – where to create/reuse the virtualenv.
• env_file – path to the .env file for local configuration.
• env_example – example env file to copy from if .env doesn’t exist.
• requirements – pip requirements file to install from.
• app_import – Python module path to import in the health check (importlib.import_module(app_import)).
• readme – path to your README file (used when optionally opening it at the end).

---

dev_tools section

"dev_tools": [
  "black",
  "ruff"
]

List of extra development tools to install into the venv. Common examples:

• formatters: black
• linters: ruff, flake8
• test tools: pytest, pytest-cov

The wizard will ask before installing them.

---

vscode section

"vscode": {
  "enable_launch": true,
  "entry_module": "my_service.app",
  "debug_name": "my-service",
  "use_black_formatter": true,
  "extra_env": {
    "PYTHONPATH": "${workspaceFolder}/src"
  },
  "cwd": "${workspaceFolder}"
}

• enable_launch (bool) – enable VS Code integration.
• entry_module (string) – module to run in debug mode (e.g. my_service.app).
• debug_name (string, optional) – name of the debug configuration in launch.json.
  If omitted, defaults to project_name, or "Python: Run app" as a fallback.
• use_black_formatter (bool) – if true, configure VS Code to use Black as formatter and enable editor.formatOnSave.
• extra_env (object, optional) – extra environment variables to set in the debug config (e.g. PYTHONPATH).
• cwd (string, optional) – working directory for the debug config (e.g. ${workspaceFolder}).

The wizard merges into existing .vscode/launch.json:

• it preserves existing configurations,
• and appends its own config if one with the same name doesn’t already exist.
  It will only offer to overwrite the file if it’s not valid JSON.

---

CLI reference

setup-wizard [OPTIONS]

Options:

• --config PATH
  Use a specific config file instead of ./setup_wizard.json.

• --python PATH_OR_CMD
  Force the target Python interpreter for the virtualenv, e.g.
  --python /usr/bin/python3.14 or --python C:\Python314\python.exe.

• --check-only
  Run only the health checks, assuming the environment is already set up.
  No venv creation, no dependency installation.

• -y, --yes
  Non-interactive / “auto-yes” mode for non-destructive steps. The wizard will still log what it does, but won’t prompt for each confirmation.

---

Notes & limitations

• The wizard cannot “activate” the virtualenv in your current shell (that’s a shell concern). It will create and use the venv for its own steps and then tell you how to activate it, e.g.:

  # PowerShell
  .\.venv\Scripts\Activate.ps1
  
  # cmd
  .\.venv\Scripts\activate.bat
  
  # bash/zsh
  source .venv/bin/activate
  

• For src/-style layouts (e.g. src/my_service/app.py), using:

  "app_import": "my_service.app",
  "vscode": {
    "extra_env": {
      "PYTHONPATH": "${workspaceFolder}/src"
    }
  }
  

  lets both the health check and VS Code debug work out of the box.

---

If you run into something you’d like the wizard to automate (e.g. migrations, pre-commit install, docs preview), you can add new steps in your own fork or open an issue/PR to extend the core tool.