Getting started

This Shell getting started guide shows you how to:

  1. Define a configuration file endpoint.

  2. Display the configuration file.

  3. Start Fauna Shell.

  4. Run queries directly in the CLI or using .fql files

After starting Fauna Shell, experiment with the Shell commands to gain familiarity with the CLI.

The example queries in this tutorial use the Demo database and demo data from the Fauna quick start.

Log in and define a configuration endpoint

The Fauna quick start describes how to set up an account, and how to create a database and get the database secret.

If you don’t have endpoints defined in the $HOME/.fauna-shell configuration file, use the cloud-login command to create a default configuration endpoint in the fauna-shell configuration file.

  1. Create an endpoint, stepping through each of the prompts.

    • These examples use cloud-example as an endpoint name, but you can choose another name.

    • The email and password are your Fauna account credentials.

    • Choose the endpoint created for your region group

    fauna cloud-login
? Endpoint name cloud-example
? Email address (from https://dashboard.fauna.com/) your.name@yourorg.com
? Password *********
? Endpoints created. Which endpoint would you like to set as default? (Use arrow keys)
  Keep 'cloud-us' endpoint as default // use arrow keys to choose endpoint
  cloud-example-global
❯  cloud-example-us
  cloud-example-eu

  ...

Configuration updated.

    This updates the $HOME/.fauna-shell file to include the following endpoints in addition to previously defined endpoints and sets cloud-example-us: as the default endpoint.

    [.fauna-shell]
default=cloud-example-us

... elided ...

[endpoint.cloud-example-global]
secret=fnAFQyPwW4ACRSqZe31zFBBPe6fh81CPA3G_esVj

[endpoint.cloud-example-us]
secret=fnAFQyPwZe31zWpqZ3-ij5Ghso4erhTiU2RXSQaL

[endpoint.cloud-example-eu]
secret=fnAFQyPwZlAAzh_cxhZe31zKUNvgcNJ6Wj0rEwjY

  2. View your defined endpoints using the endpoint list command:

    fauna endpoint list
Available endpoints:
  local
  cloud-eu
  cloud
  cloud-us
  db.fauna.com
  cloud-example-global
* cloud-example-us
  cloud-example-eu

    The cloud-example-us endpoint is the default endpoint.

Display the configuration file

To view the updated configuration file on Linux, macOS, and Unix-like operating systems, enter:

cat $HOME/.fauna-shell

On a Windows operating system, enter:

type %userprofile%\.fauna-shell

Shell session example

The fauna-shell allows you to query your Fauna database using FQL without installing other libraries.

  1. Use the list-databases command to list databases available for your endpoint and credentials:

    fauna list-databases
listing databases
Demo

    To create a database, use the create-database command:

    fauna create-database

  created database my_db

  To start a shell with your new database, run:

  fauna shell my_db

  Or, to create an application key for your database, run:

  fauna create-key my_db

  2. Start the shell for the Demo database:

    fauna shell Demo
Connected to endpoint: cloud-us
Connected to endpoint: cloud-us database: Demo
Starting shell for database Demo
Type Ctrl+D or .exit to exit the shell
Demo>

  3. After the prompt displays, you can start issuing queries against your database:

    Demo> Product.byName("avocados")
{
  data: [
    {
      id: "395885299960381508",
      coll: Product,
      ts: Time("2024-04-22T16:48:12.930Z"),
      name: "avocados",
      description: "Conventional Hass, 4ct bag",
      price: 3.99,
      quantity: 995,
      store: Store("395885299859718212"),
      backorderLimit: 15,
      backordered: false
    }
  ]
}

To exit the shell, press Ctrl+D.

Query using a file

You can use the shell to run a list of queries stored in a file as shown in this example.

  1. Create a queries.fql file that contains one or more FQL queries:

    Product.create({
  name: "lemons",
  description: "Organic, 2 ct",
  price: 0.95
})

[
  "DC Fruit Stand",
  "The Citrus Store",
].map(name => {
  Store.create({
    name: name
  })
})

  2. Run the queries with the following command:

    fauna eval Demo --file=./queries.fql
[
  {
    id: "395887362308046913",
    coll: Store,
    ts: Time("2024-04-22T17:20:59.660Z"),
    name: "DC Fruit Stand"
  },
  {
    id: "395887362308047937",
    coll: Store,
    ts: Time("2024-04-22T17:20:59.660Z"),
    name: "The Citrus Store"
  }
]

    The database name is Demo and the --file option is the path and file name of the saved the queries. If the database name is omitted, the queries are run on the default fauna shell endpoint.

    The response only includes the results of the last query.

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!