AKIS - Appwrite CLI Tool

AKIS is a CLI tool that automatically syncs your Appwrite collections with your TypeScript types. Define your types once, and AKIS creates/updates your collections and generates the corresponding schema.

Features

• Auto-generation: Creates Appwrite collections from your TypeScript types
• Synchronization: Detects differences between your types and Appwrite
• Auto-generated schema: The schema.ts file is automatically generated during migration
• Automatic indexes: Creates indexes for common fields (storeId, email, etc.)
• Dry-run mode: Preview changes before applying them

Installation

With npm

npm install @akis05/akis

With pnpm

pnpm add @akis05/akis

Global installation (optional)

npm install -g @akis05/akis

Configuration

1. Environment Variables

Create a .env file at the root of your project:

# Appwrite Endpoint (Cloud or Self-hosted)
APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1

# Your Appwrite project ID
APPWRITE_PROJECT_ID=your_project_id

# Your database ID
APPWRITE_DATABASE_ID=your_database_id

# API Key with Database permissions (Create, Read, Update, Delete)
APPWRITE_API_KEY=your_api_key

2. Getting Appwrite Credentials

1. Log in to Appwrite Console
2. Project ID: Settings → Project ID
3. Database ID: Databases → Click on your DB → Settings
4. API Key: Settings → API Keys → Create API Key (check Database permissions)

Quick Start

Step 1: Initialize the project

npx akis init

This command creates the following structure:

core/
└── appwrite-model/
    ├── types.ts              # Your TypeScript definitions
    ├── schema.ts             # Generated schema (do not edit manually)
    ├── client.ts             # Configured Appwrite client
    └── setup-collections.ts  # Utility functions

Step 2: Define your types

Edit core/appwrite-model/types.ts:

export type Client = {
  _id: string;              // Appwrite ID (required)
  _creationTime: number;    // Creation timestamp (required)
  name: string;             // Required field
  email?: string;           // Optional field (?)
  phone?: string;
  status: "active" | "inactive";  // Enum
  tags?: string[];          // String array
  storeId: string;
  createdAt: number;
  deletedAt?: number;
};

export type Product = {
  _id: string;
  _creationTime: number;
  name: string;
  price: number;
  quantity: number;
  category: "electronics" | "clothing" | "food";
  storeId: string;
  createdAt: number;
};

Step 3: Migrate to Appwrite

# Preview changes (recommended)
npx akis migrate --dry-run

# Create collections
npx akis migrate

Result:

• Collections created in Appwrite
• schema.ts file automatically generated

Step 4: Check status

npx akis status

Commands

akis init

Initializes the project structure.

npx akis init           # Create files
npx akis init --force   # Overwrite existing files

Options:

akis migrate

Creates missing collections in Appwrite and generates schema.ts.

npx akis migrate                    # Migrate all collections
npx akis migrate --name clients     # Migrate a specific collection
npx akis migrate --dry-run          # Preview without executing

Options:

Example output:

🚀 AKIS Migrate - Creating missing collections

📖 Reading types.ts...
   2 collection(s) to process

📡 Connecting to Appwrite...

📦 Creating clients...
   ✓ name
   ✓ email
   ✓ phone
   ✓ status
   ✓ storeId
   🔑 idx_storeId
   🔑 idx_email
   ✅ clients created

📝 schema.ts generated with 2 collections

✨ Migration complete: 1 created, 1 skipped

akis update

Adds new attributes to existing collections.

npx akis update                    # Update all collections
npx akis update --name clients     # Update a specific collection
npx akis update --dry-run          # Preview without executing

Options:

Use cases:

• You added a new field in types.ts
• You want to sync without recreating the collection

akis status

Compares local types with Appwrite collections.

npx akis status                    # View all collections
npx akis status --name clients     # View a specific collection

Options:

Example output:

📊 AKIS Status - Collection Status

┌─────────────────────────────┬────────┬────────────┬─────────────┐
│ Collection                  │ Status │ Attributes │ Missing     │
├─────────────────────────────┼────────┼────────────┼─────────────┤
│ clients                     │ ✅     │ 9/9        │ 0           │
│ products                    │ ⚠️     │ 5/7        │ 2           │
│ orders                      │ ❌     │ -          │ -           │
└─────────────────────────────┴────────┴────────────┴─────────────┘

📈 Summary:
   ✅ 1 synchronized
   ⚠️  1 needs update (akis update)
   ❌ 1 missing (akis migrate)

akis delete

Deletes collections in Appwrite.

npx akis delete --name clients     # Delete a collection (with confirmation)
npx akis delete --force            # Delete ALL collections without confirmation
npx akis delete --name clients -f  # Delete without confirmation

Options:

⚠️ Warning: This action is irreversible!

Supported TypeScript Types

AKIS automatically recognizes the following types:

Naming Conventions

AKIS automatically infers certain properties:

System Fields (ignored)

These fields are automatically ignored as they are managed by Appwrite:

• _id - Document ID
• _creationTime - Creation timestamp

Recommended Workflow

┌─────────────────────────────────────────────────────────────┐
│  1. Define types in types.ts                                │
│     export type Client = { ... }                            │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  2. Preview changes                                         │
│     npx akis migrate --dry-run                              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  3. Migrate to Appwrite                                     │
│     npx akis migrate                                        │
│     → Collections created + schema.ts generated             │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  4. Verify synchronization                                  │
│     npx akis status                                         │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│  5. Adding new fields? → Back to step 1                     │
│     npx akis update                                         │
└─────────────────────────────────────────────────────────────┘

Using with pnpm

If you use pnpm, add a script to your package.json:

{
  "scripts": {
    "akis": "akis"
  }
}

Then use:

pnpm akis status
pnpm akis migrate
pnpm akis update

Examples

Complete types.ts Example

/* ═══════════════════════════════════════════════════════════
   Types for my application
   ═══════════════════════════════════════════════════════════ */

export type Client = {
  _id: string;
  _creationTime: number;
  name: string;
  email?: string;
  phone?: string;
  address?: string;
  status: "active" | "inactive" | "prospect";
  discount?: number;
  tags?: string[];
  storeId: string;
  createdAt: number;
  deletedAt?: number;
};

export type Product = {
  _id: string;
  _creationTime: number;
  name: string;
  description?: string;
  price: number;
  costPrice?: number;
  quantity: number;
  minStock?: number;
  category: "electronics" | "clothing" | "food" | "other";
  image?: string;
  storeId: string;
  createdAt: number;
};

export type Sale = {
  _id: string;
  _creationTime: number;
  number: string;
  clientId?: string;
  lines: string;  // Stringified JSON
  total: number;
  status: "draft" | "validated" | "paid" | "cancelled";
  storeId: string;
  createdAt: number;
};

// Utilities
export type NewDoc<T> = Omit<T, "_id" | "_creationTime">;
export type UpdateDoc<T> = Partial<Omit<T, "_id" | "_creationTime">>;

Troubleshooting

Error: APPWRITE_API_KEY not configured

Check that your .env file exists and contains the API key:

cat .env | grep APPWRITE_API_KEY

Error: Collection not found in types.ts

Make sure the type name corresponds to a name recognized by AKIS:

• Client → clients
• Product → products
• Sale → sales

Attributes are not created

Appwrite has size limits for attributes. Check:

• String size (max 16000 characters)
• Number of attributes per collection (max ~100)

License

MIT

Links

• Appwrite Documentation
• npm Package
• GitHub Issues