appwrite-utils-cli
Advanced tools
Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.
appwrite-utils-cli is a powerful, YAML-first command-line interface tool designed for Appwrite developers who need to manage database migrations, schema generation, data import, and comprehensive project management. Built on a modular architecture with enhanced performance, this CLI tool facilitates complex tasks like setting up databases, running migrations, generating schemas, and managing backups efficiently. With version 1.0.0, the CLI introduces a completely refactored import system with 50%+ complexity reduction, YAML-first configuration, and sophisticated data handling capabilities.
To use appwrite-utils-cli, you can install it globally via npm to make it accessible from anywhere in your command line:
npm install -g appwrite-utils-cli
However, due to the rapid development of this project, it's recommended to use the following command:
npx --package=appwrite-utils-cli@latest appwrite-migrate [options]
Note: Do not install this locally into your project. It is meant to be used as a command-line tool only.
Version 1.0.0 introduces a YAML-first approach for better cross-platform compatibility and enhanced developer experience.
The CLI automatically detects configuration files in this order:
.appwrite/config.yaml (recommended)appwrite.yamlappwriteConfig.ts (legacy, still supported)# .appwrite/config.yaml with JSON Schema support
# yaml-language-server: $schema=./.yaml_schemas/appwrite-config.schema.json
appwriteEndpoint: "https://cloud.appwrite.io/v1"
appwriteProject: "your-project-id"
appwriteKey: "your-api-key"
databases:
- name: "main"
id: "main"
collections:
- name: "Users"
id: "users"
attributes:
- key: "email"
type: "string"
required: true
format: "email"
buckets:
- name: "documents"
id: "documents"
permissions:
- target: "any"
permission: "read"
logging:
enabled: false # Disabled by default
level: "info"
console: true
After installation, you can access the tool directly from your command line using the provided commands.
Run the CLI in interactive mode with enhanced visual feedback:
npx --package=appwrite-utils-cli@latest appwrite-migrate --it
This provides a professional guided experience with:
You can also use specific flags to run tasks without the interactive prompt:
npx --package=appwrite-utils-cli@latest appwrite-migrate [options]
Version 1.0.0 introduces a powerful YAML-based import system with sophisticated data handling capabilities.
# .appwrite/import/users-import.yaml
# yaml-language-server: $schema=../.yaml_schemas/import-config.schema.json
source:
file: "importData/users.json"
basePath: "RECORDS"
type: "json"
target:
collection: "Users"
type: "create"
primaryKey: "user_id"
createUsers: true
mapping:
attributes:
- oldKey: "user_id"
targetKey: "userId"
converters: ["anyToString"]
validation:
- rule: "required"
params: ["{userId}"]
- oldKey: "profile_image_url"
targetKey: "avatar"
fileData:
path: "{profile_image_url}"
name: "{user_id}_avatar"
afterImport:
- action: "createFileAndUpdateField"
params: ["{dbId}", "{collId}", "{docId}", "avatar", "{bucketId}", "{filePath}", "{fileName}"]
relationships:
- sourceField: "department_id"
targetField: "departmentId"
targetCollection: "Departments"
options:
batchSize: 50
continueOnError: true
Available options:
--it: Run in interactive mode with enhanced visual feedback--setup: Create setup files (supports both YAML and TypeScript)--generate: Generate TypeScript and JSON schemas from database configurations--import: Import data using YAML configurations with advanced processing--backup: Comprehensive backup with progress tracking and detailed reporting--dbIds: Comma-separated list of database IDs to operate on--collectionIds: Comma-separated list of collection IDs to operate on--bucketIds: Comma-separated list of bucket IDs to operate on--wipe: Wipe data with smart confirmation (all: everything, docs: only documents, users: only user data)--wipeCollections: Non-destructively wipe specified collections--writeData: Write converted imported data to file for validation--push: Push local YAML/TypeScript config to Appwrite project--sync: Synchronize by pulling config from Appwrite project--endpoint: Set the Appwrite endpoint--projectId: Set the Appwrite project ID--apiKey: Set the Appwrite API key--transfer: Transfer data between databases or collections with progress tracking--transfer-users: Transfer users between instances (will not overwrite)--fromDbId / --sourceDbId: Source database ID for transfer--toDbId / --targetDbId: Destination database ID for transfer--fromCollectionId: Source collection ID for transfer--toCollectionId: Destination collection ID for transfer--fromBucketId: Source bucket ID for transfer--toBucketId: Destination bucket ID for transfer--remoteEndpoint: Remote Appwrite endpoint for transfers--remoteProjectId: Remote Appwrite project ID for transfers--remoteApiKey: Remote Appwrite API key for transfers--updateFunctionSpec: Update function specifications--functionId: Function ID to update--specification: New function specification (s-0.5vcpu-512mb to s-8vcpu-8gb)--generateConstants / --constants: Generate cross-language constants files with database, collection, bucket, and function IDs--constantsLanguages: Comma-separated list of languages for constants generation (default: typescript)
typescript, javascript, python, php, dart, json, env--constantsOutput: Output directory for generated constants files (default: config-folder/constants)Generate cross-language constants files for all your Appwrite resource IDs:
# Generate TypeScript constants (default)
npx appwrite-utils-cli appwrite-migrate --generateConstants
# Generate multiple language formats
npx appwrite-utils-cli appwrite-migrate --generateConstants --constantsLanguages="typescript,python,php,json"
# Generate all available formats
npx appwrite-utils-cli appwrite-migrate --generateConstants --constantsLanguages="typescript,javascript,python,php,dart,json,env"
# Generate with custom output directory
npx appwrite-utils-cli appwrite-migrate --generateConstants --constantsOutput="./my-constants"
This generates constants files in your configuration directory (e.g., .appwrite/constants/) containing:
Example TypeScript output:
export const DATABASE_IDS = {
MAIN_DATABASE: "main"
} as const;
export const COLLECTION_IDS = {
USERS: "01JYDBQTB5W8SCBAYB654CCADQ",
POSTS: "01JYDBQTB5W8SCBAYB654POSTS"
} as const;
// Type helpers and utility arrays included
export type DatabaseId = typeof DATABASE_IDS[keyof typeof DATABASE_IDS];
Transfer databases within the same project or from a local to a remote project:
npx appwrite-utils-cli appwrite-migrate --transfer --fromDbId sourceDbId --toDbId targetDbId --remoteEndpoint https://appwrite.otherserver.com --remoteProjectId yourProjectId --remoteApiKey yourApiKey
Transfer specific collections from one place to another, with all of their data:
npx appwrite-utils-cli appwrite-migrate --transfer --fromDbId sourceDbId --toDbId targetDbId --fromCollectionId sourceCollectionId --toCollectionId targetCollectionId --remoteEndpoint https://appwrite.otherserver.com --remoteProjectId yourProjectId --remoteApiKey yourApiKey
Transfer files between buckets:
npx appwrite-utils-cli appwrite-migrate --transfer --fromBucketId sourceBucketId --toBucketId targetBucketId --remoteEndpoint https://appwrite.otherserver.com --remoteProjectId yourProjectId --remoteApiKey yourApiKey
NOTE: IF IT DOES NOT WORK AND YOU ARE SELF-HOSTED, PLEASE SET MAX CPU_PER_FUNCTION AND RAM_PER_FUNCTION IN YOUR ENV VARS TO > 0, THIS IS A BUG IN 1.6.0 -- YOU SET THE FUNCTION RAM IN MB
Update the CPU and RAM specifications for a function:
npx appwrite-utils-cli appwrite-migrate --updateFunctionSpec --functionId yourFunctionId --specification s-1vcpu-1gb
Available specifications:
If you run out of RAM during large data imports, you can increase Node's memory allocation:
export NODE_OPTIONS="--max-old-space-size=16384"
This sets the allocation to 16GB. For most cases, 8GB (8192) should be sufficient.
The CLI now supports OpenAPI generation for each attribute in the schema. Add a description to any attribute or collection, and it will export that schema to the appwrite/openapi folder.
This updated CLI ensures that developers have robust tools at their fingertips to manage complex Appwrite projects effectively from the command line, with both interactive and non-interactive modes available for flexibility.
🔧 Robust Transfer Operations with Status Monitoring
transferDatabaseLocalToRemote to use new attribute and index creationBreaking Change: None - fully backward compatible with significantly enhanced reliability.
🔐 Complete Password Hash Preservation During User Transfers
create*User method based on detected hash typehashOptionsuser.hash field determines creation methoduser.hashOptions provides algorithm parameters# Users will now preserve passwords during comprehensive transfer
npx appwrite-utils-cli@latest appwrite-migrate --it
# Select: 🚀 Comprehensive transfer (users → databases → buckets → functions)
# Example output:
# ✅ User 123 created with preserved argon2 password
# ✅ User 456 created with preserved bcrypt password
# ⚠️ User 789 created with temporary password - password reset required
Breaking Change: None - fully backward compatible with enhanced capabilities.
🚀 Complete Cross-Instance Transfer Solution
🚀 Comprehensive transfer (users → databases → buckets → functions) in interactive mode# Interactive mode - select comprehensive transfer
npx appwrite-utils-cli@latest appwrite-migrate --it
# Example rate limiting at 20 concurrent:
# - General operations: 20 concurrent
# - User operations: 10 concurrent
# - File operations: 5 concurrent
Benefits:
🚀 Enhanced Developer Experience with Multi-Language Constants
as const and helper types{config-folder}/constants/ by default--generateConstants with language and output options# Default TypeScript generation
npx appwrite-utils-cli appwrite-migrate --generateConstants
# Multi-language generation
npx appwrite-utils-cli appwrite-migrate --generateConstants --constantsLanguages="typescript,python,php,json"
# All formats with custom output
npx appwrite-utils-cli appwrite-migrate --generateConstants --constantsLanguages="typescript,javascript,python,php,dart,json,env" --constantsOutput="./constants"
Migration Benefits:
🚀 Enhanced Function Management & Type System Fixes
__dirname is not defined error when creating function templatestypescript-node: Node.js 21.0, TypeScript build setup, 0.5vCPU/512MBuv: Python 3.12, UV package manager, 0.5vCPU/512MBcount-docs-in-collection: Node.js 21.0, specialized counting function, 1vCPU/512MB.appwrite/collections/ regardless of config locationMigration Notes:
🎉 Major Release - Comprehensive Architecture Overhaul
.appwrite/config.yaml, appwrite.yaml, or appwriteConfig.ts.appwrite directory structureDataTransformationService - Pure data transformation logicFileHandlerService - URL downloads and local file handlingUserMappingService - Sophisticated email/phone deduplicationValidationService - Centralized validation with detailed reportingRelationshipResolver - Cross-collection ID mappingImportOrchestrator - High-level coordinationdataInsertion: 5 (concurrent document creation)fileUpload: 2 (conservative for large files)validation: 10 (pre-import validation)dataQuery: 25 (relationship resolution). directories being ignored. Normally a good thingappwriteConfig.yaml being the name for the converted config, instead of config.yaml--it so it detects when you can migrate your configMigration Note: While fully backward compatible, we recommend migrating to YAML configuration for the best experience. Use --setup to generate new YAML configurations.
selectCollections not always filtering by databaseIdwipeCollectionlodash import, replaced with es-toolkitwipeCollection -- it wasn't properly deleting all files in a loopappwrite-utils reqattributesSame so it will properly update attributes that have changedappwriteConfig.ts if you set API Key, ProjectId, and Endpoint__dirname--transfer-users phones--transfer-users boolean flag to also transfer users between projectsignore always being an empty array, if not set, so it properly ignores the defaults__pycache__ and .venv to default ignoresDeploy Function(s) not ignoring things properlycollectLocalFunctions function was failing to add the scopes and a few others to the function, accidentally, fixed nowDeploy Function(s) also update the functions, as not all things (timeout, specification, etc.) are updated via deployignore to the Functions config, to specify what to ignore when creating the .tar.gz filenode_modules and a few others to the ignoresyncDb to push the configurations properly, accidentally hurt it during synchronizeConfigurationswipeCollection to handle errors gracefullypredeployCommands to workdeployFunction to not updateConfig if it's already presentsynchronize configurations for functions, now you do not need to deploy the function first./functions in addition to appwriteConfigFolder/functions--targetDbId and --sourceDbId as aliasesupdateFunctionSpecifications resetting functions to default with undefined values (oops)updateFunctionSpecifications which lists functions and specifications to allow you to update your functions max CPU and RAM usage per-functiontransferFilesLocalToLocal and remote if a document exists with that $id, also fixed wipe "all" option also wiping the associated bucketsafterImportActions not resolvingtryAwaitWithRetry to catch 522 errors from Cloudflare, they were appearing for some users, also added a 1000ms delay to tryAwaitWithRetryappwrite-utilsselectDatabases and selectCollections from the interactive CLI to prefer local collections or databases when synchronizing the databasescreateOrUpdateAttributes so it deletes attributes that don't exist in local config when you are running syncDb. Also updated the database and collection selection, so it won't try and fetch the collections and databases that don't exist (ones you picked from local config) and errordefault...???)node-appwrite to 14, this seems to fix the xdefault errorupdateStringAttribute is fixed -- it just deletes them nowupdateStringAttribute bug$createdAt and $updatedAt to string from string | Date cause honestly if you want a date just parse itnode-appwrite@14 for appwrite 1.6.0100ms) between collection deletions, reduced other delays from 1000 to 500/250msfetch failed errors during large-scale collection creationappwriteConfig.ts file from causing error (you want to be able to setup yeah? haha)--backup support, even if only one databaseworkspace issueulid for ulidx, fixing compatibility issuesnode-appwrite versionniceidMappings now supports arrays.updates in importDef's update mappings overwriting postImportActions from the originaldataLoader's idMapping's giving me issuesdocumentExists check to batch creation functionality to try to prevent duplicatesmergeObjectsdataLoader not mapping updates correctly with updateMapping--transfer, --fromdb <targetDatabaseId>, --targetdb <targetDatabaseId>, --transferendpoint <transferEndpoint>, --transferproject <transferProjectId>, --transferkey <transferApiKey>. Additionally, I've added --fromcoll <collectionId> and --targetcoll <collectionId>. These allow you to do a few things. First, you can now transfer databases in the same project, and from local to a remote project. Second, you can now specify specific collections to transfer from one place to another, with all of their data. If --fromcoll and --targetcoll are ommitted, it will transfer the databases. During the database transfer, it will create any missing collections, attributes, and indices.tryAwaitWithRetry for fetch failed and others like it errors (looking at you server error) -- this should prevent things from going sideways.documentSecurity, enabled, and $id to the init collectiondocumentSecurity and enabled), also added a check for fetch failed errors to retry them with recursion, not sure how well that will work out, but we're gonna try it! It will still fail after 5 tries, but hopefully that gives Appwrite some time to figure it's stuff outbin section of the package.json, apparently you can't use node to run itidMappings, if you are importing data and use the idMappings functionality, you can set a fieldToSet based on the value of a sourceField in the current imported items data (whether it's in the final data or the original), in order to match another field in another collection. So if you had a store, and it had items and the items have a Region ID for instance. You can then, in your regionId of the items, setup an idMapping that will allow you to map the value of the targetField based on the value of the targetFieldToMatch in the targetCollection. Sounds complex, but it's very useful. Like psuedo-relationship resolution, without the relationships.description variable in an attribute and collection, it'll add that description to the generated schemas. This assumes you have zod-to-openpiformat into consideration from the database (URL's are not of type: "url", they are of format: "url")--sync, added optional OpenAPI generation (in progress, almost done, but wanted to push other changes), added --endpoint, --project, --key as optional parameters to change the target destination (shoutout to pingu24k for pointing out these bugs and suggesting those changes for endpoint customization)--sync to synchronize your Appwrite instance with your local appwriteConfig.yaml and generate schemas--writeData (or --write-data) to command to write the output of the import data to a file called dataLoaderOutput in your root dirpostImportActions and Relationship Resolution to the local data import, so it should be much faster.setTargetFieldFromOtherCollectionDocumentsByMatchingField for the below, but setting a different field than the field you matched. The names are long, but at least you know what's going on lmao.setFieldFromOtherCollectionDocuments to set an array of ID's for instance from another collection as a postImportActionFAQs
Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.
The npm package appwrite-utils-cli receives a total of 24 weekly downloads. As such, appwrite-utils-cli popularity was classified as not popular.
We found that appwrite-utils-cli demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
North Korean threat actors deploy 67 malicious npm packages using the newly discovered XORIndex malware loader.
Security News
Meet Socket at Black Hat & DEF CON 2025 for 1:1s, insider security talks at Allegiant Stadium, and a private dinner with top minds in software supply chain security.
Security News
CAI is a new open source AI framework that automates penetration testing tasks like scanning and exploitation up to 3,600× faster than humans.