Fauna CLI v4

Version: 4.0.0 Package: fauna-shell
Migrate to v4 of the Fauna CLI

v4 is the latest version of the Fauna CLI. Migrating from v3? Check out the CLI migration guide.

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

Requirements

  • Node.js v20.18 or later.

    • Node.js v22 or later is recommended.

  • A Fauna account.

Quick start

To get started:

  1. Install the CLI

    npm install -g fauna-shell

  2. Enable auto-complete (for bash or zsh)

    Append the output of fauna completion to your .bashrc, .bash_profile, .zshrc, or .zprofile. For example:

    fauna completion >> ~/.zshrc

  3. Authenticate with Fauna

    fauna login

  4. Create a config file (optional)

    In your project’s directory, create a fauna.config.yaml file. The file contains settings for different profiles. Each setting is passed as a flag when executing CLI commands.

    # file: fauna.config.yaml

# `dev` profile settings
dev:
  color: true           # Passed as '--color' in CLI commands
  database: us/my_db    # Passed as '--database us/mydb' in CLI commands
  dir: /schema          # Passed as '--dir /schema' in CLI commands
  role: admin           # Passed as '--role admin' in CLI commands

  5. Run CLI commands

    Run a command using the settings from the dev profile in your config file:

    # Runs a query using the settings
# from the config file's 'dev' profile.
fauna query "Collection.all()" \
  --profile dev

    You can specify flags to override settings from a config file profile. For example, to run a query in a different database:

    # Runs a query in the 'parent_db/child_db' child database
# in the 'us' region group, overriding the profile's database setting.
fauna query "Collection.all()" \
  --database us/parent_db/child_db \
  --profile dev

    Or run commands without using a config file by providing flags directly:

    # Runs a query in the top-level 'my_db' database
# in the 'us' region group. Uses the default admin role.
fauna query "Collection.all()" \
  --database us/my_db

Installation

To install the Fauna CLI globally:

npm install -g fauna-shell

Auto-complete

To enable auto-complete for CLI commands in bash or zsh, run fauna completion and append the output to your .bashrc, .bash_profile, .zshrc, or .zprofile. For example:

fauna completion >> ~/.zshrc

Authentication

Most commands make requests to the Fauna Core HTTP API, which requires authentication. Commands support the following authentication methods:

Interactive login

For interactive use cases, use the login flow:

  1. Run fauna login and specify an optional --user:

    # Log in as the 'john_doe' user.
fauna login \
  --user john_doe

    The --user argument can be any string. --user is only used by the CLI to store and retrieve Fauna account keys. The --user is not passed to Fauna itself. See How interactive login works.

  2. After logging in, authenticate other CLI commands by specifying a --database with an optional --user and --role:

    # Run a query as the `john_doe` user in the 'us/my_db' database.
# Use the 'server' role.
fauna query "Collection.all()" \
  --database us/my_db \
  --user john_doe \
  --role server

    If omitted:

    • --user defaults to default

    • --role defaults to admin

    # Run a query in the 'us/my_db' database as
# the 'default' CLI user. Use the default 'admin' role.
fauna query "Collection.all()" \
  --database us/my_db

Log in without redirects

By default, fauna login runs and redirects to a local HTTP callback server at 127.0.0.1 to receive an authentication code from Fauna.

This approach may not work in environments where opening a browser isn’t possible or environments with an isolated network stack, such as Windows Subsystem for Linux (WSL) or other virtualized environments.

In these cases, use --no-redirect to manually generate and provide an authentication code without redirects and a local callback server.

# Log in as the 'john_doe' user
# without a a local callback server.
fauna login \
  --no-redirect \
  --user john_doe

How interactive login works

Upon login, the CLI stores a Fauna account key and refresh token for the --user in the access_keys file located at:

  • Linux, macOS, Unix: ~/.fauna/credentials/access_keys

  • Windows: %userprofile%\.fauna\credentials\access_keys

The CLI automatically refreshes keys in the access_keys file.

{
  "default": {
    "accountKey": "fnacapi_...",
    "refreshToken": "fnart_..."
  },
  "john_doe": {
    "accountKey": "fnacapi_...",
    "refreshToken": "fnart_..."
  }
}

The CLI uses the account key to create a short-lived scoped key for the --database and --role. The CLI uses the scoped key to authenticate Fauna Core HTTP API requests for the command.

The scoped key’s secret is stored under the user’s account key in the secret_keys file located at:

  • Linux, macOS, Unix: ~/.fauna/credentials/secret_keys

  • Windows: %userprofile%\.fauna\credentials\secret_keys

{
  "fnacapi_...": {
    "us/my_db:admin": {
      "secret": "fn...",
      "expiresAt": 1733322000905
    }
  }
}

CLI-created scoped keys have a 15-minute ttl (time-to-live) and are scoped to their specific database.

Default user

The CLI automatically uses the default user if you don’t specify a --user when:

The default user is associated with credentials stored under the default key in the access_keys file.

For example, the following command:

fauna query "Collection.all()" \
  --database us/my_db

Is equivalent to:

fauna query "Collection.all()" \
  --database us/my_db \
  --user default

Account keys

You can specify a Fauna account key to authenticate CLI commands. The CLI uses the first account key found based on the following order of precedence:

For more information, see How account key authentication works.

--account-key flag

Use --account-key to provide an account key for a command. You must also provide a --database and an optional --role:

# Run a query using an account key.
fauna query "Collection.all()" \
  --account-key $MY_ACCOUNT_KEY \
  --database us/my_db \
  --role server

If omitted, --role defaults to admin.

You can’t use --account-key with --user or --secret. If both --account-key and --user are specified, --user is ignored. If both --account-key and --secret are specified, the command returns an error.

FAUNA_ACCOUNT_KEY environment variable

You can specify a default account key using the FAUNA_ACCOUNT_KEY environment variable:

export FAUNA_ACCOUNT_KEY="my_account_key"

How account key authentication works

Account key authentication works similarly to an interactive login. The CLI uses the account key to create a short-lived scoped key for the --database and --role. The CLI uses the scoped key to authenticate Fauna Core HTTP API requests for the command.

The scoped key’s secret is stored under the account key in the secret_keys file. For more information about this file, see How interactive login works.

Unlike an interactive login, the user-provided account key isn’t stored in the access_keys file. User-provided account keys aren’t automatically refreshed.

Secrets

You can specify an authentication secret for CLI commands. The CLI uses the first secret found based on the following order of precedence:

--secret flag

Use --secret to directly provide a database authentication secret:

# Run a query in the database scoped to a
# secret.
fauna query "Collection.all()" \
  --secret $MY_SECRET

The command runs in the database to which the secret is scoped.

Scoped keys

If the --secret is a key secret with the admin role, you can use --database and --role to create and use a scoped key that impersonates a role on a child database. If impersonating a user-defined role, the role must be defined in the child database.

# Create and use a scoped key that impersonates a secret with the
# 'server' role in the 'child_db' child database. The
# query runs in the 'child_db' child database.
fauna query "Collection.all()" \
  --secret $MY_SECRET \
  --database child_db
  --role server

Alternatively, you can manually pass a scoped key in --secret and omit --database and --role:

# Use a scoped key that impersonates a secret with the
# 'server' role in the 'child_db' child database. The
# query runs in the 'child_db' child database.
fauna query "Collection.all()" \
  --secret $MY_SECRET:child_db:server

FAUNA_SECRET environment variable

You can specify a default secret using the FAUNA_SECRET environment variable:

export FAUNA_SECRET="my_secret"

Local Fauna container

If you have Docker or a similar software installed and running, you can use fauna local to start a local Fauna container:

# Starts a local Fauna container.
# The container's name defaults to 'faunadb'.
fauna local

Use --database to optionally create a database in the container.

# Start a local Fauna container.
# Create the 'my_db' database in the container.
fauna local \
  --database my_db

When creating a database, use --dir to push a local directory of .fsl schema files to the database using fauna schema push. The schema is immediately applied to the database’s active schema with no prompts.

# Create the 'my_db' database in a container.
# Immediately apply changes to the 'my_db' database's
# active schema.
fauna local \
  --database my_db \
  --dir /path/to/schema/dir

Once started, use --local to run commands in the container. When specifying a --database, omit the region group:

# Run a query in the 'my_db' database of a local
# Fauna container. Use the default admin role.
fauna query "Collection.all()" \
  --database my_db \
  --local

The --local flag sets:

You can override these arguments using the respective --url and --secret flags.

Scoped keys for local containers

When used with --local, the`--database` and optional --role flags let you create and use a scoped key. The scoped key impersonates a role on a database. If impersonating a user-defined role, the role must be defined in the database.

# Creates a scoped key that impersonates a secret with the
# 'server' role in the 'parent_db/child_db' child database.
fauna query "Collection.all()" \
  --database parent_db/child_db \
  --role server \
  --local

If needed, you can explicitly provide a --secret. The secret must match the top-level key for the Fauna container:

# Equivalent to the previous command.
# Provides an explicit top-level key
# for the local Fauna container.
fauna query "Collection.all()" \
  --database parent_db/child_db \
  --role server \
  --local \
  --secret $MY_SECRET

Configuration

The CLI lets you pass settings using a YAML (.yml, .yaml) or JSON (.json) config file. Each setting is passed as a flag when executing CLI commands.

The config file is organized into profiles, letting you use different groups of settings for different environments or use cases.

# `dev` profile settings
dev:
  color: true           # Passed as '--color' in CLI commands
  database: us/my_db    # Passed as '--database us/mydb' in CLI commands
  dir: /schema          # Passed as '--dir /schema' in CLI commands

# `ci` profile settings
ci:
  local: true           # Passed as '--local' in CLI commands
  color: false          # Passed as '--color=false' in CLI commands
  database: my_db       # Passed as '--database mydb' in CLI commands
  dir: /schema          # Passed as '--dir /schema' in CLI commands
  input: false          # Passed as '--input=false' in CLI commands
  json: true            # Passed as '--json' in CLI commands

Settings

Each setting in the config file maps directly to a command flag. For example, the database setting in the config file is passed as the --database flag when running a command.

Supported flags vary by command. Not all commands support the same flags. Refer to each command’s documentation to see supported flags.

Unsupported or unrecognized settings/flags do not trigger errors.

Common settings

The following table outlines common settings for the config file. The table is not exhaustive.

Setting Type Description

account-key

string

Fauna account key used for authentication. If used, you must also provide a database and an optional role setting/flag.

We only recommend using this setting in CI/CD and automated workflows. See Storing credentials in config files.

color

Boolean

Enable color formatting for output. Enabled by default. Use no-color: false to disable.

database

string

Database, including the region group identifier and hierarchy, to run the command in. Supports shorthand region group identifiers. Separate path components using /. Examples: us/my_db, eu/parent_db/child_db, global/db. Can’t be used with secret.

If using a local Fauna container, omit the region group.

dir

string

Path to a local directory containing .fsl files for the database. Used by fauna schema commands.

Recursively scans subdirectories. Defaults to the current directory (.).

input

Boolean

Enable user prompts. Defaults to true. To disable prompts, use input: false.

json

Boolean

For supported commands, output results as JSON. Doesn’t affect error output.

local

Boolean

Use a local Fauna container. If not otherwise specified, this settings configures:

quiet

Boolean

Suppress all log messages except fatal errors. Output only command results. Overrides verbosity and verbose-component settings/flags used for Debug logging.

secret

string

Secret used for authentication. Supports scoped keys. The command runs in the database to which the secret is scoped. Can’t be used with database.

We only recommend using this setting in CI/CD and automated workflows. See Storing credentials in config files.

role

string

Role used to run commands. Defaults to admin. Can’t be used with --secret.

timeout

number (integer)

Maximum query runtime, in milliseconds. Used by the fauna query and fauna shell commands.

Storing credentials in config files

While supported, we don’t recommend using the account-key or secret settings to store account keys or database authentication secrets in interactive development environments. Instead, use interactive login or the respective FAUNA_ACCOUNT_KEY or FAUNA_SECRET environment variables.

For CI/CD and automated workflows, you can create and store an account key or database authentication secret with a short time-to-live (TTL) in the respective account-key or secret setting of a temporary config file. You should:

  • Avoid using account keys or secrets with a long time-to-live (TTL).

  • Ensure config files are not committed to version control.

  • Delete the config file after use.

Setting precedence

Command line flags take precedence over config file settings. If both are provided, the flag value will be used in place of the config file setting.

To see what arguments are used to execute a command, use --verbose-component argv. See Component-specific logging.

Provide a config file

The CLI uses the first config file found based on the following order of precedence:

If you provide a config file, you must also specify a profile to use.

--config flag

Use --config to provide a path to a config file to use. For example:

# Use the `config.yml` config file.
fauna query "2 + 2" \
  --database us/my_db \
  --config /path/to/config.yml

FAUNA_CONFIG environment variable

Use the FAUNA_CONFIG environment variable to specify a path to a config file to use. For example:

export FAUNA_CONFIG="/path/to/config.yml"

Default config files

The CLI automatically detects config files with the following names in the directory where you run the command:

  • fauna.config.yaml

  • fauna.config.yml

  • fauna.config.json

  • .fauna.config.yaml

  • .fauna.config.yml

  • .fauna.config.json

If multiple default config files are found, the CLI returns an error.

Specify a profile

Use --profile to specify a profile from the config file. The profile specifies the group of settings in the config file to use.

For example:

# Use settings in the config file's `container` profile.
fauna query "2 + 2" \
  --database us/my_db \
  --profile container

FAUNA_PROFILE environment variable

Use the FAUNA_PROFILE environment variable to specify a default profile to use. For example:

export FAUNA_PROFILE="container"

Flag conventions

In the CLI, you pass arguments to a command using flags. For example:

# Uses the `--database` flag for `fauna shell`.
fauna shell \
  --database us/my_db

Some flags also support a shorthand alias:

# Uses the `-d` alias for `--database`.
fauna shell \
  -d us/my_db

Array arguments

Some flags, such --verbose-component, accept an array of values. To specify an array, you can use a space-separated list:

# Passes `fetch` and `error` to `--verbose-component`.
fauna shell \
  --database us/my_db \
  --verbose-component fetch error

Alternatively, you can use separate flags:

# Passes `fetch` and `error` to `--verbose-component`.
# Equivalent to the previous query.
fauna shell \
  --database us/my_db \
  --verbose-component fetch \
  --verbose-component error

Boolean arguments

Some flags, such --color, accept a boolean value. If the flag is specified with no value, its value is true:

# Passes a `--color` value of `true`.
fauna shell \
  --database us/my_db \
  --color

Use the --[no]- prefix to pass a value of false:

# Passes a `--color` value of `false`.
fauna shell \
  --database us/my_db \
  --no-color

You can also use = to explicitly specify a boolean value:

# Passes a `--color` value of `true`.
fauna shell \
  --database us/my_db \
  --color=true

Multi-word flags

Flags that consist of multiple words support both kebab case and camel case:

# Uses the `----account-key` flag.
fauna query "Collection.all()" \
  --account-key $MY_ACCOUNT_KEY \
  --database us/my_db
# Uses the `--accountKey` alias for `--account-key`.
fauna query "Collection.all()" \
  --accountKey $MY_ACCOUNT_KEY \
  --database us/my_db

Debug logging

By default, the CLI disables debug logging. You can enable debug logs using --verbosity and --verbose-component.

The CLI outputs debug logs for warning and errors to stderr and other messages to stdout.

Global debug log level

--verbosity accepts an integer representing a debug log level. The level determines the least critical type of message to emit.

--verbosity value Debug log level Output stream

5

Debug. Detailed debug messages.

stdout

4

Info. Informational messages.

stdout

3

Warn. Warnings about potential issues.

stderr

2

Error. Errors that need attention.

stderr

1

Fatal. Critical errors.

stderr

0

Default. Emit no debug logs.

Debug logs above the --verbosity level are not emitted. For example:

# Only emits debug logs for warnings (3), errors (2),
# and fatal messages (1).
fauna query "Collection.all()" \
  --database us/my_db \
  --verbosity 3

Component-specific logging

Use --verbose-component to emit messages of any level for specific components, regardless of --verbosity. Accepted values include:

--verbose-component value Description

argv

Command flags, settings, and environment variables. Messages typically include information about arguments in use and the precedence of arguments.

config

Config files. Messages typically include information about the config file in use.

creds

Authentication. Messages typically include information about credentials in use and credential refreshes.

error

Prints the stack trace of errors instead of the error’s message.

fetch

HTTP requests, including requests to the Fauna Core HTTP API and Account HTTP API. Authentication secrets are redacted.

You can pass multiple components to --verbose-component as a space-separated list. For example:

# Emits all debug log messages for the `argv` and `config`
# components, including log messages that are
# less critical than warnings (3).
fauna query "Collection.all()" \
  --database us/my_db \
  --verbosity 3 \
  --verbose-component argv config \
  --config /path/to/config.yml \
  --profile dev

The command outputs the following debug logs:

[config]: Reading config from /myapp/.fauna.config.yaml.
[config]: Using profile dev...
[config]: Applying config: {
    "color": true
}
[config]: Reading config from /myapp/.fauna.config.yaml.
[config]: Using profile dev...
[config]: Applying config: {
    "color": true
}
[argv]: {
    "_": [
        "query"
    ],
    "database": "us/my_db",
    "d": "us/my_db",
    "verbosity": 3,
    "verbose-component": [
        "argv",
        "config"
    ],
    "verboseComponent": [
        "argv",
        "config"
    ],
    "config": "./.fauna.config.yaml",
    "profile": "dev",
    "p": "dev",
    "color": true,
    "json": false,
    "quiet": false,
    "user": "default",
    "u": "default",
    "local": false,
    "api-version": "10",
    "v": "10",
    "apiVersion": "10",
    "format": "fql",
    "f": "fql",
    "timeout": 5000,
    "performance-hints": false,
    "performanceHints": false,
    "include": [
        "summary"
    ],
    "account-url": "https://account.fauna.com",
    "accountUrl": "https://account.fauna.com",
    "$0": "fauna",
    "fql": "Collection.all()"
}
[argv]: Existing Fauna environment variables: {}
[argv]: Defaulted url to 'https://db.fauna.com' no --url was provided
[argv]: no --input specified, using [fql]
...

Suppress debug logs

--quiet suppresses all debug log messages except fatal errors. --quiet overrides --verbosity and --verbose-component. You typically use --quiet to only output the results of a command.

# Only output the results of the command.
fauna query "Collection.all()" \
  --database us/my_db \
  --quiet

Scripting

Scripts and CI/CD workflows can use the CLI to automate tasks in a Fauna database.

For example, you can use schema-related Fauna CLI commands to manage schema as .fsl files. See Manage schema with a CI/CD pipeline.

Best practices

When using the CLI in an automated workflow, follow these best practices.

Use a config file and profile

Use a config file and profiles to pass settings as flags to CLI commands. You can create profiles for different environments and use cases. You can switch between profiles using the --profile flag or the FAUNA_PROFILE environment variable.

You can override a profile’s settings by explicitly passing a flag to a command.

Authenticate using an account key or database secret

The CLI supports several authentication methods. For CI/CD and other automated workflows, we recommend you do one of the following:

  • Use the FAUNA_ACCOUNT_KEY or FAUNA_SECRET environment variables.

  • Create a temporary config file using your script or CI tool. In the config file, create and store an account key or database authentication secret with a short time-to-live (TTL) in the respective account-key or secret setting. Delete the config file after use.

    For example:

    default:
  account-key: fnacapi_abc123

    When using the account-key or secret settings in a temporary config file, you should:

    • Avoid using account keys or secrets with a long TTL.

    • Ensure config files are not committed to version control.

Avoid interactive commands

Avoid using commands, fauna shell or fauna login, that require user input.

Disable interactive prompts

Use --input=false or the corresponding setting to disable prompts for commands such as fauna schema push or fauna schema commit.

To set --input=false as a setting in a config file:

# `ci` profile settings
ci:
  input: false

Use JSON output for parsing

If you use a JSON parser, such as jq, enable JSON output for compatible commands by specifying --json=true or the corresponding json setting.

To set --json=true as a setting in a config file:

# `ci` profile settings
ci:
  json: true

Set timeouts for queries

Use --timeout or the corresponding setting to set a maximum runtime, in milliseconds, for query requests made by fauna query.

To set --timeout as a setting in a config file:

# `ci` profile settings
ci:
  timeout: 3000

Customize logging as needed

Use --verbosity. --verbose-component, and --quiet to customize logging for your use case. If needed, you can redirect stderr and stdout based on your environment. See Debug logging.

Migrate from v3 of the 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

Requirements

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

Authentication

Configuration

Local development and scripting

Removed and updated commands

Schema management

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