Appwrite CLI
The Appwrite CLI is a command-line application that allows you to interact with the Appwrite server and perform server-side tasks using your terminal. This includes creating and managing projects, managing resources (documents, files, users), creating and deploying Cloud Functions, and other operations available through Appwrite's API.
Installation
The CLI is packaged both as an npm module as well as a standalone binary for your operating system, making it completely dependency free, platform independent and language agnostic.
If you plan to use the CLI to initialize new Cloud Functions, ensure that Git is installed on your machine.
Install with NPM
If you have npm set up, run the command below to install the CLI
npm install -g appwrite-cli
Install with Script
For a completely dependency-free installation, the CLI also ships with a convenient installation script for your operating system
-
MacOS
Using Homebrew
brew tap appwrite/sdk-for-cli https://github.com/appwrite/sdk-for-cli brew update brew install --HEAD appwrite
or terminal
curl -sL https://appwrite.io/cli/install.sh | bash
-
Windows
iwr -useb https://appwrite.io/cli/install.ps1 | iex
-
Linux
curl -sL https://appwrite.io/cli/install.sh | bash
After the installation is complete, verify the install using
appwrite -v
The next step is to have your Appwrite server running. You can grab our simple installation command and execute it. Now, we're all set to play around with the CLI.
Getting Started
Before you can use the CLI, you need to login to your Appwrite account using
appwrite login
Initializing Your Project
After you're logged in, the CLI needs to be initialized with your Appwrite project. You can initialize the CLI using:
appwrite init project
The following prompts will guide you through the setup process. The init command also creates an appwrite.json file representing your Appwrite project.
You can also fetch all the collections in your current project using
appwrite init collection
Deploying Cloud Functions
The CLI also handles the creation and deployment of Appwrite's Cloud Functions. You can initialize a new function using
appwrite init function
? What would you like to name your function? My Awesome Function
? What runtime would you like to use? Node.js (node-15.5)
✓ Success
This command creates a new function My Awesome Function in your current Appwrite project and also creates a template function for you to get started. You can now deploy this function using:
appwrite deploy function
? Which functions would you like to deploy? Awesome Function (621229798628cf5bf712)
ℹ Info Deploying function Awesome Function ( 621229798628cf5bf712 )
✓ Success Deployed Awesome Function ( 621229798628cf5bf712 )
Deploying collections
The Appwrite CLI also helps you migrate your project's collections from a development server to a production server. You can deploy all the collections in your appwrite.json file using:
appwrite deploy collections
Self-Signed Certificates
By default, requests to domains with self-signed SSL certificates (or no certificates) are disabled. If you trust the domain, you can bypass the certificate validation using
appwrite client --selfSigned true
The appwrite.json File
An appwrite.json file is created by the CLI when you initialize your project. It stores all the configuration for the CLI to be able to interact with your Appwrite project. The file has a structure as depicted below. When using the appwrite deploy command, the CLI uses information from appwrite.json to deploy your functions and collections.
{
"projectId": "6213b54f2e76a06f2ec6",
"projectName": "My Awesome Project",
"functions": [
{
"$id": "6213b58cb21dda6c3263",
"name": "My Awesome Function",
"runtime": "node-17.0",
"path": "My Awesome Function",
"entrypoint": "src/index.js"
}
],
"collections": [
{
"$id": "6213bb2d567d8a206614",
"$permissions": [
"read(\"any\")",
"create(\"team:admin\")",
"update(\"team:admin\")",
"delete(\"team:admin\")",
],
"name": "Millenium Problems",
"enabled": true,
"documentSecurity": false,
"attributes": [],
"indexes": []
}
]
}
The appwrite.json file does the following things
- Provides context to the CLI
- Keeps track of all your Cloud Functions
- Keeps track of all your project's collections
- Helps you deploy your Appwrite project to production and more
Usage Examples
The Appwrite CLI follows the following general syntax.
appwrite [COMMAND] --[OPTIONS]
A complete list of supported commands can be found below.
Command | Description |
---|---|
login | The login command allows you to authenticate a user into the CLI |
init | The init command helps you initialize your Appwrite project, functions and collections |
deploy | The deploy command provides a convenient wrapper for deploying your functions and collections |
logout | The logout command allows you to logout from the CLI |
projects | The projects command allows you to view, create and manage your Appwrite projects |
storage | The storage command allows you to manage your project files |
teams | The teams command allows you to group users of your project and to enable them to share read and write access to your project's resources |
users | The users command allows you to manage your project users |
client | The client command allows you to configure your CLI |
account | The account command allows you to authenticate and manage a user account |
avatars | The avatars command aims to help you complete everyday tasks related to your app image, icons, and avatars |
functions | The functions command allows you view, create and manage your Cloud Functions |
databases | The databases command allows you to create structured collections of documents, query and filter lists of documents |
health | The health command allows you to both validate and monitor your Appwrite server's health |
locale | The locale command allows you to customize your app based on your users' location |
Here are a few sample commands to get you started
Create User
To create a new user in your project, you can use the `create` command. To successfully create a user, make sure your API key is granted with the scope "users.write".
appwrite users create --userId "unique()" --email hello@appwrite.io --password very_strong_password
List Users
To get a list of all your project users, you can use the `list` command. To successfully view the list, make sure your API key is granted with the scope "users.read".
appwrite users list
In case of errors with any command, you can get more information about what went wrong using the --verbose flag
appwrite users list --verbose
List Collections
To get a list of all your collections, you can use the `listCollections` command. To successfully view the list, make sure your API key is granted with the scope "collections.read".
appwrite databases listCollections
If you wish to parse the output from the CLI, you can request the CLI output in JSON format using the --json flag
appwrite databases listCollections --json
Get a Collection
To get more information on a particular collection, you can make use of the `getCollection` command and pass in the `collectionId`. To successfully fetch the collection, make sure your API key is granted with the scope "collections.read".
appwrite databases getCollection --collectionId 5ff468cfa32a0
Create Document
To create a new document in an existing collection, use the `createDocument` command.
appwrite databases createDocument --collectionId --documentId 'unique()' --data '{ "Name": "Iron Man" }' --permissions 'read("any")' 'write("team:abc")'
Configuration
At any point, if you would like to change your server endpoint, project key, or self-signed certificate acceptance, use the client service.
appwrite client --endpoint http://192.168.1.6/v1
appwrite client --key 23f24gwrhSDgefaY
appwrite client --selfSigned true
appwrite client --reset // Resets your CLI configuration
appwrite client --debug // Prints your current configuration
CI Mode
The Appwrite CLI can also be used in a non-interactive mode. This is especially useful when you want to automate tasks on a CI Server. In order to enable CI mode on the CLI, you need to set your project ID, endpoint and API Key using
appwrite client --endpoint http://192.168.1.6/v1 --projectId YOUR_PROJECT_ID --key YOUR_API_KEY
When you set the global configuration parameters using the client service, they take precedence over the local configuration parameters in your appwrite.json thereby switching the CLI to non-interactive mode.
In this mode, the CLI can only interact with one project at a time. If you look closely, you'll also notice that we use an API Key to authenticate which means the CLI behaves like Appwrite's server SDK. You can learn more about API Keys in the Appwrite for Server docs.
Help
If you get stuck anywhere, you can always use the help command to get the usage examples.
Uninstall
If you installed Appwrite CLI using NPM, you can use the following command to uninstall it.
npm uninstall -g appwrite-cli
If you installed the Appwrite CLI with brew or the installation script for your operating system, use the following command to uninstall it.
-
MacOS
Using Homebrew
brew uninstall appwrite
or terminal
rm -f /usr/local/bin/appwrite | bash
-
Windows
$APPWRITE_INSTALL_DIR = Join-Path -Path $env:LOCALAPPDATA -ChildPath "Appwrite"; Remove-Item -Force -Path $APPWRITE_INSTALL_DIR
-
Linux
rm -f /usr/local/bin/appwrite | bash
You can also remove the configuration, cookies, and API Keys the Appwrite CLI stored. To remove those, run the following command.
-
MacOS
rm -rf ~/.appwrite | bash
-
Windows
$APPWRITE_CONFIG_DIR = Join-Path -Path $env:UserProfile -ChildPath ".appwrite"; Remove-Item -Recurse -Force -Path $APPWRITE_CONFIG_DIR
-
Linux
rm -rf ~/.appwrite | bash