# Fauna CLI v4 | Version: 4.0.0-beta | Package: fauna-shell@4.0.0-beta | | --- | --- | --- | --- | The Fauna CLI lets you access Fauna from your terminal. You can use the CLI to: * 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.x or later * A Fauna account. You can sign up for a free account at [https://dashboard.fauna.com/register](https://dashboard.fauna.com/register). ## [](#quick-start)Quick start To get started: 1. Install the CLI: ```bash npm install -g fauna-shell@">=4.0.0-beta" ``` 2. For bash or zsh, enable auto-complete by appending 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. Run CLI commands. Specify a `--database`, including the [Region Group](../../../manage/region-groups/#id) and hierarchy, to run the command in. For example: ```cli # Runs a query in the top-level 'my_db' database # in the 'us' Region Group. Use the default admin role. fauna query "Collection.all()" \ --database us/my_db ``` ## [](#install)Installation To install the beta Fauna CLI globally: ```bash npm install -g fauna-shell@">=4.0.0-beta" ``` ## [](#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 ``` #### [](#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 an authentication secret: ```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 You can pass a [scoped key](../../../learn/security/keys/#scoped-keys) in `--secret` to run commands in a child database or one of its descendants: ```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 ``` To be used as a scoped key, the original secret must: * Be a [key secret](../../../learn/security/keys/) * Have the `admin` role #### [](#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 passed with `--local`, you can use `--database` and an optional `--role` to create and use a [scoped key](../../../learn/security/keys/#scoped-keys) that impersonates a [built-in role](../../../learn/security/roles/#built-in-roles) on a child database or one of its descendants: ```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 ``` You can’t use this method if you provide a `--secret`. ## [](#config)Configuration The CLI lets you pass settings from a YAML (`.yml`, `.yaml`) or JSON (`.json`) config file as arguments in CLI commands. The file is organized into profiles, letting you use different groups of settings for different environments or use cases. ```yaml # `dev` profile settings dev: color: true database: us/my_db # `container` profile settings container: local: true ``` ### [](#settings)Settings A config file’s settings are passed as CLI command flags. Each setting maps directly to a CLI flag. For example, the `database` setting is passed as the `--database` flag. Unrecognized settings and flags do not trigger errors. ### [](#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. | 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. #### [](#authenticate-using-a-secret-or-access-key)Authenticate using a secret or access key Use the [`FAUNA_ACCOUNT_KEY`](#account-key-flag) or [`FAUNA_SECRET`](#secret-env-var) environment variables to authenticate CLI commands. These authentication methods don’t require user interaction. Don’t store secrets, such as [authentication secrets](../../../learn/security/authentication/) or [account keys](../../../reference/http/reference/account-api/#section/Authentication), in config files. #### [](#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/), use `--json=true` or the corresponding [setting](#settings) to get JSON output from commands. 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). # 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.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 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 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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. 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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. 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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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 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. `--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). ## [](#flags)Flags Output `--color` Enable color formatting for output. Enabled by default. Use `--no-color` to disable. `--json` Output results as JSON. `--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. `-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 ``` # `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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. Only applies to FQL v10 queries. `--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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. `--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 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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. `--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` Pass this flag with `--database` and an optional `--role` to [create a scoped key](../../../../../learn/security/keys/#scoped-keys) that impersonates a built-in role on a child database. `--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. Can’t be used with `--database` or `--role`. `--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. Only applies to FQL v10 queries. `--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. `--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.