Appwrite is now available as a DigitalOcean 1-click app! Click to install! 🚀
Docs

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

  1. Provides context to the CLI
  2. Keeps track of all your Cloud Functions
  3. Keeps track of all your project's collections
  4. 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 autenticate 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