Build Your First App with Piezas.ai

Piezas.ai is a set of building blocks (APIs) that your AI coding tool assembles into the backend for production-grade software. A team of senior engineers architects, develops, reviews, audits and tests each block, so the data, sign-in, scheduling, notifications and hosting your app needs are…

To build software with Piezas, you need:

A Piezas account
An AI coding tool: Claude or Codex (with the Piezas extension), or any other AI coding tool with the Piezas command line
Node.js (the LTS version), which the extension and the command line use on your computer
A good idea of what you want to build

You don't write code. You describe what you want, and your AI tool builds it on Piezas. The whole loop is describe → see it → build → go live.

Step 1: Create your Piezas account

Sign up at app.piezas.ai/signup. You'll sign in with this account from your AI tool, and multi-factor authentication is required.

Step 2: Install Piezas (one-time)

Pick the one that fits how you work. All three build the same kind of app on Piezas.

Install the Codex extension

Follow Install the Piezas extension for Codex.

Install the Claude extension

Follow Install the Piezas extension for Claude.

Install the CLI

For any AI coding tool, or if you prefer to type the commands yourself.

Install Node.js (the LTS version) from nodejs.org. It includes npx.
Check it: in Terminal (Mac) or Command Prompt (Windows), type node --version. If you see a version number, you are set.
There is nothing else to install: npx piezas downloads the Piezas command-line tool when you run it.

Using the extension, step by step

Works the same in Codex and Claude.

Start. Open a new chat in an empty folder and say "Set up this folder for a new Piezas app".
Sign in. The AI posts a Sign in to Piezas link. Open it, check the code matches, and click Approve. The AI carries on by itself.
Answer the first question: "Starting fresh, or do you already have an app?" Starting fresh: it asks for your app's name and creates the app in your account. Already have one (built with Lovable, Claude Code, a freelancer or anything else): tell it where the folder is on your computer. It copies the app into a new folder and never changes your original.
Switch on the checks. The first time, approve the Piezas checks, then start a new chat in the same folder. In the Codex app, open Settings, then Hooks, find your project under From Projects and click Trust all (step by step). In Codex in a terminal, type /hooks and trust Piezas. In Claude, click Trust workspace, or say yes when Claude Code asks whether you trust the folder.
Describe it. It asks you one question at a time, then shows a short summary card and asks "Want to see it?" For an app you brought in, it drafts the description from your code instead, and lists what must move to Piezas and what Piezas can take over. You decide each item. This is the most valuable step: a clear description means the right app gets built the first time.
Check the preview. You get a clickable preview with sample data. Ask for any changes. When you're happy, reply approve. Only your own reply counts.
Let it build. It builds the real app. Checks run as it works and stop anything that breaks Piezas's rules. When its tests pass, it shows short clips of each part of the app working.
Add any settings. If the app needs a key or setting, it tells you what's missing and where to set it: your app's page at app.piezas.ai, or a command to run in your own terminal. Never paste keys into the chat.
Go live. It publishes and gives you the live address. The Report a problem button stays on unless you ask to turn it off. If something breaks a Piezas rule, it pauses and offers to fix it; only you can reply deploy anyway.

Later: open a chat in the same folder. If people reported problems with the Report a problem button, the AI tells you and offers to fix them all at once.

Using the CLI, step by step

1. Set up your project

Make a new empty folder, open it in Terminal, and run:

npx piezas@latest login
npx piezas@latest init

login opens your browser so you can approve the sign-in. init creates your app and connects the folder to it, and gives your AI tool two things: the platform contract (the rules of every Piezas building block, so it builds against reality instead of guessing) and a guided spec mode.

2. Describe it: let the AI interview you

Open the folder in your AI coding tool and run:

/piezas-spec your idea here

(If your tool has no slash commands, ask for "Piezas spec mode".) The assistant becomes a product manager and asks you one question at a time (a quick first version or a complete one? who are the users? what do they need to do?), then writes a clear SPEC.md.

3. Get a design (optional, recommended)

When the spec is ready, it offers a paste-ready design prompt for Claude. Say yes and it writes a DESIGN_PROMPT.md. Drop that into Claude Design (or another design tool) to get screen layouts before building starts, so your app looks polished instead of default.

4. Build from the spec

Tell the assistant "Build this from SPEC.md." Because it has the contract and your spec, it builds the whole app on Piezas: data, logic and screens. Review and refine in plain English. For a commercial product, we highly recommend automated tests for each feature, plus a regression test you run before every release.

5. Check it and publish

npx piezas doctor
npx piezas deploy

doctor checks the app is ready. deploy publishes it and gives you a live link to share. If your app needs settings such as keys, set them on your app's page at app.piezas.ai or with npx piezas env set NAME=value. Never paste them into the chat.

You can manage the app and attach a domain on the Piezas dashboard.

Want the short version? See Hello, World.