Getting Started

VibeHub is a spec-first development platform. Instead of writing code and documenting it afterward, you write feature specs in plain English and let an AI compiler generate the implementation.

Your specs live in a .vibe/ directory inside your project. They are version-controlled, reviewable, and portable — just like code, but readable by anyone.

The vibe CLI initializes projects, runs the compiler, and syncs with VibeHub.

# macOS / Linux
curl -fsSL https://getvibehub.com/install.sh | sh

You can start a project from the web or locally. The easiest way is to create one on getvibehub.com (sign in, describe your idea, done), then clone it locally:

vibe clone your-handle/my-app

Or start purely locally with vibe init:

mkdir my-app && cd my-app
vibe init my-app

Either way, you end up with a .vibe/ directory:

.vibe/
├── meta.json          # Project name, version
├── project.json       # Build/dev/test commands
├── remote.json        # Connection to VibeHub (if cloned)
├── features/
│   └── overview.md    # Your first feature spec
└── requirements/      # Tech stack & constraints

Feature specs are markdown files with YAML frontmatter. Open .vibe/features/overview.md and describe what your app should do:

---
Uses: []
Data: [User, Task]
Never:
  - Allow unauthenticated access to tasks
Connects: []
---

# Task Management

## What it does
Users can create, edit, and delete tasks. Each task has a
title, description, due date, and status (todo, in-progress, done).

## Behavior
- Tasks are scoped to the authenticated user
- Overdue tasks are highlighted in the UI
- Completing a task moves it to the bottom of the list

## Acceptance criteria
- User can create a task and see it in their list
- Changing status updates the UI immediately
- Deleting a task requires confirmation

Run the compiler to generate code from your specs. You'll need a Gemini API key:

export GEMINI_API_KEY=your-key-here
vibe compile

The compiler runs four phases: code generation, type checking, tests, and requirement validation. You'll see a report at the end showing what was generated and whether it passes.

If you created your project on VibeHub, you can also trigger a cloud compile from the web UI — no local API key needed.

If your project is connected to VibeHub (via vibe clone or VibeStudio), your specs sync between local and web. Changes you push from the desktop or CLI appear as reviewable updates on the web, where you and your team can review intent changes in plain English before merging.

The typical loop: edit specs locally, compile to verify, push to VibeHub for review, merge, repeat.

When you clone a project or connect VibeStudio to VibeHub, a few local config files are created inside your .vibe/ directory:

remote.json

Stores the connection to VibeHub: your owner handle, repo name, and the web URL. Created automatically by vibe clone or when you connect VibeStudio.

project.json

Build manifest — language, framework, and commands for install, dev, build, and test. Used by both the CLI compiler and VibeStudio.

meta.json

Project name, creation date, and version. Created by vibe init.

Authentication tokens for the desktop app are stored securely in your system's local storage (managed by VibeStudio). The CLI uses VIBEHUB_WEB_URL to know where to connect. All API requests from the desktop app and CLI use bearer token authentication, and the server verifies project ownership before allowing any writes.

• Read about core concepts like specs, snapshots, and lineage
• Learn how the compiler turns specs into working code
• Set up VibeStudio for a local editing experience
• See the full CLI reference