Build your first mini app with a clean, obvious workflow.
This guide is written for people who want the shortest path from zero setup to a live A1Zap app. Follow it top to bottom if you're new, or jump straight to the section you need.
1. Install the basics
Node.js, a terminal, and an editor.
2. Connect the A1Zap CLI
Install it once, then authenticate with your key.
3. Use Cursor to make changes
Prompt in plain English and review the diff.
4. Preview, iterate, and push
Run locally, tweak fast, then ship.
What success looks like
By the end, you'll have the CLI installed, your app open in Cursor, a local live preview running, and a clear push path when you're ready to ship.
If you already have Node
Skip to Install the CLI and come back only if you hit setup issues.
Environment setup
You only need three things to get started: a terminal, Node.js, and an editor. Pick your operating system and follow the exact steps below.
Choose your operating system
The commands and setup notes update instantly.
Linux setup
Use your app launcher or press Ctrl + Alt + T.
On Ubuntu or Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt-get install -y nodejs
On Fedora:
sudo dnf install -y nodejs
Then check the version:
node -v
You can skip this section if
- You already have Node 18+ installed.
- You already use Cursor or VS Code.
- You know how to open a terminal.
Quick check
Run node -v. If you see a version number, move on to the CLI install.
Install the CLI
This is the one-time setup that lets your computer talk to A1Zap. After this section, you can create, edit, preview, and push apps locally.
curl -fsSL https://raw.githubusercontent.com/a1baseai/a1zap-miniapp-editor/main/install.sh | bash
Close the current terminal window and open a fresh one so your new a1zap command is on the PATH.
a1zap --version
Generate a key on the Developer CLI page and then run:
a1zap config "your-api-key"
a1zap list
If you see your apps, the CLI is fully connected.
Fallback install
If script installs are blocked on your network, use npm instead:
npm install -g a1zap-miniapp-editor
If "a1zap" is not found
- Open a brand new terminal window.
- Check Node first with
node -v. - Try the installed binary directly:
~/.local/bin/a1zap
Build flow
Once the CLI is connected, this is the full loop most developers follow: get the app locally, open it in an editor, run the live preview, then push when the result looks right.
Create or pull
Start a new app or pull an existing one onto your machine.
a1zap create my-app --name "My App"
a1zap pull my-app
Open and edit
Jump into the app folder and open it in Cursor or another editor.
cd $(a1zap open my-app) cursor .
Preview and push
Keep the preview running while you iterate, then push when you're happy.
a1zap dev my-app a1zap push my-app
Typical session
This is the shortest command sequence to keep in your head.
# One time: create a new app a1zap create my-app --name "My App" # Open the local folder cd $(a1zap open my-app) cursor . # Start a live preview a1zap dev my-app # After editing and reviewing a1zap push my-app
Vibe coding with AI
A1Zap works well with AI-first editors because your app is just a normal folder of files. Describe the change, let the editor draft it, review the diff, and keep tightening until the preview matches the idea in your head.
The loop
- 1. Ask for one specific change.
- 2. Review the files the AI touched.
- 3. Check the local preview.
- 4. Ask for the next correction.
- 5. Push only when the preview looks right.
Rule of thumb
Good prompts mention the screen, the desired behavior, and the visual style. Bad prompts are vague and make the AI guess.
Set up Cursor
Download Cursor from cursor.com and install it like any normal desktop app.
If you already use VS Code, Cursor should feel familiar because the interface and shortcuts are very similar.
Good prompts
- "Add a blue submit button below the form with rounded corners and a loading state."
- "Turn the home screen into a pricing page with three feature rows and one primary CTA."
- "Make the header sticky and add a soft backdrop blur when the page scrolls."
- "When the like button is tapped, increment the count and animate the icon from gray to red."
Prompts that make the AI guess
- "Make it better."
- "Clean this up."
- "Add some polish."
- "Fix the page."
Cursor vs Windsurf
Both work. Cursor is the easier recommendation here because it is familiar to VS Code users, fast at multi-file changes, and simple to explain in a step-by-step guide. If you prefer Windsurf, the same A1Zap workflow still applies.
Live preview
The local preview is what makes AI editing useful. Keep it running while you prompt, review, and save changes so you can instantly verify whether the UI is actually improving.
a1zap dev my-app
If you're already inside the app folder, a1zap dev is usually enough.
The terminal prints a URL like http://localhost:3100. Open that exact URL in your browser.
✔ Dev server running at http://localhost:3100
Leave the browser open next to your editor. Each save or accepted AI edit should refresh the page automatically.
Workflow tips
- Split your screen between Cursor and the browser.
- Keep the terminal visible for syntax errors.
- Use a second terminal tab for push commands.
What localhost means
localhost is your own computer. The preview is private and only visible on your machine until you push.
CLI reference
Run a1zap help any time to see this list in the terminal.
| Command | What it does |
|---|---|
a1zap config [apiKey] | Set or show your API key and workspace config |
a1zap list | List your apps and show which ones exist locally |
a1zap pull <app> | Download an existing app to your computer |
a1zap create <handle> | Create a new app from the starter template |
a1zap attach <app> | Attach a mini app to a community |
a1zap push [handle] | Upload your local changes to A1Zap |
a1zap dev [handle] | Run the live preview server with hot reload |
a1zap open <handle> | Print the local app path so you can cd into it |
a1zap help | Show all available commands |
Add --help to any command for more detail, for example a1zap create --help.
Need help? Go to the Developer CLI page to manage your API keys or reach out to support.