Getting Started

Putnami starts with one workspace model, then lets you choose the runtime surface that fits the first thing you want to build.

Use this page to get the CLI and workspace in place. If you already know the language you want, jump straight to the framework start guide:

You want to build... Start here
React SSR, API routes, or a TypeScript library TypeScript getting started
A Go service or Go library Go getting started
An experimental Python service, library, or data workload Python getting started

Run the verified first-use path

From an empty directory, run these three commands in the same shell:

curl -fsSL https://putnami.dev/install.sh | bash
putnami init --project webapp --extension ts
putnami serve webapp

Supported platforms are macOS and Linux, on amd64 or arm64. On Windows, install inside WSL2. Anything else stops with an error naming what it detected, rather than installing a binary that cannot run.

Prerequisites are Bash, curl, tar, either sha256sum or shasum, Bun v1.4.0 or later for the TypeScript init/serve path, network access to putnami.dev and the public artifact registry, network access to the public package registry (https://npm.putnami.dev) used by bun install, and a standard user-writable directory already named by PATH (~/.local/bin, ~/bin, the install directory, or a writable /usr/local/bin). The home-directory candidate may be absent: the installer creates it. That PATH prerequisite is what makes the second command discoverable immediately; a script running as the child of a pipe cannot mutate its parent shell.

What the installer does, and does not do

  • It verifies what it downloads. The registry states the SHA-256 of the binary it serves; the installer computes that hash and compares. It prints Integrity verified (sha256:…) only after the comparison passes, and it refuses to install anything it cannot check.

  • It never asks for your password. No sudo, ever. It installs into ~/.putnami/bin, and links putnami only into a directory that is already on your PATH and writable by you. If there is no writable target, it says which directory and stops — pass --install-dir <dir> to choose another one.

  • It tells you if you need one more line. When it cannot reach your PATH on its own, it prints the exact command to run in the shell you are in:

    export PATH="$HOME/.putnami/bin:$PATH"

    and appends it to your shell startup file for future shells. The last line it prints is which putnami your shell now runs, so you never have to guess.

Install a specific version with curl -fsSL https://putnami.dev/install.sh | bash -s -- --version 1.2.3.

Already installed? Update any time with putnami upgrade --global — the install script is only needed once per machine.

Prefer not to run an install script? Read the CLI reference for the command surface and install notes.

What the gate proves

The release gate replays the exact commands above with an empty workspace, neutral home/config/cache directories, no credentials, and no preinstalled CLI or extensions. init creates and validates:

  • putnami.workspace.json identifies the workspace root
  • putnami.lock.json pins the TypeScript extension and web template
  • webapp/putnami.json identifies the generated project
  • package.json and bun.lock record its dependency state
  • .npmrc maps @putnami dependencies to the public package registry without credentials
  • one Putnami block in AGENTS.md (which CLAUDE.md imports) gives coding assistants the local conventions

serve must emit machine-readable readiness, the starter must answer a real HTTP request successfully, and shutdown must complete within the gate's bound. Open the local URL printed by putnami serve.

This guarantee is deliberately narrow. It does not promise support for every shell or Linux distribution, Windows outside WSL2, other architectures, offline installation, proxy-specific configuration, production deployment, or stable source details in every future generated app. Go and experimental Python starters remain available through their framework guides, but they are not the three-command golden path gated here. The checksum proves the bytes match the public registry's digest; artifact signing is a separate, non-goal mechanism.

Experimental Python requires an explicit workspace opt-in after initialization:

putnami deps add @putnami/python
putnami extensions install

What just happened

You interacted with three core pieces of Putnami:

  • Workspace - the root container that organizes projects, extensions, templates, and shared context. Learn more
  • Project - a runnable unit inside the workspace. Learn more
  • Template - the scaffold that gives a new project its language-specific shape. Reference
  • CLI - the command surface for build, test, lint, serve, publish, dependencies, and templates. Reference

You didn't configure anything yet. Defaults are intentional.

Continue from here

Choose the path closest to your first project: