Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

fauna shell

Start an interactive Fauna session to run queries.

Syntax

fauna shell [<DB_PATH>] [--endpoint <value>] [--environment <value>]
  [--file <value>] [--format json|json-tagged|shell] [--output <value>]
  [--secret <value>] [--stdin] [--timeout <value>] [--typecheck]
  [--url <value>] [--version 4|10]

Description

The shell command starts an interactive query shell for sending Fauna database queries.

By default, this command supports FQL v10 queries. For FQL v4 queries, use the --version 4 option.

FQL v4 access

Fauna accounts created after August 21, 2024 can’t use --version 4 or otherwise run FQL v4 queries.

You can’t use this command to run queries against a parent or peer database.

Arguments

Argument Description

<DB_PATH>

Database path.

Options

Option Description

--endpoint

Connection endpoint from .fauna-shell.

--environment

Environment to use, from a Fauna project.

--file

Name of file with queries to run.

--format

Output format:
     json
     json-tagged
     shell

--help

Help for run-queries command.

--output

File to write output to.

--secret

Authentication secret. Overrides the secret in .fauna-shell.

Use a scoped key to interact with a child database using a parent database’s admin key.

For example, with a parent database’s admin key secret of fn123, you can access a child database by appending the child database name and role: fn123:childDB:admin.

--stdin

Read file input from stdin. Write to stdout by default.

--timeout

Connection timeout (milliseconds).

--typecheck

Enable typechecking.

--url

Database URL. Overrides the URL in .fauna-shell.

--version

FQL Version:
     4 = FQL version 4
     10 = (default) FQL version 10

See FQL v4 access.

Example

Start the shell:

fauna shell

At the prompt, run a query to list all collections using the FQL Collection.all() method:

Collection.all()
{
  data: [
    {
      name: "Customer",
      coll: Collection,
      ts: Time("2099-07-30T22:22:32.945Z"),
      constraints: [
        {
          unique: [
            {
              field: ".email",
              mva: false
            }
          ],
          status: "active"
        }
      ],
      fields: {
        name: {
          signature: "String"
        },
        email: {
          signature: "String"
        },
        address: {
          signature: "{ street: String, city: String, state: String, postalCode: String, country: String }"
        }
      },
      history_days: 0,
      indexes: {
        byEmail: {
          terms: [
            {
              field: ".email",
              mva: false
            }
          ],
          queryable: true,
          status: "complete"
        }
      },
      computed_fields: {
        cart: {
          body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
          signature: "Order?"
        },
        orders: {
          body: "(customer) => Order.byCustomer(customer)",
          signature: "Set<Order>"
        }
      }
    },
    ...
  ]
}

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!