Fauna CLI

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 database schemas

  • 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

You can configure the file with one or more connection endpoints. Each endpoint can include a domain, secret, and other properties used in Fauna HTTP API requests.

Example:

default=cloud-us

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

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

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

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

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.

Endpoint properties

Property Required Description

secret=<secret>

Yes

Fauna 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 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 cloud-login to log into Fauna:

fauna cloud-login

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

Create a database

Use create-database to create a database:

fauna create-database <DATABASE_NAME>

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 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.

Push and pull schemas

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 schemas with a CI/CD pipeline.

Push schemas to Fauna

To push FSL schemas to a Fauna database:

  1. If you haven’t already, initialize the project.

  2. In the project’s schema directory, create and save one or more .fsl files.

    For example, you can create a collections.fsl file with the following FSL collection schema:

    collection Customer {
      index byName {
        terms [.firstName, .lastName]
      }
    
      unique [.firstName, .lastName]
    }
  3. Use schema push to push the FSL schemas to Fauna:

    fauna schema push

    Before pushing changes, the command displays a diff. If wanted, you can then accept or reject the changes.

Pushing a schema to Fauna creates the related resource. For example, pushing a collection schema to Fauna creates the collection.

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

Compare local and live schemas

Use schema diff to compare a project’s local FSL schemas to the live schemas in Fauna:

fauna schema diff

Pull schemas from Fauna

Use schema pull to pull a database’s live schemas into a project’s local FSL files:

fauna schema pull

The command overwrites existing schema files. If wanted you can use the --delete option to delete local .fsl files that aren’t in the live schemas:

fauna schema pull --delete

Create and manage keys

The Fauna CLI includes commands for creating and managing keys.

Create a key

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

fauna create-key <DATABASE_NAME> <ROLE>

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.

List keys

Use list-keys to get a list of existing keys:

fauna list-keys

The response includes each key’s ID, database, and role. It doesn’t include the key’s secret:

Key ID               Database             Role
259718958404338186   app1                 server
259719743570706945   app1                 client
265528117038154259   my-test-db           admin
265437820880945683   my-test-db           admin

Delete keys

Use delete-key to delete an existing key. You must provide the key’s ID:

fauna delete-key <KEY_ID>

The response doesn’t include the key’s secret.

Run FQL queries

Use 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 file 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 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 schemas with a CI/CD pipeline

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

GitHub

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

name: Main CI

# Trigger the workflow on a push to the 'main' branch
on:


  push:
    branches: [ main ]

# Define jobs to be run by the workflow
jobs:
  ci:  # This is the identifier for the job
    runs-on: ubuntu-latest  # Specifies that the job should run on the latest Ubuntu runner
    env:
      # Set an environment variable using a secret stored in the repository's secrets
      FAUNA_SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

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

    # Steps to be run as part of this job
    steps:
    - uses: actions/checkout@v3  # Checks out the repository code

    - name: Use Node.js ${{ matrix.node-version }}
      uses: actions/setup-node@v3  # Sets up the Node.js environment
      with:
        node-version: ${{ matrix.node-version }}  # Use the Node.js version from the strategy matrix

    - name: Install dependencies
      run: npm install  # Install npm dependencies specified in package.json

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

    # Push the schema to a test database, potentially overwriting existing schema
    - name: Push schema to Test Database
      run: fauna schema push --force --secret $FAUNA_SECRET_KEY # Using the force flag will omit user confirmation input
      env:
        FAUNA_SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

    - name: Run tests
      run: npm test  # Run tests using the npm test script

    # Reset the test database by pushing a cleanup schema
    - name: Reset Test Database
      run: fauna schema push --dir=./cleanup/ --force --secret $FAUNA_SECRET_KEY
      # An additional environment variable for this step
      env:
        FAUNA__SECRET_KEY: ${{ secrets.FAUNA_SECRET_KEY }}

GitLab

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

# Define the stages in the pipeline
stages:
  - build
  - test
  - deploy

# Job definitions
build_job:
  stage: build
  image : node:18
  script:
    - npm install
    - npm install -g fauna-shell
  only:
    - main

test_job:
  stage: test
  image : node:18
  script:

    - fauna schema push --force --secret $FAUNA_SECRET_KEY
    - npm test
    - fauna schema push --dir=./cleanup/ --force --secret $FAUNA_SECRET_KEY
  only:
    - main
  variables:
    FAUNA_SECRET_KEY: $FAUNA_SECRET_KEY

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!