# Fauna CLI v4 | Version: 4.0.0 | Package: fauna-shell | | --- | --- | --- | --- | The Fauna CLI lets you access Fauna from your terminal. You can use the CLI to: * Create and manage Fauna [databases](../../../learn/data-model/databases/). * Manage [database schema](../../../learn/schema/) as `.fsl` schema files. * Run [FQL queries](../../../learn/query/) from files or in an interactive REPL. * Run a local [Fauna container](../../tools/docker/). ## [](#requirements)Requirements * [Node.js](https://nodejs.org/en/download/package-manager) v20.18 or later. * [Node.js](https://nodejs.org/en/download/package-manager) v22 or later is recommended. * A Fauna account. ## [](#quick-start)Quick start To get started: 1. **Install the CLI** ```bash npm install -g fauna-shell ``` 2. **Enable auto-complete (for bash or zsh)** Append the output of [`fauna completion`](commands/completion/) to your `.bashrc`, `.bash_profile`, `.zshrc`, or `.zprofile`. For example: ```bash fauna completion >> ~/.zshrc ``` 3. **Authenticate with Fauna** ```cli 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. ```yaml # 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: ```cli # 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: ```cli # 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: ```cli # 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 ``` ## [](#install)Installation To install the Fauna CLI globally: ```bash npm install -g fauna-shell ``` ## [](#autocomplete)Auto-complete To enable auto-complete for CLI commands in bash or zsh, run [`fauna completion`](commands/completion/) and append the output to your `.bashrc`, `.bash_profile`, `.zshrc`, or `.zprofile`. For example: ```bash fauna completion >> ~/.zshrc ``` ## [](#auth)Authentication Most commands make requests to the [Fauna Core HTTP API](../../../reference/http/reference/core-api/), which requires authentication. Commands support the following authentication methods: * [Interactive login](#interactive) * [Account keys](#account-key) * [Secrets](#secret) * [Local Fauna container](#local) ### [](#interactive)Interactive login For interactive use cases, use the login flow: 1. Run [`fauna login`](commands/login/) and specify an optional `--user`: ```cli # 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](../../../reference/http/reference/account-api/#section/Authentication). The `--user` is not passed to Fauna itself. See [How interactive login works](#works). 2. After logging in, authenticate other CLI commands by specifying a `--database` with an optional `--user` and `--role`: ```cli # 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`](#default-user) * `--role` defaults to `admin` ```cli # 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 ``` #### [](#no-redirect)Log in without redirects By default, [`fauna login`](commands/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)](https://learn.microsoft.com/en-us/windows/wsl/about) 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. ```cli # Log in as the 'john_doe' user # without a a local callback server. fauna login \ --no-redirect \ --user john_doe ``` #### [](#works)How interactive login works Upon [login](#interactive), the CLI stores a Fauna [account key](../../../reference/http/reference/account-api/#section/Authentication) 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. ```json { "default": { "accountKey": "fnacapi_...", "refreshToken": "fnart_..." }, "john_doe": { "accountKey": "fnacapi_...", "refreshToken": "fnart_..." } } ``` The CLI uses the account key to create a short-lived [scoped key](../../../learn/security/keys/#scoped-keys) for the `--database` and `--role`. The CLI uses the scoped key to authenticate [Fauna Core HTTP API](../../../reference/http/reference/core-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` ```json { "fnacapi_...": { "us/my_db:admin": { "secret": "fn...", "expiresAt": 1733322000905 } } } ``` CLI-created scoped keys have a 15-minute [`ttl` (time-to-live)](../../../learn/security/keys/#ttl) and are scoped to their specific database. #### [](#default-user)Default user The CLI automatically uses the `default` user if you don’t specify a `--user` when: * Running [`fauna login`](commands/login/) * Running other CLI commands with `--database` but no [`--account-key`](#account-key) The `default` user is associated with credentials stored under the `default` key in the `access_keys` file. For example, the following command: ```cli fauna query "Collection.all()" \ --database us/my_db ``` Is equivalent to: ```cli fauna query "Collection.all()" \ --database us/my_db \ --user default ``` ### [](#account-key)Account keys You can specify a Fauna [account key](../../../reference/http/reference/account-api/#section/Authentication) to authenticate CLI commands. The CLI uses the first account key found based on the following order of precedence: * The [`--account-key`](#account-key-flag) flag * The [`FAUNA_ACCOUNT_KEY`](#account-key-env-var) environment variable * Account keys in the `access_keys` file. These keys are typically created using an [interactive login](#interactive). For more information, see [How account key authentication works](#account-key-works). #### [](#account-key-flag)`--account-key` flag Use `--account-key` to provide an account key for a command. You must also provide a `--database` and an optional `--role`: ```cli # 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. #### [](#account-key-env-var)`FAUNA_ACCOUNT_KEY` environment variable You can specify a default account key using the `FAUNA_ACCOUNT_KEY` environment variable: ```bash export FAUNA_ACCOUNT_KEY="my_account_key" ``` #### [](#account-key-works)How account key authentication works Account key authentication works similarly to an [interactive login](#works). The CLI uses the account key to create a short-lived [scoped key](../../../learn/security/keys/#scoped-keys) for the `--database` and `--role`. The CLI uses the scoped key to authenticate [Fauna Core HTTP API](../../../reference/http/reference/core-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](#works). Unlike an [interactive login](#works), the user-provided account key isn’t stored in the `access_keys` file. User-provided account keys aren’t automatically refreshed. ### [](#secret)Secrets You can specify an [authentication secret](../../../learn/security/authentication/) for CLI commands. The CLI uses the first secret found based on the following order of precedence: * The [`--secret`](#secret-flag) flag * The [`FAUNA_SECRET`](#secret-env-var) environment variable * Secrets in the `secret_keys` file. These keys are typically created by the CLI using a Fauna account key. See [How interactive login works](#works) and [How account key authentication works](#account-key-works). #### [](#secret-flag)`--secret` flag Use `--secret` to directly provide a [database authentication secret](../../../learn/security/authentication/): ```cli # 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)Scoped keys If the `--secret` is a [key secret](../../../learn/security/keys/) with the `admin` role, you can use `--database` and `--role` to create and use a [scoped key](../../../learn/security/keys/#scoped-keys) that impersonates a [role](../../../learn/security/roles/) on a child database. If impersonating a user-defined role, the role must be defined in the child database. ```cli # 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](../../../learn/security/keys/#scoped-keys) in `--secret` and omit `--database` and `--role`: ```cli # 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 ``` #### [](#secret-env-var)`FAUNA_SECRET` environment variable You can specify a default secret using the `FAUNA_SECRET` environment variable: ```bash export FAUNA_SECRET="my_secret" ``` ### [](#local)Local Fauna container If you have [Docker](https://www.docker.com/) or a similar software installed and running, you can use [`fauna local`](commands/local/) to start a local [Fauna container](../../tools/docker/): ```cli # Starts a local Fauna container. # The container's name defaults to 'faunadb'. fauna local ``` Use `--database` to optionally create a database in the container. ```cli # 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`](commands/schema/push/). The schema is immediately applied to the database’s active schema with no prompts. ```cli # 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: ```cli # 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: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443). * `--secret` to `secret`, the default secret for the [top-level key](../../tools/docker/#secret) of Fauna container instances. The secret uses the admin role. You can override these arguments using the respective `--url` and `--secret` flags. #### [](#local-scoped-keys)Scoped keys for local containers When used with `--local`, the\`--database\` and optional `--role` flags let you create and use a [scoped key](../../../learn/security/keys/#scoped-keys). The scoped key impersonates a [role](../../../learn/security/roles/) on a database. If impersonating a user-defined role, the role must be defined in the database. ```cli # 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](../../tools/docker/#secret) for the Fauna container: ```cli # 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 ``` ## [](#config)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. ```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 # `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)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](commands/) to see supported flags. Unsupported or unrecognized settings/flags do not trigger errors. #### [](#common-settings)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:url to http://0.0.0.0:8443secret to secret | | 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. | #### [](#config-creds)Storing credentials in config files While supported, we don’t recommend using the `account-key` or `secret` settings to store [account keys](../../../reference/http/reference/account-api/#section/Authentication) or [database authentication secrets](../../../learn/security/authentication/) in interactive development environments. Instead, use [interactive login](#interactive) or the respective [FAUNA\_ACCOUNT\_KEY](#account-key-env-var) or [FAUNA\_SECRET](#secret-env-var) environment variables. For [CI/CD and automated workflows](#script-auth), you can create and store an [account key](../../../reference/http/reference/account-api/#section/Authentication) or [database authentication secret](../../../learn/security/authentication/) 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)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](#comp-log). ### [](#provide)Provide a config file The CLI uses the first config file found based on the following order of precedence: * The [`--config`](#config-flag) flag * The [`FAUNA_CONFIG`](#config-env-var) environment variable * A [default config file](#default), automatically detected based on filename If you provide a config file, you must also [specify a profile](#profile) to use. #### [](#config-flag)`--config` flag Use `--config` to provide a path to a config file to use. For example: ```cli # Use the `config.yml` config file. fauna query "2 + 2" \ --database us/my_db \ --config /path/to/config.yml ``` #### [](#config-env-var)`FAUNA_CONFIG` environment variable Use the `FAUNA_CONFIG` environment variable to specify a path to a config file to use. For example: ```bash export FAUNA_CONFIG="/path/to/config.yml" ``` #### [](#default)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. ### [](#profile)Specify a profile Use `--profile` to specify a profile from the [config file](#config). The profile specifies the group of [settings](#settings) in the config file to use. For example: ```cli # Use settings in the config file's `container` profile. fauna query "2 + 2" \ --database us/my_db \ --profile container ``` #### [](#profile-env-var)`FAUNA_PROFILE` environment variable Use the `FAUNA_PROFILE` environment variable to specify a default profile to use. For example: ```bash export FAUNA_PROFILE="container" ``` ## [](#flag-conventions)Flag conventions In the CLI, you pass arguments to a command using flags. For example: ```cli # Uses the `--database` flag for `fauna shell`. fauna shell \ --database us/my_db ``` Some flags also support a shorthand alias: ```cli # Uses the `-d` alias for `--database`. fauna shell \ -d us/my_db ``` ### [](#array-arguments)Array arguments Some flags, such `--verbose-component`, accept an array of values. To specify an array, you can use a space-separated list: ```cli # Passes `fetch` and `error` to `--verbose-component`. fauna shell \ --database us/my_db \ --verbose-component fetch error ``` Alternatively, you can use separate flags: ```cli # 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)Boolean arguments Some flags, such `--color`, accept a boolean value. If the flag is specified with no value, its value is `true`: ```cli # Passes a `--color` value of `true`. fauna shell \ --database us/my_db \ --color ``` Use the `--[no]-` prefix to pass a value of `false`: ```cli # Passes a `--color` value of `false`. fauna shell \ --database us/my_db \ --no-color ``` You can also use `=` to explicitly specify a boolean value: ```cli # Passes a `--color` value of `true`. fauna shell \ --database us/my_db \ --color=true ``` ### [](#multi-word-flags)Multi-word flags Flags that consist of multiple words support both kebab case and camel case: ```cli # Uses the `----account-key` flag. fauna query "Collection.all()" \ --account-key $MY_ACCOUNT_KEY \ --database us/my_db ``` ```cli # Uses the `--accountKey` alias for `--account-key`. fauna query "Collection.all()" \ --accountKey $MY_ACCOUNT_KEY \ --database us/my_db ``` ## [](#log)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`. ### [](#verbosity)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: ```cli # Only emits debug logs for warnings (3), errors (2), # and fatal messages (1). fauna query "Collection.all()" \ --database us/my_db \ --verbosity 3 ``` ### [](#comp-log)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: ```cli # 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: ```bash [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-log)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. ```cli # Only output the results of the command. fauna query "Collection.all()" \ --database us/my_db \ --quiet ``` ## [](#script)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](../../../learn/schema/manage-schema/#cicd). ### [](#best-practices)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 profile Use a [config file](#config) and [profiles](#profile) 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`](#config-env-var) environment variable. You can override a profile’s settings by explicitly passing a flag to a command. #### [](#script-auth)Authenticate using an account key or database secret The CLI supports several [authentication methods](#auth). For CI/CD and other automated workflows, we recommend you do one of the following: * Use the [`FAUNA_ACCOUNT_KEY`](#account-key-flag) or [`FAUNA_SECRET`](#secret-env-var) environment variables. * Create a temporary config file using your script or CI tool. In the config file, create and store an [account key](../../../reference/http/reference/account-api/#section/Authentication) or [database authentication secret](../../../learn/security/authentication/) with a short time-to-live (TTL) in the respective `account-key` or `secret` setting. Delete the config file after use. For example: ```yaml default: account-key: fnacapi_abc123 ``` #### [](#avoid-interactive-commands)Avoid interactive commands Avoid using commands, [`fauna shell`](commands/shell/) or [`fauna login`](commands/login/), that require user input. #### [](#disable-interactive-prompts)Disable interactive prompts Use `--input=false` or the corresponding [setting](#settings) to disable prompts for commands such as [`fauna schema push`](commands/schema/push/) or [`fauna schema commit`](commands/schema/commit/). To set `--input=false` as a setting in a config file: ```yaml # `ci` profile settings ci: input: false ``` #### [](#use-json-output-for-parsing)Use JSON output for parsing If you use a JSON parser, such as [jq](https://jqlang.github.io/jq/), enable JSON output for compatible commands by specifying `--json=true` or the corresponding `json` [setting](#settings). To set `--json=true` as a setting in a config file: ```yaml # `ci` profile settings ci: json: true ``` #### [](#set-timeouts-for-queries)Set timeouts for queries Use `--timeout` or the corresponding [setting](#settings) to set a maximum runtime, in milliseconds, for query requests made by [`fauna query`](commands/query/). To set `--timeout` as a setting in a config file: ```yaml # `ci` profile settings ci: timeout: 3000 ``` #### [](#customize-logging-as-needed)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](#log). ## [](#migrate)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 | 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 v4 commands | Globalfauna completionOutput an auto-complete script for CLI commands in bash or zsh.fauna localStart a local Fauna container.fauna loginLog in to Fauna using a web-based browser flow.fauna queryRun a provided FQL query.fauna shellRun FQL queries in an interactive REPL.Databasefauna database createCreate a database.fauna database deleteDelete a database.fauna database listList top-level or child databases.Exportfauna export createStart the export of a database or specified user-defined collections to a specified destination type.fauna export create s3Start an export to an AWS S3 bucket.fauna export getGet an export by its ID.fauna export listList exports.Schemafauna schema abandonAbandon a database’s staged schema.fauna schema commitApply a staged schema to a database.fauna schema diffShow the diff between a database’s local, staged, or active schema.fauna schema pullPull a database’s remote .fsl schema files into a local directory. By default, pulls the database’s staged schema.fauna schema pushPush a local directory of .fsl schema files to a database. By default, stages the schema.fauna schema statusShows a database’s staged schema status. | fauna completion | Output an auto-complete script for CLI commands in bash or zsh. | fauna local | Start a local Fauna container. | fauna login | Log in to Fauna using a web-based browser flow. | fauna query | Run a provided FQL query. | fauna shell | Run FQL queries in an interactive REPL. | fauna database create | Create a database. | fauna database delete | Delete a database. | fauna database list | List top-level or child databases. | fauna export create | Start the export of a database or specified user-defined collections to a specified destination type. | fauna export create s3 | Start an export to an AWS S3 bucket. | fauna export get | Get an export by its ID. | fauna export list | List exports. | fauna schema abandon | Abandon a database’s staged schema. | fauna schema commit | Apply a staged schema to a database. | fauna schema diff | Show the diff between a database’s local, staged, or active schema. | fauna schema pull | Pull a database’s remote .fsl schema files into a local directory. By default, pulls the database’s staged schema. | fauna schema push | Push a local directory of .fsl schema files to a database. By default, stages the schema. | fauna schema status | Shows a database’s staged schema status. | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | fauna completion | Output an auto-complete script for CLI commands in bash or zsh. | | fauna local | Start a local Fauna container. | | fauna login | Log in to Fauna using a web-based browser flow. | | fauna query | Run a provided FQL query. | | fauna shell | Run FQL queries in an interactive REPL. | | fauna database create | Create a database. | | fauna database delete | Delete a database. | | fauna database list | List top-level or child databases. | | fauna export create | Start the export of a database or specified user-defined collections to a specified destination type. | | fauna export create s3 | Start an export to an AWS S3 bucket. | | fauna export get | Get an export by its ID. | | fauna export list | List exports. | | fauna schema abandon | Abandon a database’s staged schema. | | fauna schema commit | Apply a staged schema to a database. | | fauna schema diff | Show the diff between a database’s local, staged, or active schema. | | fauna schema pull | Pull a database’s remote .fsl schema files into a local directory. By default, pulls the database’s staged schema. | | fauna schema push | Push a local directory of .fsl schema files to a database. By default, stages the schema. | | fauna schema status | Shows a database’s staged schema status. | # `fauna completion` ```cli-sig fauna completion ``` Output an auto-complete script for CLI commands in bash or zsh. To enable auto-complete, run [`fauna completion`](./) and append the command’s output to your `.bashrc`, `.bash_profile`, `.zshrc`, or `.zprofile`. ## [](#examples)Examples ```bash fauna completion >> ~/.bashrc fauna completion >> ~/.bash_profile fauna completion >> ~/.zshrc fauna completion >> ~/.zprofile ``` # `fauna database` ```cli-sig fauna database [flags] ``` Use `fauna database` commands to create and manage databases. ## [](#available-commands)Available commands * [`fauna database create`](create/) * [`fauna database delete`](delete/) * [`fauna database list`](list/) ## [](#aliases)Aliases ```cli-sig fauna db ``` # `fauna database create` ```cli-sig fauna database create --name [flags] ``` Create a [database](../../../../../../learn/data-model/databases/). Specify the child database’s name using `--name`. Use `--database` or `--secret` to specify the parent database. If using `--secret`, the parent database is the database to which the secret is scoped. To create a top-level database, specify a [region group identifier](../../../../../../manage/region-groups/#id) in `--database`. You can’t create a top-level database using `--secret`. ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). Can’t be used to create a [top-level database](../../../../../../learn/data-model/databases/#child). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--name ` (Required) Name of the database to create. To create a [child database](../../../../../../learn/data-model/databases/#child), specify the parent database using `--database` or `--secret`. If using `--secret`, the parent database is the database to which the secret is scoped. `--typechecked` Enable [typechecking](../../../../../../learn/query/static-typing/) for the database. Use `--no-typechecked` to disable. Defaults to enabled for top-level databases. Inherits the parent database’s setting for child databases. `--protected` Enable [protected mode](../../../../../../learn/schema/#protected-mode) for the database. `--priority ` User-defined priority for the database. Must be an integer. ## [](#examples)Examples ```cli # Create a top-level 'my_db' database # in the 'us' region group. fauna database create \ --name my_db \ --database us # Create a 'child_db' child database # directly under 'us/parent_db'. fauna database create \ --name child_db \ --database us/parent_db # Create a 'child_db' child database directly # under the database scoped to a secret. fauna database create \ --name child_db \ --secret my-secret # Create a database with typechecking enabled. fauna database create \ --name my_db \ --database us \ --typechecked # Create a database with protected mode enabled. fauna database create \ --name my_db \ --database us \ --protected ``` ## [](#aliases)Aliases ```cli-sig fauna db create ``` # `fauna database delete` ```cli-sig fauna database delete --name [flags] ``` Delete a [database](../../../../../../learn/data-model/databases/). Specify the child database’s name using `--name`. Use `--database` or `--secret` to specify the parent database. If using `--secret`, the parent database is the database to which the secret is scoped. To delete a top-level database, specify a [region group identifier](../../../../../../manage/region-groups/#id) in `--database`. You can’t create a top-level database using `--secret`. ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). Can’t be used to delete a [top-level database](../../../../../../learn/data-model/databases/#child). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. To delete a top-level database, only include the region group identifier. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--name ` (Required) Name of the database to delete. To delete a [child database](../../../../../../learn/data-model/databases/#child), specify the parent database using `--database` or `--secret`. If using `--secret`, the parent database is the database to which the secret is scoped. ## [](#examples)Examples ```cli # Delete the top-level 'my_db' database # in the 'us' region group. fauna database delete \ --name my_db \ --database us # Delete the 'child_db' database directly # under 'us/parent_db'. fauna database delete \ --name child_db \ --database us/parent_db # Delete a 'child_db' database directly under the # database scoped to a secret. fauna database delete \ --name child_db \ --secret my-secret ``` ## [](#aliases)Aliases ```cli-sig fauna db delete ``` # `fauna database list` ```cli-sig fauna database list ``` List top-level or child [databases](../../../../../../learn/data-model/databases/). To get top-level databases, omit `--database` and `--secret`. To get child databases, use `--database` or `--secret` to specify the parent database. If using `--secret`, the parent database is the database to which the secret is scoped. When using [interactive login](../../../#interactive) or an [account key](../../../#account-key), the command outputs the database’s name and path, including [Region Group identifier](../../../../../../manage/region-groups/#id) and hierarchy. Paths are not available when using a [secret](../../../#secret). ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--page-size ` Maximum number of databases to return. Defaults to `1000`. ## [](#examples)Examples ```cli # List all top-level databases. fauna database list # List all child databases directly # under the 'us/parent_db' database. fauna database list \ --database 'us/parent_db' # Get all child databases for the database # scoped to a secret. fauna database list \ --secret my-secret # List all top-level databases and output as JSON. fauna database list \ --json # List the first 10 top-level databases. fauna database list \ --page-size 10 ``` ## [](#aliases)Aliases ```cli-sig fauna db list ``` # `fauna export` ```cli-sig fauna export [flags] ``` Use `fauna export` commands to create and manage [exports](../../../../../manage/exports/) for a Fauna account. An export stores document data from a database or specified user-defined collections in a specified [AWS S3 bucket](https://aws.amazon.com/s3/). To use exports, you must: * Have an Enterprise plan. * Be an owner, admin, or developer for your Fauna account. See [Team management](../../../../../manage/team-management/) . `fauna export` commands do not support `--secret`, `--local`, or Fauna containers. ## [](#available-commands)Available commands * [`fauna export create`](create/) * [`fauna export get`](get/) * [`fauna export list`](list/) # `fauna export create` ```cli-sig fauna export create ``` Start the [export](../../../../../../manage/exports/) of a database or specified user-defined collections to a specified destination type. Currently only [AWS S3 bucket](https://aws.amazon.com/s3/) are supported as a destination type. See [`fauna export create s3`](s3/) . To use exports, you must: * Have an Enterprise plan. * Be an owner, admin, or developer for your Fauna account. See [Team management](../../../../../../manage/team-management/) . `fauna export create` commands do not support `--secret`, `--local`, or Fauna containers. ## [](#available-commands)Available commands * [`fauna export create s3`](s3/) # `fauna export create s3` ```cli-sig fauna export create s3 [flags] ``` Start an [export](../../../../../../../manage/exports/) to an [AWS S3 bucket](https://aws.amazon.com/s3/). Export operations are asynchronous. Export requests aren’t idempotent. By default, the command outputs the export’s ID. To get additional information about the export as JSON, use `--json`. To use exports, you must: * Have an Enterprise plan. * Be an owner, admin, or developer for your Fauna account. See [Team management](../../../../../../../manage/team-management/) . `fauna export create s3` does not support `--secret`, `--local`, or Fauna containers. ## [](#flags)Flags API `--account-key ` Fauna [account key](../../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../../login/). Defaults to [`default`](../../../../#default-user). See [Interactive login](../../../../#interactive). `-r`, `--role ` [Role](../../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. `-d`, `--database ` Database, including the [region group identifier](../../../../../../../manage/region-groups/#id) and hierarchy, to export. Supports [shorthand region group identifiers](../../../../../../../manage/region-groups/#id). Separate path components using `/`. Examples: `us/my_db`, `eu/parent_db/child_db`, `global/db`. [Child databases](../../../../../../../learn/data-model/databases/#child) are not included in the export. `--collection ` User-defined collections from the database to export. Pass values as a space-separated list. Example: `--collection Product Category`. If omitted, all user-defined collections are exported. You can’t export [system collections](../../../../../../../learn/data-model/collections/#system-coll). `--bucket ` (Required) Name of the S3 bucket where the export will be stored. `--path ` (Required) Path prefix for the destination S3 bucket. Separate subfolders using a slash (`/`). A trailing slash is supported but not required. `--format ` (Required) [Data format](../../../../../../../reference/http/reference/wire-protocol/#tagged) used to convert the database’s FQL document data to JSON. Accepts [`tagged`](../../../../../../../reference/http/reference/wire-protocol/#tagged) or [`simple`](../../../../../../../reference/http/reference/wire-protocol/#simple). Defaults to `simple`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../../#config) to use. If provided, must [specify a profile](../../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../../#config). A profile is a group of [CLI settings](../../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `-w`, `--wait`, `--watch` Wait for the export to complete or fail before exiting. Polls for the export’s state using an exponential backoff strategy. Use '--max-wait' to set a timeout. `--max-wait ` Maximum wait time in minutes. Defaults to 120 minutes. ## [](#examples)Examples ```cli # Export all user-defined collections in # the 'us/parent_db/child_db' database. Store the export # in the 'fauna_exports/parent_db/child_db/2099-12-31' # path of the 'doc-example-bucket' S3 bucket. Format FQL data # using the simple data format. fauna export create s3 \ --database us/parent_db/child_db \ --bucket doc-example-bucket \ --path fauna_exports/parent_db/child_db/2099-12-31 # Export the 'Product' and 'Category' collections in # the 'us/parent_db/child_db' database. fauna export create s3 \ --database us/parent_db/child_db \ --collection Product Category \ --bucket doc-example-bucket \ --path fauna_exports/parent_db/child_db/2099-12-31 # Encode the export's FQL document data # using the 'tagged' format. fauna export create s3 \ --database us/parent_db/child_db \ --bucket doc-example-bucket \ --path fauna_exports/parent_db/child_db/2099-12-31 \ --format tagged # Wait for the export to complete or fail before exiting. # Waits up to 180 minutes. fauna export create s3 \ --database us/parent_db/child_db \ --bucket doc-example-bucket \ --path fauna_exports/parent_db/child_db/2099-12-31 \ --wait \ --max-wait 180 ``` # `fauna export get` ```cli-sig fauna export get [flags] ``` Get an [export](../../../../../../manage/exports/) by its ID. By default, the command outputs the export’s information as YAML. To get the information as JSON, use `--json`. To use exports, you must: * Have an Enterprise plan. * Be an owner, admin, or developer for your Fauna account. See [Team management](../../../../../../manage/team-management/) . `fauna export get` does not support `--secret`, `--local`, or Fauna containers. ## [](#positional-arguments)Positional arguments `` (Required) ID of the export to retrieve. ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. API `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `-w`, `--wait`, `--watch` Wait for the export to complete or fail before exiting. Polls for the export’s state using an exponential backoff strategy. Use '--max-wait' to set a timeout. `--max-wait ` Maximum wait time in minutes. Defaults to 120 minutes. ## [](#examples)Examples ```cli # Get an export with an ID of '123456789'. fauna export get 123456789 # Get an export as JSON. fauna export get 123456789 \ --json # Wait for the export to complete or fail before exiting. # Waits up to 180 minutes. fauna export get 123456789 \ --wait \ --max-wait 180 ``` # `fauna export list` ```cli-sig fauna export list [flags] ``` List [exports](../../../../../../manage/exports/). By default, the command outputs the export list as tab-separated values (TSV). To get the list as JSON, use `--json`. Exports are ordered by state and descending export ID. To use exports, you must: * Have an Enterprise plan. * Be an owner, admin, or developer for your Fauna account. See [Team management](../../../../../../manage/team-management/) . `fauna export list` does not support `--secret`, `--local`, or Fauna containers. ## [](#flags)Flags API `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. `--max`, `--max-results ` Maximum number of exports to return per page. Accepts `1` to `1000`. Defaults to `100`. `--state ` Filter exports by their state. Accepts one or more of the following: * `Pending`: The export request has been received but is not yet in progress. * `InProgress`: The export is in progress. This includes copying the export files to the S3 bucket. * `Complete`: The export is complete. Export files are available in the S3 bucket. * `Failed`: There was an error processing the export. Pass values as a space-separated list. Example: `--state Pending Complete`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. ## [](#examples)Examples ```cli # List exports in TSV format. fauna export list # List exports in JSON format. fauna export list \ --json # List up to 50 exports. fauna export list \ --max-results 50 # List exports in the 'Pending' or # 'Complete' state. fauna export list \ --state Pending Complete ``` # `fauna local` ```cli-sig fauna local [flags] ``` Start a local [Fauna container](../../../../tools/docker/). Once started, use the `--local` flag to run CLI commands in the container. See [Use a Local Fauna container with the CLI](../../#local). To use this command, you must have [Docker](https://www.docker.com/) or similar software installed and running. The command uses health checks to determine whether the container is ready. The checks ping the container at regular intervals until a successful response is received or the maximum number of attempts is reached. You can configure the checks using `--interval` and `--max-attempts`. Use `--database` to optionally create a database in the container. Use `--typechecked`, `--protected`, and `--priority` to configure the database. When creating a database, use `--dir` to push a local directory of `.fsl` schema files to the database using [`fauna schema push`](../schema/push/). The schema is immediately applied to the database’s active schema with no prompts. ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../#config) to use. If provided, must [specify a profile](../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../#config). A profile is a group of [CLI settings](../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--container-port ` Port inside the container where the Fauna instance listens for requests. Defaults to `8443`. `--host-port ` Port on your host machine that maps to the `--container-port`. The CLI and other external clients can send HTTP API requests to Fauna using this port. Defaults to `8443`. `--host-ip ` IP address to bind the container’s port to. Defaults to `0.0.0.0`. `--interval ` Interval, in milliseconds, between health check attempts. How often the CLI checks if the container is ready. Defaults to `10000`. Must be greater than or equal to `0`. `--max-attempts ` Maximum number of health check attempts allowed before container startup fails. Defaults to `100`. Must be greater than `0`. `--name ` Name for the container. Defaults to `faunadb`. `--pull` Pull the latest [`fauna/faunadb`](https://hub.docker.com/r/fauna/faunadb) image before starting the container. Defaults to true. Use `--no-pull` to disable. `--database ` Name of the database to create. Omit to create no database. `--typechecked` Enable [typechecking](../../../../../learn/query/static-typing/) for the database. Use `--no-typechecked` to disable. Defaults to enabled for databases in a Fauna container. Only valid if `--database` is set. `--protected` Enable [protected mode](../../../../../learn/schema/#protected-mode) for the database. Only valid if `--database` is set. `--priority ` User-defined priority for the database. Must be an integer. Only valid if `--database` is set. `--fsl-directory`, `--dir`, `--directory ` Path to a local directory containing `.fsl` files for the database. Recursively scans subdirectories. Defaults to the current directory (`.`). Only valid if `--database` is set. ## [](#examples)Examples ```cli # Start a local Fauna container with # default name and ports. fauna local # Start a container named 'local-fauna'. fauna local \ --name local-fauna # Map host port `1234` to container port `6789`. # Equivalent to `-p 1234:6789` in Docker. fauna local \ --host-port 1234 \ --container-port 6789 # Start a local Fauna container. # Create the 'my_db' database in the container. fauna local \ --database my_db # Start a local Fauna container. # Create the 'my_db' database in the container. # Immediately apply changes to the 'my_db' database's # active schema. fauna local \ --database my_db \ --dir /path/to/schema/dir ``` # `fauna login` ```cli-sig fauna login [flags] ``` Log in to Fauna using a web-based browser flow. This command is used to set up authentication using an [interactive login](../../#interactive). Use `--user` to specify a user to log in as. If omitted, `--user` defaults to [`default`](../../#default-user). The `--user` argument can be any string. `--user` is only used by the CLI to store and retrieve Fauna [account keys](../../../../../reference/http/reference/account-api/#section/Authentication). The `--user` is not passed to Fauna itself. See [How interactive login works](../../#works). After logging in, you can authenticate other CLI commands by specifying the `--user`, a `--database`, and an optional `--role`. You can’t use this command to log in to or authenticate with a local [Fauna container](../../../../tools/docker/). See [local Fauna container authentication](../../#local). 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)](https://learn.microsoft.com/en-us/windows/wsl/about) 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. ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../#config) to use. If provided, must [specify a profile](../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../#config). A profile is a group of [CLI settings](../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `-r`, `--redirect` Log in using a local callback server (default). Use `--no-redirect` if you are unable to open a browser on your local machine. See [Log in without redirects](../../#no-redirect). `-u`, `--user ` User to log in as. Defaults to [`default`](../../#default-user). ## [](#examples)Examples ```cli # Log in as the 'default' user. fauna login # Log in as the `john_doe` user. fauna login \ --user john_doe # Log in without redirecting to a callback server. fauna login \ --user john_doe \ --no-redirect ``` # `fauna query` ```cli-sig fauna eval [] [flags] ``` Run a provided [FQL query](../../../../../learn/query/). You can provide the query as a positional `` query string. To read the query from `stdin`, use `-` as the query string. You can also use `--input` to provide the query as a file. Queries run in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, queries run in the database to which the secret is scoped. By default, FQL v10 query results are output as copy-pastable FQL. To get results in JSON, use `--format json` or `--json`. JSON results are encoded using the [simple data format](../../../../../reference/http/reference/wire-protocol/#simple). ## [](#positional-arguments)Positional arguments `` FQL query string to run. Use `-` to read from `stdin`. ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../login/). Defaults to [`default`](../../#default-user). See [Interactive login](../../#interactive). `--local` Use a local [Fauna container](../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../manage/region-groups/#id). 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](../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. `-v`, `--api-version ` FQL version to use. Accepts one of the following: * `10` (Default): [FQL v10](../../../../../reference/fql/quick-look/) * `4`: [FQL v4](https://docs.fauna.com/fauna/v4/api/fql/cheat_sheet/) `-f`, `--format ` Output format for query results. Accepts `fql` (Default) and `json`. Only applies to FQL v10 queries. `--json` overrides `--format`. `--typecheck` Enable query [typechecking](../../../../../learn/query/static-typing/). Only applies to FQL v10 queries. If omitted, uses the typechecking setting of the database. `--timeout ` Maximum query runtime, in milliseconds. `--performance-hints` Output [performance hints](../../../../../learn/query/performance-hints/). Sets `--include summary`. Only applies to FQL v10 queries. If no performance hints are returned, no hints are output. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../#config) to use. If provided, must [specify a profile](../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../#config). A profile is a group of [CLI settings](../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--include ` Include additional query response data in the output. Only applies to FQL v10 queries. Accepts the following values: * `all` * `none` * `txnTs` * `schemaVersion` * `summary` * `queryTags` * `stats` Defaults to only `summary`. Pass values as a space-separated list, such as `--include summary queryTags`. Each value corresponds to a field from the [query response](../../../../../reference/http/reference/core-api/#operation/query). `-i`, `--input ` Path to a file containing an FQL query to run. Can’t be used with the `` positional argument. The file can use any file extension. `.fql` is recommended. `-o`, `--output ` Path to a file where query results are written. If omitted, writes to `stdout`. ## [](#examples)Examples ```cli # Run the query in the 'us/my_db' database and write # the results to stdout. fauna query "Collection.all()" \ --database us/my_db # Run the query in the 'us/my_db' database using the # server role. fauna query "Collection.all()" \ --database us/my_db \ --role server # Run the query in the database scoped to a secret. fauna query "Collection.all()" \ --secret my-secret # Run the query from a file. fauna query \ --input /path/to/query.fql \ --database us/my_db # Run the query from stdin. echo "1 + 1" | fauna query - \ --database us/my_db # Run the query and write the results to a file. fauna query \ --input /path/to/query.fql \ --output /tmp/result.json \ --database us/my_db ``` ## [](#aliases)Aliases ```cli-sig fauna eval ``` # `fauna schema` ```cli-sig fauna schema [flags] ``` Use `fauna schema` commands to create and manage [database schema](../../../../../learn/schema/) as `.fsl` schema files. ## [](#available-commands)Available commands * [`fauna schema abandon`](abandon/) * [`fauna schema commit`](commit/) * [`fauna schema diff`](diff/) * [`fauna schema pull`](pull/) * [`fauna schema push`](push/) * [`fauna schema status`](status/) # `fauna schema abandon` ```cli-sig fauna schema abandon [flags] ``` Abandon a database’s [staged schema](../../../../../../learn/schema/manage-schema/#staged). You run this command as part of a [staged schema change](../../../../../../learn/schema/manage-schema/#staged). You can abandon a staged schema at any time, including a schema with the `ready` status using [status](../status/). This is useful when you want to discard changes that are no longer needed or failed during staging. The command runs in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, the command runs in the database to which the secret is scoped. If the database has no staged schema, the command returns an error. ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--input` Prompt for user input. Defaults to true. To disable prompts, use `--no-input`. ## [](#examples)Examples ```cli # Abandon staged schema for the 'us/my_db' database. fauna schema abandon \ --database us/my_db # Abandon staged schema for the database scoped to a secret fauna schema abandon \ --secret my-secret # Run the command without input prompts. fauna schema abandon \ --database us/my_db \ --no-input ``` # `fauna schema commit` ```cli-sig fauna schema commit [flags] ``` Apply a [staged schema](../../../../../../learn/schema/manage-schema/#staged) to a database. You run this command as part of a [staged schema change](../../../../../../learn/schema/manage-schema/#staged). You can only apply a staged schema that has a status of `ready`. You can check a database’s staged schema status using [`fauna schema status`](../status/). The command runs in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, the command runs in the database to which the secret is scoped. If the database has no staged schema, the command returns an error. ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--input` Prompt for user input. Defaults to true. To disable prompts, use `--no-input`. ## [](#examples)Examples ```cli # Commit staged schema for the 'us/my_db' database. fauna schema commit \ --database us/my_db # Commit staged schema for the database scoped to a secret. fauna schema commit \ --secret my-secret # Run the command without prompts. fauna schema commit \ --database us/my_db \ --no-input ``` # `fauna schema diff` ```cli-sig fauna schema diff [flags] ``` Show the diff between a database’s local, [staged](../../../../../../learn/schema/manage-schema/#staged), or active schema. The command runs in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, the command runs in the database to which the secret is scoped. By default, the command compares the database’s staged schema to schema in a local directory, specified using `--dir`. If no schema is staged, it compares the database’s active schema to the local schema. Use `--active` to compare the database’s active schema to the local schema, regardless of whether schema is staged. Use `--staged` to compare the database’s active schema to its local schema. ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--staged` Show the diff between the active and [staged schema](../../../../../../learn/schema/manage-schema/#staged). `--text` Show a text diff that contains line-by-line changes, including comments and whitespace. `--active` Show the diff between the active and local schema. `--fsl-directory`, `--dir`, `--directory ` Path to a local directory containing `.fsl` files for the database. Recursively scans subdirectories. Defaults to the current directory (`.`). ## [](#examples)Examples ```cli # Compare the database's staged schema to the local schema. # If no schema is staged, compare the database's active # schema to the local schema. fauna schema diff \ --database us/my_db \ --dir /path/to/schema/dir # Compare the active schema of the database scoped to a # secret to the local schema. fauna schema diff \ --secret my-secret \ --dir /path/to/schema/dir \ --active # Compare the 'us/my_db' database's active schema to the # local schema. fauna schema diff \ --database us/my_db \ --dir /path/to/schema/dir \ --active # Compare the 'us/my_db' database's active schema to its # staged schema. fauna schema diff \ --database us/my_db \ --dir /path/to/schema/dir \ --staged # Show a text diff instead of a semantic diff. fauna schema diff \ --database us/my_db \ --dir /path/to/schema/dir \ --text ``` # `fauna schema pull` ```cli-sig fauna schema pull [flags] ``` Pull a database’s remote `.fsl` schema files into a local directory. By default, pulls the database’s staged schema. If the database has no staged schema, the command pulls the database’s active schema by default. To explicitly pull the database’s active schema, use `--active`. The command runs in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, the command runs in the database to which the secret is scoped. Specify the local directory using `--dir`. To delete any schema files in the local directory that are not part of the pulled database schema, use `--delete`. ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--delete` Delete `.fsl` files in the local directory that are not part of the pulled schema. `--active` Pull the database’s active schema files. Defaults to false. If omitted, pull the database’s [staged schema](../../../../../../learn/schema/manage-schema/#staged), if available. `--fsl-directory`, `--dir`, `--directory ` Path to a local directory containing `.fsl` files for the database. Recursively scans subdirectories. Defaults to the current directory (`.`). ## [](#examples)Examples ```cli # Pull the 'us/my_db' database's staged schema. # If the database has no staged schema, pull the # active schema. fauna schema pull \ --database us/my_db \ --dir /path/to/schema/dir # Pull the staged schema for the database scoped # to a secret. fauna schema pull \ --secret my-secret \ --dir /path/to/schema/dir # Pull the 'us/my_db' database's active schema. fauna schema pull \ --database us/my_db \ --dir /path/to/schema/dir \ --active # Delete `.fsl` files in the local directory # that are not part of the pulled schema. fauna schema pull \ --database us/my_db \ --dir /path/to/schema/dir \ --delete ``` # `fauna schema push` ```cli-sig fauna schema push [flags] ``` Push a local directory of `.fsl` schema files to a database. By default, [stages the schema](../../../../../../learn/schema/manage-schema/#staged). The command runs in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, the command runs in the database to which the secret is scoped. Specify the local directory using `--dir`. Use `--active` to immediately apply the local schema to the database’s active schema. This skips staging the schema. However, If the local schema includes [index definition](../../../../../../reference/fql-api/collection/indexes/) changes, related indexes may be temporarily unavailable due to [index builds](../../../../../../learn/data-model/indexes/#builds). ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--input` Prompt for user input. Defaults to true. To disable prompts, use `--no-input`. `--active` Immediately apply the local schema to the database’s active schema. Skip [staging the schema](../../../../../../learn/schema/manage-schema/#staged). If the local schema includes [index definition](../../../../../../reference/fql-api/collection/indexes/) changes, related indexes may be temporarily unavailable due to [index builds](../../../../../../learn/data-model/indexes/#builds). `--fsl-directory`, `--dir`, `--directory ` Path to a local directory containing `.fsl` files for the database. Recursively scans subdirectories. Defaults to the current directory (`.`). ## [](#examples)Examples ```cli # Stage schema changes for the 'us/my_db' database. # If schema is already staged, replace the staged schema. fauna schema push \ --database us/my_db \ --dir /path/to/schema/dir # Stage schema changes for the database scoped to a secret. # If schema is already staged, replace the staged schema. fauna schema push \ --secret my-secret \ --dir /path/to/schema/dir # Immediately apply changes to the 'us/my_db' database's # active schema. fauna schema push \ --database us/my_db \ --dir /path/to/schema/dir \ --active # Run the command without prompts fauna schema push \ --database us/my_db \ --dir /path/to/schema/dir \ --no-input ``` # `fauna schema status` ```cli-sig fauna schema status [flags] ``` Shows a database’s [staged schema status](../../../../../../learn/schema/manage-schema/#staged). The status indicates whether [index builds](../../../../../../learn/data-model/indexes/#builds) for the schema changes are complete. The commands also outputs diffs between the database’s * Active and staged schema * Active and local schema in the `--dir` The command runs in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, the command runs in the database to which the secret is scoped. ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../../login/). Defaults to [`default`](../../../#default-user). See [Interactive login](../../../#interactive). `--local` Use a local [Fauna container](../../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../../manage/region-groups/#id). 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](../../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../../#config) to use. If provided, must [specify a profile](../../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../../#config). A profile is a group of [CLI settings](../../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--version` Show the Fauna CLI version. `--fsl-directory`, `--dir`, `--directory ` Path to a local directory containing `.fsl` files for the database. Recursively scans subdirectories. Defaults to the current directory (`.`). ## [](#examples)Examples ```cli # Get the staged schema status for the 'us/my_db' database. fauna schema status \ --database us/my_db # Get the staged schema status for the database # scoped to a secret. fauna schema status \ --secret my-secret ``` # `fauna shell` ```cli-sig fauna shell [flags] ``` Run [FQL queries](../../../../../learn/query/) in an interactive REPL. Queries run in the context of a single database, specified using `--database` or `--secret`. If using `--secret`, queries run in the database to which the secret is scoped. By default, FQL v10 query results are output as copy-pastable FQL. To get results in JSON, use `--format json` or `--json`. JSON results are encoded from FQL using the [simple data format](../../../../../reference/http/reference/wire-protocol/#simple). REPL session history is stored at: * Linux, macOS, Unix: `~/.fauna/history` * Windows: `%userprofile%\.fauna\history` ## [](#flags)Flags API `-u`, `--user ` CLI user to run the command as. You must first log in as the user using [`fauna login`](../login/). Defaults to [`default`](../../#default-user). See [Interactive login](../../#interactive). `--local` Use a local [Fauna container](../../../../tools/docker/). If not otherwise specified, this flag sets: * `--url` to [http://0.0.0.0:8443](http://0.0.0.0:8443) * `--secret` to `secret` `--url ` URL for [Core HTTP API requests](../../../../../reference/http/reference/core-api/) made by the command. Defaults to [https://db.fauna.com](https://db.fauna.com). `--secret ` [Secret](../../../../../learn/security/authentication/) used for authentication. Supports [scoped keys](../../../../../learn/security/keys/#scoped-keys). The command runs in the database to which the secret is scoped. If the secret is a [key secret](../../../../../learn/security/keys/) with the `admin` role, you can pass this flag with `--database` and an optional `--role` to create and use a [scoped key](../../../../../learn/security/keys/#scoped-keys) that impersonates a role on a child database. See [Scoped keys](../../#scoped-keys). `--account-key ` Fauna [account key](../../../../../reference/http/reference/account-api/#section/Authentication) used for authentication. If used, you must also provide a `--database` and an optional `--role`. See [Account key authentication](../../#account-key). Can’t be used with `--user` or `--secret`. If `--account-key` and `--user` are specified, `--user` is ignored. `-d`, `--database ` Database, including the [region group identifier](../../../../../manage/region-groups/#id) and hierarchy, to run the command in. Supports [shorthand region group identifiers](../../../../../manage/region-groups/#id). 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](../../#local), omit the region group. `-r`, `--role ` [Role](../../../../../learn/security/roles/) used to run the command. Defaults to [`admin`](../../../../../learn/security/roles/#built-in-roles). Can’t be used with `--secret`. `-v`, `--api-version ` FQL version to use. Accepts one of the following: * `10` (Default): [FQL v10](../../../../../reference/fql/quick-look/) * `4`: [FQL v4](https://docs.fauna.com/fauna/v4/api/fql/cheat_sheet/) `-f`, `--format ` Output format for query results. Accepts `fql` (Default) and `json`. Only applies to FQL v10 queries. `--json` overrides `--format`. `--typecheck` Enable query [typechecking](../../../../../learn/query/static-typing/). Only applies to FQL v10 queries. If omitted, uses the typechecking setting of the database. `--timeout ` Maximum query runtime, in milliseconds. `--performance-hints` Output [performance hints](../../../../../learn/query/performance-hints/). Sets `--include summary`. Only applies to FQL v10 queries. If no performance hints are returned, no hints are output. Use the [`.toggleInfo`](#togg-info) REPL command to enable or disable output of `--include` info in a session. Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. This flag doesn’t affect error output. `--quiet` Suppress all log messages except fatal errors. Output only command results. Overrides `--verbosity` and `--verbose-component`. Config `--config ` Path to a CLI [config file](../../#config) to use. If provided, must [specify a profile](../../#provide). `-p`, `--profile ` Profile from the CLI [config file](../../#config). A profile is a group of [CLI settings](../../#settings). Debug `--verbose-component ` Components to emit logs for. Overrides `--verbosity`. Accepts the following values: * `argv` * `config` * `creds` * `error` * `fetch` Pass values as a space-separated list. Example: `--verbose-component argv config`. `--verbosity ` Least critical log level to emit. Accepts integers ranging from `1` (fatal) to `5` (debug). Lower values represent more critical logs. Log messages with a level greater than this value are not logged. Options `-h`, `--help` Show help. `--include ` Include additional query response data in the output. Only applies to FQL v10 queries. Accepts the following values: * `all` * `none` * `txnTs` * `schemaVersion` * `summary` * `queryTags` * `stats` Defaults to only `summary`. Pass values as a space-separated list, such as `--include summary queryTags`. Each value corresponds to a field from the [query response](../../../../../reference/http/reference/core-api/#operation/query). Use the [`.toggleInfo`](#togg-info) REPL command to enable or disable output of `--include` info in a session. ## [](#examples)Examples ```cli # Run queries in the 'us/my_db' database. fauna shell \ --database us/my_db # Run queries in the 'us/my_db' database. # using the 'server' role. fauna shell \ --database us/my_db \ --role server # Run queries in the database scoped to a secret. fauna shell \ --secret my-secret ``` ## [](#repl-cmd)REPL commands REPL sessions support the following commands: `.break` Sometimes you get stuck. This gets you out. `.clear` Clear the REPL. `.clearhistory` Clear the REPL session history in `~/.fauna/history`. `.editor` Enter editor mode for multi-line queries. `.exit` Exit the REPL. `.help` Get a list of supported REPL commands. `.lastError` Display the most recent error encountered in the REPL. `.load` Load FQL queries from a file into the REPL session. `.save` Save all evaluated FQL queries from the REPL session to a file. `.toggleInfo` Enable or disable additional response data in results. If enabled, outputs fields listed in [`--include`](#include). Enabled by default. `.togglePerformanceHints` Enable or disable [performance hints](../../../../../learn/query/performance-hints/). Only applies to FQL v10 queries. Disabled by default. If no performance hint is returned, no hint is included in the output.