Skip to content

Tooling

Terminal_

Browse, query, and manage your Appwrite projects in an interactive, keyboard-driven interface with the terminal command in the Appwrite CLI.

8 min read

Raw

The appwrite terminal command opens your Appwrite projects in an interactive, keyboard-driven interface inside your terminal. Browse databases, functions, sites, storage, users, teams, and messaging, query rows, execute functions, and watch your project's usage, without leaving the command line. It works with Appwrite Cloud and self-hosted instances.

Project overview in the CLI terminal interface
Project overview in the CLI terminal interface

Open the terminal interface

Sign in with the CLI, then run the command:

Bash
appwrite login
appwrite terminal

appwrite terminal uses the credentials the CLI already has, so there is nothing new to set up. It signs in as your console login, or, without one, with the API key you stored with appwrite client --key.

The interface opens on the first project it finds in this order:

  1. The --project-id flag.
  2. The APPWRITE_PROJECT_ID environment variable.
  3. The projectId in the project config: the file chosen with --config-file or APPWRITE_CONFIG_FILE, or else the nearest appwrite.config.json, so running the command inside a project directory opens that project. Learn more about multiple environments.

Without a project, a console login opens on your organizations, where you can pick any project you have access to.

Bash
appwrite terminal --project-id "<PROJECT_ID>"

Sign in with an API key

To use the interface without a console login, store a project's API key and open that project:

Bash
appwrite client --key "<API_KEY>"
appwrite terminal --project-id "<PROJECT_ID>"

An API key reaches one project, so the interface opens directly on it and has no organizations view. It shows what the key's scopes allow and tells you on each page what the key cannot read. Add the usage.read scope to see usage.

Options

FlagDescription
--project-id <ID>Project to open, instead of APPWRITE_PROJECT_ID or the project config's projectId.
--theme <theme>Color theme: auto (default) follows your terminal; dark or light also paint the background.
--debugWrite debug logs to debug.log in the working directory.

The header shows the project, the endpoint and its Appwrite version, whether it's Appwrite Cloud or self-hosted, the round-trip time, and who you're signed in as. Below it, a breadcrumb shows where you are, such as project Shop › databases › database main › table orders › rows.

  • Move through a list with the arrow keys or j and k, and press Enter to open the selected resource.
  • Each resource page has numbered tabs. Press a number to open a tab, or Tab and Shift + Tab to cycle through them.
  • Press q or Esc to go back one level. On the project overview, q quits. Ctrl + C quits from anywhere.
  • Press ? to see every shortcut that works on the current page.

The page on screen refreshes every 5 seconds, so new rows, executions, and deployments show up as they happen. Press r to refresh now, and p to pause or resume refreshing.

Project overview

Opening a project lands on its overview:

  • Resources. How many databases, functions, sites, buckets, users, teams, messages, topics, and providers the project has, each with a sparkline of the requests to that service over the last 24 hours.
  • Usage, last 24h. Requests, inbound and outbound bandwidth, database reads and writes, function executions, and file and database storage.
  • Busiest routes. The API routes your project served most over the last 24 hours, with their request count, outbound bandwidth, and HTTP method.

Select a resource and press Enter to open its list.

Browse resources

Every resource opens on a page with its details and a set of tabs. Each page also has a json tab with the full resource as the API returns it.

ResourceTabs
OrganizationsProjects. Shown with a console login only.
DatabasesTables, usage
TablesRows, columns, indexes, usage
RowsValues, usage
FunctionsExecutions, deployments, variables, usage
ExecutionsOutput, response, logs, errors, headers
SitesDeployments, logs, usage
BucketsFiles, usage
UsersSessions, memberships, targets, prefs, usage
TeamsMemberships, prefs, usage
MessagesContent, targets, errors, usage
TopicsSubscribers, usage
ProvidersOptions, credentials, usage

Long lists load one page at a time. The footer shows how many items are loaded out of the total, and m reads the next page.

Press / on a list to filter it. As you type, the list narrows to the items whose name or ID matches. On lists the server can search, such as functions, users, and buckets, press Enter to run the search on the server and find items that aren't loaded yet. Press Esc to clear the filter.

Query rows

On a table's rows tab, / also takes a query. Write one or more conditions separated by spaces, and press Enter to run them as Appwrite queries on the server. A row must meet every condition.

Plain text
status=open total>=100 sort:-total

Rows filtered with a query in the CLI terminal interface
Rows filtered with a query in the CLI terminal interface

SyntaxQuery
column=valueEqual to
column!=valueNot equal to
column>value, column>=valueGreater than, greater than or equal to
column<value, column<=valueLess than, less than or equal to
column~textContains
column=null, column!=nullIs null, is not null
sort:column, sort:-columnSort ascending, sort descending

A value that reads as a number, true, false, or null is sent as one. Wrap a value in double quotes to keep spaces in it or to send it as text, for example name~"van der" or code="404". The current query shows in the top-right corner of the frame, and Esc clears it.

Edit and create rows

Rows can be edited and created from the interface:

  • Press e on a row to open its values as JSON in your editor. When you save and close the file, the interface updates the row. If nothing changed, nothing is saved.
  • Press Ctrl + N on a table's rows to open a template for a new row with the table's columns. Save and close the file to create the row.

The interface opens $VISUAL, then $EDITOR, and falls back to vi, or Notepad on Windows. Set a command with its arguments for editors that need one, such as export EDITOR="code --wait".

Execute functions

Press x on a function to execute it. A form asks for the method, path, headers, and body of the request, and whether to run it asynchronously. Press Ctrl + R to run it. The interface then opens the execution with its output, response, logs, and errors. A synchronous execution opens once the function returns. An asynchronous one opens right away, and its page updates as it runs.

Download, copy, and delete

  • Download. Press Ctrl + S on a file to save it to the working directory.
  • Copy. Press c to copy the selected resource's ID, or Shift + C to copy the whole resource as JSON.
  • Delete. Press Ctrl + D to delete a row, file, session, or subscriber. To confirm, type the resource's ID and press Enter. Deleting can't be undone.

Delete confirmation in the CLI terminal interface
Delete confirmation in the CLI terminal interface

Usage

The project overview and the usage tab show usage over the last 24 hours, in 15-minute buckets, next to the total, the range, and the latest value. Not every resource has a usage tab: the resources table lists the ones that do.

  • Requests, inbound, and outbound count the requests to the resource's API route and the routes below it, other than the Console's, with a list of the busiest routes.
  • Databases add reads, writes, and storage.
  • Functions add executions, compute, and deployment storage.
  • Sites show the requests and bandwidth the site served, plus the API calls to the site's route.
  • Buckets add the number of files.

Lists of databases, functions, sites, and buckets also show a 24-hour sparkline next to each item.

Table usage in the CLI terminal interface
Table usage in the CLI terminal interface

Usage needs a console login or an API key with the usage.read scope. On self-hosted instances, usage requires Appwrite 2.7 or later.

Keyboard shortcuts

Press ? in the interface to see the shortcuts for the current page. The full set:

KeyAction
↑ ↓ or k jMove up and down
← → or h lMove left and right
PgUp PgDnPage up and down
g or Home, G or EndGo to the top or bottom
EnterOpen the selected resource
1-9Open a tab by its number
Tab, Shift + TabNext tab, previous tab
/Filter, search, or query
mLoad more items
rRefresh
pPause or resume refreshing
cCopy the ID
Shift + CCopy the JSON
eEdit a row
Ctrl + NCreate a row
xExecute a function
Ctrl + SDownload a file
Ctrl + DDelete the selected resource
?Show help
q or EscGo back
Ctrl + CQuit

Was this page helpful?

Share what worked or what we should fix. Once approved, our agents automatically apply suggested updates to the docs.