Installation and configuration

Prerequisites

Node.js, version 14.x or newer.

Installation

To install fauna-shell globally and create a default, YAML-formatted configuration file, enter:

npm install -g fauna-shell

Configuration

For Linux, macOS, and other UNIX-like systems, the configuration file is located at $HOME/.fauna-shell.

For Windows systems, the configuration file is located at %userprofile%\.fauna-shell.

You can configure fauna-shell for one or more connection endpoints. An endpoint defines the domain, secret, and other properties needed to query a Fauna instance.

In the following example, the default endpoint is defined in the first line as db2 and there is a corresponding db2 endpoint configuration.

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

[cloud]
domain=db.fauna.com
scheme=https
secret=fnADS@PxN@2CE@n7z@kDa4_p6Z@fIBaZm@Qt@bYT

[db2]
domain=private.example
port=8443
scheme=https
secret=MY_ORGANIZATION_SECRET

An endpoint entry begins with a [<endpoint>] header, which is the name or alias for the endpoint, and is followed by the endpoint configuration properties.

If a property is duplicated, fauna-shell uses the last definition.

Global properties

Configuration key Description

Configuration key	Description
`default=<alias>`	(Optional) Default endpoint alias. If fauna-shell is started without the `--endpoint` option, the shell uses this endpoint, and there must be a corresponding endpoint configuration in the file. If a default endpoint isn’t defined and the `--endpoint` option isn’t used, an error is generated.

default=<alias>

(Optional) Default endpoint alias. If fauna-shell is started without the --endpoint option, the shell uses this endpoint, and there must be a corresponding endpoint configuration in the file. If a default endpoint isn’t defined and the --endpoint option isn’t used, an error is generated.

Endpoint properties

Property Required Description

Property	Required	Description
`domain=<Fauna hostname>`	No	Hostname of this endpoint Fauna instance. Default = `db.fauna.com`
`scheme=<scheme>`	No	Connection scheme. One of: `https` (Default) `http`
`port=<port>`	No	UNIX port number of this endpoint Fauna instance. Defaults = 443.
`secret=<secret>`	Yes	Database secret.
`queriesFile=<name>`	Yes	File name that has queries to run using the `eval` command.
`query=<query>`	Yes	Query to use with the `eval` command.

domain=<Fauna hostname>

Hostname of this endpoint Fauna instance.
Default = db.fauna.com

scheme=<scheme>

Connection scheme. One of:

https (Default)
http

port=<port>

UNIX port number of this endpoint Fauna instance.
Defaults = 443.

secret=<secret>

Yes

Database secret.

queriesFile=<name>

Yes

File name that has queries to run using the eval command.

query=<query>

Yes

Query to use with the eval command.

You can add more properties to differentiate between endpoints, but they are ignored.

Project configuration file

Syntax

schema_directory=<schemaName>
default=<environmentName>

[environment.<environmentName>]
endpoint=<endpointName>
database=<databaseName>

. . .

Description

Project configuration is stored in the .fauna-project file. Fauna CLI commands use the configuration in this file to discover the database to connect to. When in a subdirectory of a directory that has a .fauna-project file, the CLI searches for the nearest parent directory that has a .fauna-project file and uses that file for the configuration.

Example

fsl_directory=fsl
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

Fields

Label Field Description

Label	Field	Description
	`schema_directory`	(optional) Tells the CLI where the project FSL files are stored. default = Directory with the .fauna-project file. When set, only `.fsl` files in the directory and subdirectories are accessed by the schema commands. This is useful for managing schema files and application files in the same repository.
	`default`	Default environment, `[environment.<environmentName]`, to be used by CLI commands.
`[environment.<environmentName>]`		Project instances, which typically map to environments, such as development, preview, QA, and production. A project usually has multiple environments. Each environment instance has a unique name.
	`endpoint`	Endpoint from the \~/.fauna-shell configuration file, which has the secret to use for this environment. This allows project configuration files, .fauna-project, to be checked into source control without including secrets in the project configuration file.
	`database`	Account database that the environment exists in. All schema changes made with this environment selected, using fauna schema commands, updates this database. This can include a path that points to a nested database.

schema_directory

(optional) Tells the CLI where the project FSL files are stored.
default = Directory with the .fauna-project file.

When set, only .fsl files in the directory and subdirectories are accessed by the schema commands. This is useful for managing schema files and application files in the same repository.

default

Default environment, [environment.<environmentName], to be used by CLI commands.

[environment.<environmentName>]

Project instances, which typically map to environments, such as development, preview, QA, and production. A project usually has multiple environments.

Each environment instance has a unique name.

endpoint

Endpoint from the \~/.fauna-shell configuration file, which has the secret to use for this environment. This allows project configuration files, .fauna-project, to be checked into source control without including secrets in the project configuration file.

database

Account database that the environment exists in. All schema changes made with this environment selected, using fauna schema commands, updates this database. This can include a path that points to a nested database.

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!