Fauna CLI v3

Version: 3.0.1

Migrate to v4 of the Fauna CLI

v3 of the Fauna CLI is now deprecated. v4 of the CLI introduces several significant enhancements to the developer experience, including an improved authentication workflow.

To get started, see the CLI v4 quick start and Migrate to v4 of the Fauna CLI.

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

Node.js v20.x or later
A Fauna account.

Installation

To install the Fauna CLI globally:

npm install -g fauna-shell@3.0.1

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

Configuration

Upon login, the CLI creates or updates a .fauna-shell configuration file. 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 a local Fauna container, 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

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.

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

Property	Required	Description
`secret=<secret>`	true	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.

secret=<secret>

true

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.

Initialize a project directory

A project directory includes:

<APP>/              // Directory containing app source code (optional)
├── .fauna-project  // INI-format file containig Fauna CLI defaults for the project
├── schema/         // Directory containing Fauna .fsl schema files
│   └── *.fsl
...

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 directory:

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.

Manage FSL schema

In Fauna, you define database schema using Fauna Schema Language (FSL). You can manage FSL schemas using the Fauna Dashboard or as .fsl files using the Fauna CLI or the Fauna Core HTTP API’s Schema endpoints.

Using .fsl files lets you:

Store .fsl schema files alongside your application code
Pull and push schema to your Fauna database from a local directory
Place database schema under version control
Deploy schema with CI/CD pipelines
Change your production schema as your app evolves using progressive schema enforcement and zero-downtime migrations

For more information, see Manage schema as .fsl files.

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

.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

The .fauna-project` file is typically committed to version control.

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.

Several Fauna CLI commands, such as fauna eval, let you easily switch environments using the --environment option:

fauna eval "Product.all()" --environment='prod'

Global properties

Property Required Description

Property	Required	Description
`schema_directory=<DIRECTORY>`		Default directory of `.fsl` files used for the following commands: `fauna schema abandon` `fauna schema commit` `fauna schema diff` `fauna schema pull` `fauna schema push` `fauna schema status` 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.

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

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.

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.

Migrate to v4 of the Fauna CLI

v3 of the Fauna CLI is now deprecated. v4 of the Fauna CLI introduces several significant enhancements to the developer experience. The following table outlines major changes from v3 to v4 of the CLI. The table is not exhaustive.

Topic Changes in v4

Topic	Changes in v4
Requirements	v4 of the CLI requires Node.js v20.18 or later. v22 or later is recommended.
Authentication	`fauna login` replaces `fauna cloud-login`. The new `fauna login` command uses a web-based flow. You can use `--user` to switch between credentials for different users after login. The `.fauna-shell` file is no longer used and can be safely deleted. Instead, the CLI uses short-lived credentials and refreshes credentials as needed. See How interactive login works. You can use the `FAUNA_ACCOUNT_KEY` or `FAUNA_SECRET` environment variables to authenticate commands programmatically.
Configuration	The `.fauna-shell` file is no longer used and can be safely deleted. `.fauna-project` files are no longer used and can be safely deleted. The environment and endpoint abstractions are no longer used. Instead, you can use profiles in a config file to switch between settings for different environments or use cases.
Local development and scripting	v4 introduces `fauna local`, which starts a local Fauna container. In v4, you can use `--local` to run CLI commands in a local Fauna container. v4 supports customized logging and scripting.
Removed and updated commands	The following database commands have been renamed and updated: `fauna create-database` is now `fauna database create`. `fauna list-databases` is now `fauna database list`. `fauna delete-database` is now `fauna database delete`. The `fauna eval` command is now `fauna query`, which supports a `fauna eval` alias. v4 has removed commands for managing keys. Instead, you can manage keys in the CLI with FQL queries using Key methods in `fauna eval` or `fauna shell`. Commands related to managing environments and endpoints have been removed. Instead, you can use profiles in a config file to switch between settings for different environments or use cases. `fauna import` has been removed.
Schema management	`fauna schema` commands no longer require `fauna project init`. Otherwise, `fauna schema` commands remain largely unchanged. `.fauna-project` files are no longer used and can be safely deleted. Instead, you can use profiles in a config file to easily switch between databases and other command settings.
Auto-complete	You can use the `fauna completion` command to enable auto-complete for CLI v4 commands in bash or zsh. See Auto-complete.
CLI updates and issue tracking	Starting with v4 of the CLI, Fauna uses the fauna-shell GitHub repository for issue tracking and release tracking. v4 of the CLI uses the update-notifier library to notify you when updates to the CLI’s npm package is available.

Requirements

v4 of the CLI requires Node.js v20.18 or later. v22 or later is recommended.

Authentication

fauna login replaces fauna cloud-login. The new fauna login command uses a web-based flow. You can use --user to switch between credentials for different users after login.
The .fauna-shell file is no longer used and can be safely deleted. Instead, the CLI uses short-lived credentials and refreshes credentials as needed. See How interactive login works.
You can use the FAUNA_ACCOUNT_KEY or FAUNA_SECRET environment variables to authenticate commands programmatically.

Configuration

The .fauna-shell file is no longer used and can be safely deleted.
.fauna-project files are no longer used and can be safely deleted.
The environment and endpoint abstractions are no longer used. Instead, you can use profiles in a config file to switch between settings for different environments or use cases.

Local development and scripting

v4 introduces fauna local, which starts a local Fauna container.
In v4, you can use --local to run CLI commands in a local Fauna container.
v4 supports customized logging and scripting.

Removed and updated commands

The following database commands have been renamed and updated:
- fauna create-database is now fauna database create.
- fauna list-databases is now fauna database list.
- fauna delete-database is now fauna database delete.
The fauna eval command is now fauna query, which supports a fauna eval alias.
v4 has removed commands for managing keys. Instead, you can manage keys in the CLI with FQL queries using Key methods in fauna eval or fauna shell.
Commands related to managing environments and endpoints have been removed. Instead, you can use profiles in a config file to switch between settings for different environments or use cases.
fauna import has been removed.

Schema management

fauna schema commands no longer require fauna project init. Otherwise, fauna schema commands remain largely unchanged.
.fauna-project files are no longer used and can be safely deleted. Instead, you can use profiles in a config file to easily switch between databases and other command settings.

Auto-complete

You can use the fauna completion command to enable auto-complete for CLI v4 commands in bash or zsh. See Auto-complete.

CLI updates and issue tracking

Starting with v4 of the CLI, Fauna uses the fauna-shell GitHub repository for issue tracking and release tracking.
v4 of the CLI uses the update-notifier library to notify you when updates to the CLI’s npm package is available.

Fauna CLI v3

Requirements

Installation

Log in to Fauna

Configuration

Endpoints

Add endpoints

Non-standard endpoints

Global .fauna-shell properties

.fauna-shell endpoint properties

Basic usage

Initialize a project directory

Create a database

Manage FSL schema

Create a key

Run FQL queries

Run queries using eval

Run queries in an interactive shell

Project configuration

Environments

Global properties

Environment properties

Migrate to v4 of the Fauna CLI

Global `.fauna-shell` properties

`.fauna-shell` endpoint properties

Run queries using `eval`