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
-
Node.js v20.x or later
-
A Fauna account. You can sign up for a free account at https://dashboard.fauna.com/register.
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
ofdb.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
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 |
---|---|---|
|
Name for the default endpoint used in Fauna CLI commands. You can override the default for a command using the If no default endpoint is defined and a command doesn’t include the
|
.fauna-shell
endpoint properties
Endpoints in the .fauna-shell
configuration file have the following
properties:
Property | Required | Description |
---|---|---|
|
Yes |
Secret used to authenticate HTTP API requests to the endpoint. |
|
Hostname of the endpoint’s Fauna instance. Defaults to |
|
|
Connection scheme. Must be |
|
|
UNIX port number of the endpoint’s Fauna instance. Defaults to |
|
|
Default file containing FQL queries to run using the
|
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 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, usecloud-us
.
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 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 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 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:
-
If you haven’t already, initialize the project.
-
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 { name: String email: String index byEmail { terms [.email] } unique [.email] }
-
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 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 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 a key
Use 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 eval
to run an FQL query from the command
line, a file, or STDIN.
fauna eval "Product.all()"
For additional examples, see the eval
reference docs.
Run queries in an interactive shell
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
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 |
---|---|---|
|
Default directory of FSL files used for the following commands: You can override the default for these commands using the If no default endpoint is defined and the command doesn’t include the
|
|
|
Default environment used for Fauna CLI commands. |
Environment properties
Property | Required | Description |
---|---|---|
|
Default endpoint for the environment. The endpoint must be defined in the
|
|
|
Default database for the environment. Can include a path to a child database. Example: |
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!