Installation

Prerequisites

Zig 0.16.0 or later — Install Zig
Git — for fetching dependencies via build.zig.zon

Install the CLI

The pidgn CLI provides project scaffolding, code generation, a dev server, and database migrations.

curl -fsSL https://pidgn.dev/install.sh | sh

Install a specific version:

PIDGN_VERSION=v0.3.0-beta.1 curl -fsSL https://pidgn.dev/install.sh | sh

git clone https://github.com/seemsindie/pidgn_cli.git
cd pidgn_cli
zig build
# Binary at zig-out/bin/pidgn

Verify the installation:

pidgn version

Create a new project

Scaffold the project

pidgn new my_app

This creates a full project structure:

my_app/
  build.zig
  build.zig.zon
  .gitignore
  src/
    main.zig
    controllers/
  templates/
  public/
    css/style.css
    js/app.js

Build and run
Terminal window
```
cd my_app
zig build run
```
Your server is now running at http://127.0.0.1:4000.
Start the dev server (with auto-reload)
Terminal window
```
pidgn server
```

Add to an existing project

If you already have a Zig project and want to add pidgn as a dependency, pick whichever layout matches your setup.

Workspace (relative path)
Standalone (URL + hash)

Useful when pidgn lives next to your app on disk (monorepo, fork, or local checkout).

.dependencies = .{
    .pidgn = .{
        .path = "../pidgn",
    },
},

Fetches pidgn from GitHub and pins it to a specific commit. The hash is a content-addressable digest that Zig verifies on fetch.

.dependencies = .{
    .pidgn = .{
        .url = "git+https://github.com/seemsindie/pidgn#eb21548",
        .hash = "...", // zig build will tell you the expected hash
    },
},

Replace the commit SHA after # with whatever you want to pin (a commit, tag, or branch tip).

Finding the hash. Leave the hash = "..." line as-is on the first run, then zig build prints the correct value in the error message:

error: hash mismatch: manifest declares <old> but the fetched package has <new>

Paste <new> back into build.zig.zon. The workspace ships a helper script zhash that automates this across deps — see Workspace tooling.

Then wire it up in build.zig:

const pidgn_dep = b.dependency("pidgn", .{
    .target = target,
    .optimize = optimize,
});

exe.root_module.addImport("pidgn", pidgn_dep.module("pidgn"));

And import it in your source files:

const pidgn = @import("pidgn");

Optional dependencies

Package	What it adds	How to enable
pidgn_db	Database (SQLite & PostgreSQL)	Add `pidgn_db` dependency
pidgn_jobs	Background job processing	Add `pidgn_jobs` dependency
pidgn_mailer	Email sending	Add `pidgn_mailer` dependency
pidgn_template	Template engine	Add `pidgn_template` dependency

Next steps

Follow the Quick Start tutorial
Learn about Project Structure
Explore Routing and Middleware