Fauna CLI v4

Version: 4.0.0-beta Package: fauna-shell@4.0.0-beta

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

Requirements

Quick start

To get started:

  1. Install the CLI:

    npm install -g fauna-shell@">=4.0.0-beta"

  2. For bash or zsh, enable auto-complete by appending 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. Run CLI commands. Specify a --database, including the Region Group and hierarchy, to run the command in. For example:

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

Installation

To install the beta Fauna CLI globally:

npm install -g fauna-shell@">=4.0.0-beta"

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

Interactive login is not currently supported on Windows Subsystem for Linux (WSL). Use an alternative authentication method, such as account keys or secrets.

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

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

You can pass a scoped key in --secret to run commands in a child database or one of its descendants:

# 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

To be used as a scoped key, the original secret must:

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 passed with --local, you can use --database and an optional --role to create and use a scoped key that impersonates a built-in role on a child database or one of its descendants:

# 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

You can’t use this method if you provide a --secret.

Configuration

The CLI lets you pass settings from a YAML (.yml, .yaml) or JSON (.json) config file as arguments in CLI commands.

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

# `dev` profile settings
dev:
  color: true
  database: us/my_db

# `container` profile settings
container:
  local: true

Settings

A config file’s settings are passed as CLI command flags. Each setting maps directly to a CLI flag. For example, the database setting is passed as the --database flag. Unrecognized settings and flags do not trigger errors.

While supported, we don’t recommend storing secrets, such as authentication secrets or account keys, in config files.

Instead, use the respective FAUNA_SECRET or FAUNA_ACCOUNT_KEY environment variables. Alternatively, you can pass other environment variables to --secret or --account-key.

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.

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 a secret or access key

Use the FAUNA_ACCOUNT_KEY or FAUNA_SECRET environment variables to authenticate CLI commands. These authentication methods don’t require user interaction.

Don’t store secrets, such as authentication secrets or account keys, in config files.

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, use --json=true or the corresponding setting to get JSON output from commands.

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.

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!