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

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.

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

appwrite client --endpoint http://192.168.1.6/v1 --projectId YOUR_PROJECT_ID --key YOUR_API_KEY

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