@vaiftech/cli 1.1.0 → 1.2.0

package/README.md

@@ -1,120 +1,200 @@
 # @vaiftech/cli
 
-Command-line tools for VAIF Studio - a Backend-as-a-Service platform.
+[![npm version](https://img.shields.io/npm/v/@vaiftech/cli)](https://www.npmjs.com/package/@vaiftech/cli)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Command-line tools for [VAIF Studio](https://vaif.studio) - scaffold projects from templates, manage schemas, deploy functions, generate TypeScript types, and more.
 
 ## Installation
 
 ```bash
-npm install -D @vaiftech/cli
-# or
-pnpm add -D @vaiftech/cli
-# or
-yarn add -D @vaiftech/cli
+npm install -g @vaiftech/cli
+# or use directly with npx
+npx @vaiftech/cli init --template react-spa
 ```
 
-## Features
+## Quick Start
 
-### Type Generation
+```bash
+# Scaffold a new project from a template
+npx @vaiftech/cli init --template nextjs-fullstack
+
+# Or initialize a plain config
+vaif init
+
+# Authenticate with your VAIF account
+vaif login
 
-Generate TypeScript types from your VAIF database schema.
+# Pull your database schema and generate types
+vaif pull
+vaif generate
+
+# Deploy functions
+vaif functions deploy
+```
+
+## Templates
+
+Scaffold a fully configured VAIF Studio project with one command:
 
 ```bash
-npx vaif types generate --project <project-id> --output ./src/types/database.ts
+vaif init --template <name>
 ```
 
-#### Options
+Each template creates `vaif.config.json` plus platform-specific integration files (client setup, auth helpers, environment config).
+
+### Available Templates
 
-| Flag | Description | Default |
-|------|-------------|---------|
-| `--project` | Project ID | Required |
-| `--output` | Output file path | `./vaif.types.ts` |
-| `--env` | Environment (development, staging, production) | `development` |
+| Template | Description | Ecosystem |
+|----------|-------------|-----------|
+| `nextjs-fullstack` | Next.js app with server/client VAIF client, auth middleware, and React hooks | Next.js |
+| `react-spa` | React SPA with VaifProvider, hooks for queries/mutations, and env setup | React / Vite |
+| `ios-swift-app` | iOS app with VaifManager singleton, SwiftUI auth, and database helpers | Swift / iOS |
+| `expo-mobile-app` | React Native / Expo with realtime hooks, storage uploads, and push notifications | Expo |
+| `flutter-app` | Flutter app with VaifClient, auth flows, and typed database queries | Flutter / Dart |
+| `python-fastapi-backend` | FastAPI server with VAIF auth middleware, database queries, and storage uploads | Python |
+| `go-backend-api` | Go HTTP server with VAIF client, auth verification, and webhook handling | Go |
+| `todo-app` | Minimal React + VAIF starter for learning the basics | React |
+| `realtime-chat` | Real-time messaging app with presence tracking and live subscriptions | React |
+| `saas-starter` | SaaS foundation with teams, org management, auth, and billing hooks | React / Node.js |
+| `ecommerce-api` | E-commerce backend with products, orders, Stripe webhooks, and inventory | Node.js |
 
-#### Example Output
+```bash
+# List all templates
+vaif templates
 
-```typescript
-// Generated by @vaiftech/cli
+# Scaffold and overwrite existing files
+vaif init --template expo-mobile-app --force
+```
 
-export interface User {
-  id: string;
-  email: string;
-  name: string | null;
-  avatar_url: string | null;
-  created_at: string;
-  updated_at: string;
-}
+### What Templates Create
 
-export interface Post {
-  id: string;
-  title: string;
-  content: string;
-  author_id: string;
-  published: boolean;
-  created_at: string;
-  updated_at: string;
-}
+**JavaScript/TypeScript templates** (nextjs-fullstack, react-spa, etc.):
+- `vaif.config.json` - Project configuration
+- `lib/vaif.ts` or `src/lib/vaif.ts` - Client initialization
+- `.env.example` or `.env.local.example` - Environment variables
+- Platform-specific files (middleware, providers, hooks)
+- Prints `npm install` command with required dependencies
 
-export interface Database {
-  users: User;
-  posts: Post;
-}
+**Native/Backend templates** (ios-swift-app, flutter-app, python-fastapi-backend, go-backend-api):
+- `vaif.config.json` - Project configuration
+- Platform integration files (VaifManager.swift, vaif_client.py, etc.)
+- `.env.example` - Environment variables
+- `requirements.txt` / `README-VAIF.md` with setup instructions
+
+## Commands
+
+### Authentication
+
+```bash
+vaif login                           # Interactive login
+vaif login --token <api-token>       # Login with token
+vaif whoami                          # Show current user
+vaif logout                          # Log out
 ```
 
-### Programmatic Usage
+### Project Setup
 
-```typescript
-import { generateTypes } from '@vaiftech/cli';
+```bash
+vaif init                            # Create vaif.config.json
+vaif init --template react-spa       # Scaffold from template
+vaif init --typescript               # Setup for TypeScript
+vaif init --force                    # Overwrite existing config
+```
 
-const types = await generateTypes({
-  projectId: 'proj-123',
-  apiKey: 'vaif_sk_xxx',
-  baseUrl: 'https://api.vaif.io',
-});
+### Project Info
 
-// types is a string containing TypeScript definitions
-console.log(types);
+```bash
+vaif info                            # Project details (name, region, URLs)
+vaif status                          # Tables, functions, storage, connections
 ```
 
-## Configuration
+### Schema Management
+
+```bash
+vaif pull                            # Pull database schema from remote
+vaif push                            # Push local schema changes
+vaif push --dry-run                  # Preview changes without applying
+```
 
-Create a `vaif.config.js` file in your project root:
+### Type Generation
 
-```javascript
-module.exports = {
-  projectId: 'proj-123',
-  output: './src/types/vaif.ts',
-};
+```bash
+vaif generate                        # Generate TypeScript types
+vaif generate --output ./types.ts    # Custom output path
+vaif generate --dry-run              # Preview without writing
+vaif gen                             # Alias
 ```
 
-Then run without flags:
+### Functions
 
 ```bash
-npx vaif types generate
+vaif functions deploy                # Deploy all functions
+vaif functions deploy --name myFunc  # Deploy specific function
+vaif functions list                  # List deployed functions
+vaif fn ls                           # Alias
 ```
 
-## Usage with @vaiftech/client
+### Database
 
-Use generated types with the client SDK:
+```bash
+vaif db push                         # Push Drizzle migrations
+vaif db pull                         # Pull remote schema
+vaif db seed                         # Seed with test data
+vaif db seed --truncate              # Truncate before seeding
+vaif db reset --force                # Reset database (destructive)
+```
 
-```typescript
-import { createVaifClient } from '@vaiftech/client';
-import type { User, Post, Database } from './types/vaif';
+### API Keys
 
-const vaif = createVaifClient({
-  baseUrl: 'https://api.myproject.vaif.io',
-  apiKey: 'vaif_pk_xxx',
-});
+```bash
+vaif keys generate                   # Generate new API key
+vaif keys generate --name "Prod"     # Named key
+vaif keys list                       # List all keys
+```
 
-// Fully typed queries
-const users = await vaif.from<User>('users').list();
-const post = await vaif.from<Post>('posts').eq('id', 'post-123').single();
+## Configuration
+
+`vaif.config.json` (created by `vaif init`):
+
+```json
+{
+  "$schema": "https://vaif.studio/schemas/config.json",
+  "projectId": "your-project-id",
+  "database": {
+    "url": "${DATABASE_URL}",
+    "schema": "public"
+  },
+  "types": {
+    "output": "./src/types/database.ts"
+  },
+  "api": {
+    "baseUrl": "https://api.vaif.studio"
+  }
+}
 ```
 
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `VAIF_API_URL` | API base URL (default: `https://api.vaif.studio`) |
+| `VAIF_TOKEN` | API token (alternative to `vaif login`) |
+| `VAIF_PROJECT_ID` | Default project ID |
+
 ## Related Packages
 
-- [@vaiftech/client](https://www.npmjs.com/package/@vaiftech/client) - Core client SDK
-- [@vaiftech/react](https://www.npmjs.com/package/@vaiftech/react) - React hooks
-- [@vaiftech/sdk-expo](https://www.npmjs.com/package/@vaiftech/sdk-expo) - React Native/Expo SDK
+| Package | Description |
+|---------|-------------|
+| [@vaiftech/client](https://www.npmjs.com/package/@vaiftech/client) | TypeScript SDK - database, auth, realtime, storage, functions |
+| [@vaiftech/auth](https://www.npmjs.com/package/@vaiftech/auth) | Standalone auth SDK - OAuth, MFA, sessions |
+| [@vaiftech/react](https://www.npmjs.com/package/@vaiftech/react) | React hooks - useAuth, useQuery, useRealtime |
+| [@vaiftech/sdk-expo](https://www.npmjs.com/package/@vaiftech/sdk-expo) | React Native / Expo SDK |
+| [@vaiftechnologies/vaif-client](https://www.npmjs.com/package/@vaiftechnologies/vaif-client) | JavaScript SDK |
+
+## Documentation
+
+Full documentation at [docs.vaif.studio](https://docs.vaif.studio).
 
 ## License