Fauna CLI

Version: 3.0.1 Package: fauna-shell

The Fauna CLI lets you access Fauna from your terminal. You can use the CLI to:

  • Log in to your Fauna account

  • Create and manage Fauna databases and keys

  • Push, pull, and manage FSL schema

  • Run FQL queries in an interactive shell

Requirements

Installation

To install the Fauna CLI globally:

npm install -g fauna-shell

Configuration

The CLI creates a .fauna-shell configuration file upon installation. The file is located at:

  • Linux, macOS, Unix: ~/.fauna-shell

  • Windows: %userprofile%\.fauna-shell

.fauna-shell is an INI-format file that stores the configuration for Fauna endpoints. Example:

default=cloud-us

[endpoint.cloud-us]
domain=db.fauna.com
scheme=https
secret=fn...

[endpoint.cloud-eu]
domain=db.fauna.com
scheme=https
secret=fn...

[localhost]
domain=127.0.0.1
port=8443
scheme=http
secret=fn...

An endpoint starts with [<ENDPOINT_NAME>] followed by its properties. If an endpoint or property is duplicated, the CLI uses the last definition.

Endpoints

Internally, the CLI uses the Fauna Core HTTP API to execute most commands.

An endpoint defines the settings the CLI uses to run API requests against a Fauna account or database. Each endpoint contains:

  • A base domain for Fauna Core HTTP API endpoints.

  • An HTTP scheme for the base domain.

  • An authentication secret used to authenticate and route Fauna API requests. The secret is scoped to a specific database or a Fauna account’s top-level context.

Endpoints let you switch between different Fauna accounts or databases using the CLI.

Add endpoints

The CLI stores endpoints in .fauna-shell. The cloud-login command is the preferred way to add endpoints to .fauna-shell.

Endpoints for a Fauna account or database should use:

  • A domain of db.fauna.com

  • An HTTP scheme of https

Example:

[endpoint.cloud-us]
domain=db.fauna.com
scheme=https
secret=fn...

Non-standard endpoints

If you use the Fauna Dev Docker image, you can use fauna endpoint add to add non-standard or local endpoints to .fauna-shell. Example:

[localhost]
domain=127.0.0.1
port=8443
scheme=http
secret=fn...

Global .fauna-shell properties

The .fauna-shell configuration file has the following global properties:

Property Required Description

default=<ENDPOINT_NAME>

Name for the default endpoint used in Fauna CLI commands.

You can override the default for a command using the --endpoint option.

If no default endpoint is defined and a command doesn’t include the --endpoint option, the CLI returns an error.

.fauna-shell endpoint properties

Endpoints in the .fauna-shell configuration file have the following properties:

Property Required Description

secret=<secret>

Yes

Secret used to authenticate HTTP API requests to the endpoint.

domain=<FAUNA_HOSTNAME>

Hostname of the endpoint’s Fauna instance. Defaults to db.fauna.com.

scheme=<scheme>

Connection scheme. Must be https (default) or http.

port=<port>

UNIX port number of the endpoint’s Fauna instance. Defaults to 443.

queriesFile=<name>

Default file containing FQL queries to run using the fauna eval command. You can override the default using the command’s --file option.

To differentiate between endpoints, you can also include arbitrary properties. Fauna ignores these properties.

Basic usage

This section covers common Fauna CLI commands and usage. For all commands, see Fauna CLI commands.

Log in to Fauna

Use fauna cloud-login to log in to Fauna:

fauna cloud-login

When prompted, enter:

  • Endpoint name: cloud (Press Enter)

    An endpoint defines the settings the CLI uses to run API requests against a Fauna account or database. See Endpoints.

  • Email address: The email address for your Fauna account.

  • Password: The password for your Fauna account.

  • Which endpoint would you like to set as default? The cloud-* endpoint for your preferred Region Group. For example, to use the US Region Group, use cloud-us.

fauna cloud-login requires an email and password login. If you log in to the Fauna using GitHub or Netlify, you can enable email and password login using the Forgot Password workflow.

If successful, the command adds a related endpoint and secret to the .fauna-shell configuration file. See Configuration.

Initialize a project

A project is a directory that includes:

  • A .fauna-project file that stores a default configuration for the project in Fauna CLI

  • .fsl files for the project’s database(s), typically stored in a subdirectory

  • (Optional) The application’s source code

Use fauna project init to create a .fauna-project file for a project:

fauna project init

When prompted, provide:

  • A schema directory used to store .fsl files. If the directory doesn’t exist, the command creates it.

  • A default environment name. See Environments.

  • A default endpoint to use for Fauna CLI commands.

  • A default database for Fauna CLI commands.

For more information about the .fauna-project file, see Project configuration.

Create a database

Use fauna create-database to create a database:

fauna create-database <DATABASE_NAME>

If you’re using a .fauna-project file and want to create a top-level database, add --environment='':

fauna create-database --environment='' <DATABASE_NAME>

To create a top-level database, you must use a secret scoped to the account’s top-level context. To create this secret and use it by default, use the fauna cloud-login command.

Push and pull schema

A project directory includes .fsl files for the project’s database. You can use the Fauna CLI to push and pull a project’s .fsl files from Fauna.

You can use these commands to manage .fsl files using a CI/CD pipeline. See Manage schema with a CI/CD pipeline.

Run a staged schema change

A staged schema change lets you change one or more collection schema without index downtime due to index builds.

To run a staged schema change:

  1. Make the desired changes to .fsl files in your schema directory.

    You can’t use a staged schema change to delete or rename schema. Instead, delete or rename the schema in a separate unstaged schema change.

  2. Use fauna schema push to stage the schema changes. fauna schema push stages schema changes by default:

    fauna schema push

    This allows Fauna to build indexes for the updated schema before applying the schema to the database.

    A database can have one staged schema change at a time. You can update staged schema using fauna schema push.

    When a database has staged schema, any access or updates done using FQL’s schema commands on related system collections interact with the staged schema, not the database’s active schema.

    For example, when schema changes are staged, Collection.all() returns Collection documents for the staged collection schema, not the database’s Collection documents.

    If a database has staged schema, you can’t edit the database’s active schema using FQL, the Dashboard, or an unstaged schema change. You must first abandon the staged schema change.

  3. Use fauna schema status to check the status of the staged schema:

    fauna schema status

    Possible statuses:

    Staged status Description

    pending

    Changes are being processed. New indexes are still being built.

    ready

    All indexes have been built. Changes are ready to commit.

    failed

    There was an error during the staging process.

  4. When the status is ready, use fauna schema commit to apply the staged schema to the database:

    fauna schema commit

    You can only commit staged schema with a status of ready.

    If you no longer wish to apply the staged schema or if the status is failed, use fauna schema abandon to unstage the schema:

    fauna schema abandon

Run an unstaged schema change

To immediately commit schema changes without staging, use the --active option:

fauna schema push --active

Schema changes that trigger an index build may result in downtime where the index is not queryable.

You can’t run an unstaged schema change if a database has staged schema. You must abandon the staged schema changes first.

Create and delete schema

Committing a schema to Fauna creates the related resource. For example, committing a collection schema to Fauna creates the collection.

Similarly, you can delete the resource by removing the schema from the FSL files in a project’s schema directory then pushing the changes to Fauna.

Compare local, staged, and active schema

Use fauna schema diff to compare a project’s local, staged, and active schema.

For example, to compare the local schema to the remote staged schema:

fauna schema diff

If there is no staged schema, fauna schema diff compares the local schema to the remote active schema instead.

To compare the local schema to the remote active schema:

fauna schema diff --active

To compare the remote active schema to the remote staged schema:

fauna schema diff --staged

By default, fauna schema diff prints a semantic summary of the changes. To get a textual diff, use the --text option. For example:

fauna schema diff --text

Pull schema from Fauna

Use fauna schema pull to pull a database’s remote .fsl schema files into a project’s local schema directory:

fauna schema pull

If the database has staged schema, the command pulls the database’s remote staged schema by default.

If the database has no staged schema, the command pulls the database’s remote active schema.

Pull active schema files

Use the fauna schema pull command’s --active option to pull the database’s remote active schema regardless of whether the database has staged schema:

fauna schema pull --active
Delete local files

The fauna schema pull command overwrites existing schema files in the local directory.

If wanted, you can use the --delete option to delete local .fsl files that aren’t part of the remote schema:

fauna schema pull --delete

Manage schema for child databases

Fauna databases support a hierarchical database structure with top-level and child databases. You can manage schema for child databases using scoped keys with the CLI or using FQL schema methods.

Use scoped keys

Most schema-related Fauna CLI commands support a --secret option. Use this option to provide a scoped key, letting you interact with a child database’s schema using a parent database’s admin key.

For example, with a parent database’s admin key secret of fn123, you can access a child database by appending the child database name and role:

# Uses a scoped key from a parent database
# to stage schema in the `childDb` child database.
# The scope key has `admin` privileges in the
# `childDb` database.
fauna schema push --secret:fn123:childDb:admin
Use FQL schema methods

Fauna stores each schema for a database as an FQL document in a related system collection.

You can use methods for these system collections to programmatically manage the schema of child databases using FQL queries.

FSL schema FQL system collection

Create a key

Use fauna create-key to create a key for a database:

fauna create-key <DATABASE_NAME> <ROLE>

If you’re using a .fauna-project file and want to create a key for a top-level database, add --environment='':

fauna create-key --environment='' <DATABASE_NAME> <ROLE>

To create a key for a top-level database, you must use a secret scoped to the account’s top-level context. You can create this secret and use it by default using the fauna cloud-login command.

The response includes the key’s secret. The secret is shown once. You can’t recover or retrieve the secret later.

If you don’t specify a role, the key uses the admin role by default.

Run FQL queries

The Fauna CLI includes commands for running FQL queries.

Run queries using eval

Use fauna eval to run an FQL query from the command line, a file, or STDIN.

fauna eval "Product.all()"

For additional examples, see the fauna eval command reference docs.

Run queries in an interactive shell

Use fauna shell to start an interactive shell session in the Fauna CLI. You can use the session to run arbitrary FQL queries.

fauna shell

In the shell session, you can enter editor mode to run multi-line queries:

> .editor

Project configuration

The .fauna-project is an INI-format file that stores a default Fauna CLI configuration for a project directory.

The Fauna CLI uses these defaults when you run commands in the directory. If you run commands in a subdirectory, the CLI searches parent directories for the nearest .fauna-project file.

Example:

schema_directory=schema
default=dev

[environment.dev]
endpoint=fauna-us
database=accounts/dev

[environment.qa]
endpoint=fauna-us
database=accounts/qa

[environment.prod]
endpoint=fauna-us
database=accounts/prod

Environments

The .fauna-project file lets you define multiple environments for a project. An environment groups a Fauna endpoint with a default database at the endpoint.

Fauna CLI environments are typically mapped to the environments for the client application, such as dev, staging, or prod. You can use Fauna environments to easily switch between databases when running Fauna CLI commands.

An environment starts with [environment.<ENVIRONMENT_NAME>] followed by its configuration properties. If an environment or property is duplicated, the CLI uses the last definition.

Global properties

Property Required Description

schema_directory=<DIRECTORY>

Default directory of .fsl files used for the following commands:

You can override the default for these commands using the --dir option.

If no default endpoint is defined and the command doesn’t include the --dir option, the CLI returns an error.

default=<ENVIRONMENT_NAME>

Default environment used for Fauna CLI commands.

Environment properties

Property Required Description

endpoint=<ENDPOINT_NAME>

Default endpoint for the environment. The endpoint must be defined in the ~/.fauna-shell configuration file. See .fauna-shell endpoint properties in the configuration documentation.

database=<DATABASE>

Default database for the environment.

Can include a path to a child database. Example: accounts/prod is a path to the accounts database’s prod child database.

Manage schema with a CI/CD pipeline

You can use schema-related Fauna CLI commands to manage schema as .fsl files. The following examples show how you can manage schema using a CI/CD pipeline:

GitHub

In your project, create a .github/workflows/main.yml file with the following contents:

name: Main CI

on:
  push:
    branches: [ main ]

jobs:
  ci:
    runs-on: ubuntu-latest
    env:
      FAUNA_SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

    strategy:
      matrix:
        node-version: [18.x]

    steps:
    - uses: actions/checkout@v3

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3
      with:
        node-version: ${{ matrix.node-version }}

    - name: Install dependencies
      run: npm install

    - name: Install Fauna CLI
      run: npm install -g fauna-shell

    - name: Stage schema change
      run: fauna schema push --no-input --secret $FAUNA_SECRET_KEY

    - name: Check schema status
      id: schema-check
      run: |
        attempts=0
        max_attempts=60  # 30 minutes with 30-second intervals
        while [ $attempts -lt $max_attempts ]; do
          STATUS=$(fauna schema status --secret $FAUNA_SECRET_KEY | grep -oP '(?<=Staged status: )\w+')
          echo "Current status: $STATUS"
          if [ "$STATUS" = "ready" ]; then
            echo "Schema is ready"
            echo "schema_status=ready" >> $GITHUB_OUTPUT
            exit 0
          elif [ "$STATUS" = "failed" ]; then
            echo "Schema staging failed"
            echo "schema_status=failed" >> $GITHUB_OUTPUT
            exit 1
          fi
          echo "Waiting for schema to be ready..."
          sleep 30
          attempts=$((attempts + 1))
        done
        echo "Timeout waiting for schema status"
        echo "schema_status=timeout" >> $GITHUB_OUTPUT
        exit 1

    - name: Run tests
      run: npm test

    - name: Handle schema changes
      if: always()
      run: |
        if [[ "${{ steps.schema-check.outputs.schema_status }}" == "ready" ]]; then
          fauna schema commit --no-input --secret $FAUNA_SECRET_KEY
        else
          fauna schema abandon --no-input --secret $FAUNA_SECRET_KEY
        fi

    - name: Reset Test Database
      if: always()
      run: |
        fauna schema push --dir=./cleanup/ --no-input --active --secret $FAUNA_SECRET_KEY
        fauna schema commit --no-input --secret $FAUNA_SECRET_KEY
      env:
        FAUNA_SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

GitLab

In your project, create a .gitlab-ci.yml file with the following contents:

stages:
  - build
  - stage_schema
  - test
  - cleanup

variables:
  FAUNA_SECRET_KEY: $FAUNA_SECRET_KEY

default:
  image: node:18

build:
  stage: build
  script:
    - npm install
    - npm install -g fauna-shell
  only:
    - main

stage_schema:
  stage: stage_schema
  script:
    - fauna schema push --no-input --secret $FAUNA_SECRET_KEY
    - |
      attempts=0
      max_attempts=60
      while [ $attempts -lt $max_attempts ]; do
        STATUS=$(fauna schema status --secret $FAUNA_SECRET_KEY | grep -oP '(?<=Staged status: )\w+')
        echo "Current status: $STATUS"
        if [ "$STATUS" = "ready" ]; then
          echo "Schema is ready"
          exit 0
        elif [ "$STATUS" = "failed" ]; then
          echo "Schema staging failed"
          exit 1
        fi
        echo "Waiting for schema to be ready..."
        sleep 30
        attempts=$((attempts + 1))
      done
      echo "Timeout waiting for schema status"
      exit 1
  only:
    - main

test:
  stage: test
  script:
    - npm install  # Need to install dependencies again in this stage
    - npm install -g fauna-shell
    - npm test
    - |
      if [ $? -eq 0 ]; then
        fauna schema commit --no-input --secret $FAUNA_SECRET_KEY
      else
        fauna schema abandon --no-input --secret $FAUNA_SECRET_KEY
        exit 1
      fi
  only:
    - main

cleanup:
  stage: cleanup
  script:
    - npm install -g fauna-shell
    - fauna schema push --dir=./cleanup/ --no-input --active --secret $FAUNA_SECRET_KEY
    - fauna schema commit --no-input --secret $FAUNA_SECRET_KEY
  when: always
  only:
    - main

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!