appwrite-ctl

Appwrite Ctl

A Node.js (ESM) package to manage Appwrite infrastructure via Version Snapshots. Uses the Appwrite CLI for schema pull/push operations and the Appwrite SDK for data migration scripts.

Features

• Version Control for Appwrite Schema: Manage your appwrite.config.json snapshots alongside your code.
• CLI-based Snapshots: Uses appwrite-cli pull/push for reliable schema synchronization.
• Data Migrations: Execute TypeScript or JavaScript migration scripts (up and down) using the Node.js SDK.
• State Management: Tracks applied migrations in a dedicated Appwrite collection (system.migrations).
• Attribute Polling: Ensures schema attributes are available before running data scripts.
• Security Rules & Exceptions Ledger: Define security rules for collections and buckets; document intentional exceptions with author and justification — all stored in appwrite-ctl.config.json and surfaced in generated docs.
• Schema Documentation: Auto-generate ER diagrams and detailed collection docs from any snapshot.

Installation

npm install -g appwrite-ctl
# or
npm install --save-dev appwrite-ctl

From Repository

npm install github:bfbechlin/appwrite-ctl

Prerequisites

• Node.js: v18 or higher.
• Appwrite CLI: Installed globally (npm install -g appwrite-cli). The tool configures the CLI automatically using API key — no interactive login required.
• Environment Variables:

APPWRITE_ENDPOINT=https://cloud.appwrite.io/v1
APPWRITE_PROJECT_ID=your_project_id
APPWRITE_API_KEY=your_api_key

Architecture

The tool uses a clear separation of concerns:

Operation	Tool	Why
Schema snapshots (pull/push)	Appwrite CLI	Has full serialization/deserialization of schemas via appwrite.config.json
Data migrations (up/down)	Appwrite SDK	Provides programmatic access to databases, documents, etc.
Migration tracking	Appwrite SDK	Creates/reads documents in the system.migrations collection

CLI Usage

# Default (uses .env)
npx appwrite-ctl migrations run

# Custom environment file
npx appwrite-ctl migrations run --env .env.prod

Quick Start

1. Initialize the Project

npx appwrite-ctl init

Creates:

• appwrite/ directory
• appwrite/migration/ directory
• appwrite/appwrite-ctl.config.json — unified configuration file (migration settings + security rules)

2. Setup System Collection

npx appwrite-ctl migrations setup

3. Create a Migration

npx appwrite-ctl migrations create

This command:

• Creates appwrite/migration/vN/ (auto-increments version).
• Generates an index.ts file with a boilerplate migration script.
• Pulls the current appwrite.config.json from Appwrite via CLI.
• Auto-generates docs.md for the new version and updates appwrite/docs.md.

Folder Structure:

/appwrite
  appwrite-ctl.config.json     <-- Unified config (migration + security rules/exceptions)
  appwrite.config.json         <-- Appwrite CLI snapshot (latest, temporary)
  docs.md                      <-- Generated by `docs` command
  /migration
    /v1
      index.ts                 <-- Migration logic (SDK)
      appwrite.config.json     <-- Schema snapshot (CLI format)
      docs.md                  <-- Auto-generated on create/update
    /v2
      index.ts
      appwrite.config.json
      docs.md

4. Edit Migration Logic

import { Migration } from 'appwrite-ctl';

const migration: Migration = {
  id: 'uuid-generated-id',
  description: 'Update finance schema',

  up: async ({ client, databases, log }) => {
    log('Seeding initial data...');
    await databases.createDocument('db', 'users', 'unique()', {
      name: 'Admin',
      role: 'admin',
    });
  },

  down: async ({ client, databases, log }) => {
    // Logic to revert changes
  },
};

export default migration;

5. Update a Snapshot

After making schema changes in the Appwrite console, update a migration version's snapshot:

npx appwrite-ctl migrations update v1

This pulls the current state from Appwrite via CLI and saves it as the version's appwrite.config.json.

6. Run Migrations

npx appwrite-ctl migrations run

The runner performs these steps for each pending version:

• Configure CLI: Sets endpoint, project-id, and API key on appwrite-cli.
• Schema Push: Pushes the version's appwrite.config.json via CLI (tables, buckets, teams, topics).
• Polling: Waits for all schema attributes to become available (via SDK), with a 2-minute timeout per collection.
• Execution: Runs the up function defined in index.ts (via SDK).
• Finalization: Records the migration as applied.

7. Check Status

npx appwrite-ctl migrations status

8. Generate Schema Docs

# Pull latest state from Appwrite and generate docs → appwrite/docs.md
npx appwrite-ctl docs

# Generate from a stored local snapshot (no Appwrite connection needed)
npx appwrite-ctl docs v1

Generates a Markdown file with:

• ER diagrams (Mermaid) for each database (system database excluded)
• Collection details: columns, types, defaults, indexes, permissions, relationships
• Buckets: storage configuration summary
• Security exception callouts inline where exceptions have been recorded

Note: Docs are also auto-generated inside the version folder (vN/docs.md) when running migrations create or migrations update.

Security Exceptions Ledger

When a resource intentionally deviates from security best-practices, document it explicitly in the security.exceptions block of appwrite-ctl.config.json — it persists across all snapshot operations.

[!IMPORTANT] appwrite-ctl.config.json should be committed to version control — it is the team's audit trail for security exceptions.

Integration with Docs

When docs (or migrations create / migrations update) generates docs.md, it reads security.exceptions and injects a > [!WARNING] callout after each affected collection or bucket.

Adding Exceptions via CLI

npx appwrite-ctl exceptions add

Walk through the prompts — the rule is selected from the configured rules list, and the author is resolved automatically from git config user.name or your OS username.

Listing Exceptions

npx appwrite-ctl exceptions list

Prints a formatted table of every recorded exception grouped by type and resource ID.

Configuration (appwrite/appwrite-ctl.config.json)

All tool configuration lives in a single file at appwrite/appwrite-ctl.config.json. It is created automatically by appwrite-ctl init.

{
  "collection": "migrations",
  "database": "system",
  "security": {
    "rules": {
      "require-row-security": { "enabled": true, "severity": "error" },
      "forbid-role-all-write": { "enabled": true, "severity": "error" },
      "forbid-role-all-delete": { "enabled": true, "severity": "error" },
      "forbid-role-all-read": { "enabled": true, "severity": "warn" },
      "forbid-role-all-create": { "enabled": true, "severity": "warn" },
      "require-file-security": { "enabled": true, "severity": "warn" }
    },
    "exceptions": {
      "collections": {},
      "buckets": {}
    }
  }
}

Field	Description
collection	ID of the migrations tracking collection.
database	ID of the database where migrations are tracked (default: system).
security.rules	Map of rule IDs to { enabled, severity }. Severity: "error" | "warn" | "off".
security.exceptions	Documented bypasses per resource (see Security Exceptions Ledger above).

CI/CD & Automated Deployment

• Install Appwrite CLI: npm install -g appwrite-cli
• Set environment variables: APPWRITE_ENDPOINT, APPWRITE_PROJECT_ID, APPWRITE_API_KEY
• The tool automatically configures the CLI via appwrite client --key — no login required.

Required API Key Scopes:

• collections.read, collections.write
• documents.read, documents.write
• attributes.read, attributes.write
• indexes.read, indexes.write

CLI Commands

Command	Description
init	Initialize the project folder structure and config.
migrations setup	Create the system database and migrations collection.
migrations create	Create a new migration version pulling the latest snapshot from Appwrite via CLI.
migrations update <version>	Update a version's snapshot by pulling from Appwrite via CLI.
migrations run	Execute all pending migrations in order.
migrations status	List applied and pending migrations.
docs [version]	Generate docs.md. Without a version, pulls live from Appwrite. With a version (e.g. v1), reads the stored local snapshot — no Appwrite connection needed.
exceptions add	Interactively add a security exception entry to appwrite-ctl.config.json.
exceptions list	List all security exceptions recorded in appwrite-ctl.config.json.

AI Rules

Understanding the Data Models Layer

📌 docs.md — The Source of Truth

The most important file for understanding the application's data model is:

appwrite/docs.md

This is an auto-generated Markdown file that documents the current state of every database, collection, attribute, relationship, index, and storage bucket in the Appwrite project. It is generated from the latest appwrite.config.json snapshot via the docs command.

When you need to understand the data model — always read appwrite/docs.md first.

It contains:

• ER Diagrams (Mermaid) — visual representation of collection relationships per database.
• Collections — complete list of every collection with:
  • Column names, types, required flags, defaults, and constraints.
  • Relationships: type (oneToMany, manyToOne, etc.), related collection, on-delete behavior, and two-way configuration.
  • Indexes: type (unique, key, fulltext), columns, and sort orders.
  • Permissions: read/write/create/delete access rules.
• Buckets — storage buckets with max file size, extensions, compression, encryption, and antivirus settings.
• Security exception callouts — [!WARNING] blocks embedded next to any resource with a recorded bypass.

Migration Commands

This project uses appwrite-ctl to manage schema migrations. The available commands are:

Command	Description
appwrite-ctl migrations create	Create a new migration version pulling the latest snapshot from Appwrite via CLI.
appwrite-ctl migrations update <version>	Pull the current Appwrite state and update a version's snapshot.
appwrite-ctl migrations run	Execute all pending migrations in order (push schema → poll attributes → run script).
appwrite-ctl migrations status	List applied and pending migrations.
appwrite-ctl docs	Pull the current Appwrite state and generate/regenerate docs.md.
appwrite-ctl docs <version>	Generate docs.md from a stored local snapshot (no Appwrite connection needed).

Each migration version lives in appwrite/migration/vN/ and contains:

• appwrite.config.json — the schema snapshot (Appwrite CLI format).
• index.ts — the migration script with up (and optional down) functions.
• docs.md — auto-generated docs for that version's snapshot.

How to Handle Data Model Changes

When a change to the data model is needed (e.g. adding a collection, modifying attributes, creating indexes), follow these steps:

• Create a new migration version:

  npx appwrite-ctl migrations create
  

  This creates appwrite/migration/vN/ and automatically pulls the current schema snapshot from Appwrite into appwrite.config.json via the CLI.

• Edit the snapshot (appwrite.config.json) inside the new version folder. Apply the desired schema changes directly to this JSON file — add/remove/modify collections, attributes, indexes, relationships, or buckets.

• Write the migration script in appwrite/migration/vN/index.ts if data manipulation is needed (e.g. seeding data, transforming existing documents). If the change is schema-only, the default empty up function is sufficient.

• Regenerate the schema docs:

  npx appwrite-ctl docs
  

  This updates appwrite/docs.md from the latest Appwrite state.

• Verify the updated appwrite/docs.md to confirm the changes are correct.

⚠️ Never edit docs.md files manually — they are auto-generated. Always modify the appwrite.config.json snapshot and run docs to regenerate.