biforge 0.1.1
Scaffold Power BI projects instantly from templates
License: MIT
Requires Python: >=3.10
Keywords: powerbi, power-bi, scaffold, template, cli, pbip

# biforge 🔨

**Scaffold Power BI projects instantly from templates.**

[![PyPI version](https://badge.fury.io/py/biforge.svg)](https://pypi.org/project/biforge/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

Create ready-to-use Power BI Projects (.pbip) with intelligent renaming and path updates—all from a single command.

---

<br>

![biforge demo](https://media2.giphy.com/media/v1.Y2lkPWVjZjA1ZTQ3MmhjOHBsYjZubzQ2czNhN3V5OWFqcW03ZWVucWRtaGhhNHVmMG42MSZlcD12MV9naWZzX3JlbGF0ZWQmY3Q9Zw/UiWG8AoIf4dtVEP4Bi/200.webp) 
*<p align="center">From template to working project in seconds.</p>*

<br>

## ✨ Quick Start

### Installation

**Option 1: Use without installing (quickest)**
```bash
uvx biforge "My Project"
```

**Option 2: Install globally (recommended for frequent use)**
```bash
pip install biforge

# Or with uv:
uv pip install biforge
```

**Option 3: Run directly with uvx**
```bash
# No installation needed, runs in isolated environment
uvx biforge "My Project"
uvx yeet "My Project"  # alias also works
```

### First-Time Setup

The first time you run biforge, a setup wizard will ask for your `.pbip` template folder location.

```bash
# Try creating your first project - the wizard launches automatically
biforge "My First Report"

# 🪄 The wizard will start:
# 🚀 Welcome! Let's configure your .pbip project template.
# Drag your template folder here and press Enter: _
```

### Create Projects

Once configured, just pass the project name:

```bash
# The main way (recommended):
biforge "Q4 Sales Dashboard"

# ✓ Success! Project created at '202510 - Q4 Sales Dashboard'
```

**Multiple ways to create projects:**

```bash
# Shortcut (fastest):
biforge "Annual Report"

# Explicit command:
biforge create "Annual Report"
biforge new "Annual Report"

# Using yeet alias (same functionality):
yeet "Annual Report"
```

<br>

## 🔧 How It Works

biforge doesn't just copy files—it performs intelligent scaffolding:

- **🔍 Discovery**: Analyzes your `.pbip` template and automatically detects the base project structure
- **✏️ Rename**: Updates folder names, `.pbip` file, and `.Report`/`.SemanticModel` directories to match your new project
- **🔄 Update**: Edits internal JSON configs (`.pbip`, `.pbir`, `.platform`) so all paths and display names work correctly in Fabric

**Result:** Zero manual fixes. Your project just works.

<br>

## 🎨 Creating Your Template

The power of biforge is that it works with **your own template**. Here's how:

1.  **Design Your Base Report**: Open Power BI Desktop and create your ideal starting point—add logos, themes, common pages, standard visuals.

2.  **Save as Project**: Go to `File > Save As`. In the file type dropdown, choose **`Power BI Project (*.pbip)`** instead of `.pbix`.

3.  **That's Your Template**: Power BI creates a folder with the project structure. Point the biforge setup wizard to this folder.

> **Living Template**: Update your base report anytime. Just save it as `.pbip` again in the same location. All future projects will inherit the changes automatically.

<br>

## 🧰 Commands

| Command | Action |
| ------- | ------ |
| `biforge "Name"` | Create a new project (shortcut) |
| `biforge create "Name"` | Create a new project (explicit) |
| `biforge new "Name"` | Create a new project (alias) |
| `biforge setup` | Configure or reconfigure template path |
| `biforge --help` | Show all commands and options |
| `yeet "Name"` | Same as biforge, just cooler 😎 |

<br>

## 💡 Why biforge?

- **Zero Config Needed**: Works with any `.pbip` template structure
- **Intelligent Updates**: Automatically fixes all internal paths and references
- **Date Prefixing**: Auto-adds `YYYYMM -` prefix to keep projects organized
- **Error Prevention**: Validates names and prevents overwrites
- **Multiple Aliases**: Use `biforge`, `create`, `new`, or `yeet` - whatever fits your style

<br>

## 🚀 Advanced Usage

### Using with uv (recommended for speed)

```bash
# Install with uv (faster than pip)
uv pip install biforge

# Or run without installing
uvx biforge "Project Name"
```

### Reconfiguring Template

Need to change your template location?

```bash
biforge setup
```

The wizard will guide you through selecting a new template folder.

<br>

## 📦 What Gets Created

When you run `biforge "Sales Report"`, you get:

```
202410 - Sales Report/
├── Sales Report.pbip                    # Renamed project file
├── Sales Report.Report/                 # Renamed report folder
│   ├── definition.pbir                  # Updated with new paths
│   └── .platform                        # Updated display name
└── Sales Report.SemanticModel/          # Renamed model folder
    └── .platform                        # Updated display name
```

All internal references are automatically updated to match the new names.

<br>

## 🐛 Troubleshooting

**"No .pbip file found in template"**
- Make sure your template folder contains a `.pbip` file
- The template must be saved as Power BI Project format, not `.pbix`

**"Directory already exists"**
- A project with that name already exists for this month
- Choose a different name or delete the existing folder

**Commands not working?**
- Make sure you're using the latest version: `pip install --upgrade biforge`
- For uvx users: `uvx --refresh biforge "Project"`

<br>

## 🤝 Contributing

Issues and pull requests are welcome! Visit the [GitHub repository](https://github.com/AlejandroGonzalezColin/biforge).

<br>

## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Built for analysts and developers who value their time.**

*Forge your Power BI projects. Don't fight with folder structures.*