fauna shell

fauna shell [flags]

Run FQL queries 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.

REPL session history is stored at:

  • Linux, macOS, Unix: ~/.fauna/history

  • Windows: %userprofile%\.fauna\history

Flags

API
-u, --user <string>

CLI user to run the command as. You must first log in as the user using fauna login. Defaults to default. See Interactive login.

--local

Use a local Fauna container.

If not otherwise specified, this flag sets:

--url <string>

URL for Core HTTP API requests made by the command. Defaults to https://db.fauna.com.

--secret <string>

Secret used for authentication. Supports scoped keys. The command runs in the database to which the secret is scoped.

If the secret is a key secret with the admin role, you can pass this flag with --database and an optional --role to create and use a scoped key that impersonates a role on a child database. See Scoped keys.

--account-key <string>

Fauna account key used for authentication. If used, you must also provide a --database and an optional --role. See Account key authentication.

Can’t be used with --user or --secret. If --account-key and --user are specified, --user is ignored.

-d, --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.

-r, --role <string>

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

-v, --api-version <number>

FQL version to use. Accepts one of the following:

-f, --format <string>

Output format for query results. Accepts fql (Default) and json. Only applies to FQL v10 queries. --json overrides --format.

--typecheck

Enable query typechecking. Only applies to FQL v10 queries. If omitted, uses the typechecking setting of the database.

--timeout <number>

Maximum query runtime, in milliseconds.

--performance-hints

Output performance hints. Sets --include summary. Only applies to FQL v10 queries. If no performance hints are returned, no hints are output.

Use the .toggleInfo 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 <string>

Path to a CLI config file to use. If provided, must specify a profile.

-p, --profile <string>

Profile from the CLI config file. A profile is a group of CLI settings.

Debug
--verbose-component <array>

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

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

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.

Use the .toggleInfo REPL command to enable or disable output of --include info in a session.

Examples

# 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 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. Enabled by default.

.togglePerformanceHints

Enable or disable performance hints. Only applies to FQL v10 queries. Disabled by default. If no performance hint is returned, no hint is included in the output.

\