Set up a project using FSL and the Fauna CLI

This high-level guide shows how to set up a project for an application using the Fauna CLI and FSL files.

While not required, we recommend using this workflow for production apps. The setup lets you manage your database schema as declarative files alongside your app’s code.

Before you start

The tutorial assumes you have:

Completed the tour.
Not created a database or schema for your app.

Set up a project

If you haven’t already, install the Fauna CLI:
```
npm install -g fauna-shell
```
Use fauna cloud-login to log in to Fauna:
```
fauna cloud-login
```
When prompted, enter:
- Endpoint name: cloud (Press Enter)
  
  An endpoint defines the settings the CLI uses to run API requests against a Fauna account or database. See Endpoints.
- Email address: The email address for your Fauna account.
- Password: The password for your Fauna account.
- Which endpoint would you like to set as default? The cloud-* endpoint for your preferred Region Group. For example, to use the US Region Group, use cloud-us.
The command requires an email and password login. If you log in to Fauna using GitHub or Netlify, you can enable email and password login using the Forgot Password workflow.

If successful, the command adds a related endpoint and secret to the .fauna-shell configuration file.
If you haven’t already, create a directory for the project and navigate to it. In most cases, the directory also contains your app’s source code. For example:
```
mkdir <PROJECT_DIRECTORY>
cd <PROJECT_DIRECTORY>
```
Create one or more databases for the app:
```
fauna create-database <DATABASE_NAME>
```
You can view the databases in the Fauna Dashboard.
Use fauna project init to create a .fauna-project file for the project:
```
fauna project init
```
When prompted, enter:
- A schema directory used to store .fsl files. If the directory doesn’t exist, the command creates it.
- A default environment name. See Environments.
- A default endpoint to use for Fauna CLI commands.
- A default database for Fauna CLI commands.
In the project’s schema directory, create and save one or more .fsl files.

For example, you can create a collections.fsl file with the following FSL collection schema:
```
collection Customer {
  name: String
  email: String

  index byEmail {
    terms [.email]
  }

  unique [.email]
}
```
An .fsl file can contain schema for multiple resources. You can use multiple .fsl files to organize your schema. There is no performance benefit to splitting .fsl files or storing larger, individual files.

Run a staged schema change to commit the schema to Fauna:

Use fauna schema push to stage the schema changes. fauna schema push stages schema changes by default:
```
fauna schema push
```
A database can have one staged schema change at a time. You can update staged schema using fauna schema push.

When a database has staged schema, any access or updates done using FQL’s schema commands on related system collections interact with the staged schema, not the database’s active schema.

For example, when schema changes are staged, Collection.all() returns Collection documents for the staged collection schema, not the database’s Collection documents.

If a database has staged schema, you can’t edit the database’s active schema using FQL, the Dashboard, or an unstaged schema change. You must first abandon the staged schema change.

Use fauna schema status to check the status of the staged schema:

fauna schema status

Possible statuses:

Staged status Description

Staged status	Description
`pending`	Changes are being processed. New indexes are still being built.
`ready`	All indexes have been built. Changes are ready to commit.
`failed`	There was an error during the staging process.

pending

Changes are being processed. New indexes are still being built.

ready

All indexes have been built. Changes are ready to commit.

failed

There was an error during the staging process.

When the status is ready, use fauna schema commit to apply the staged schema to the database:
```
fauna schema commit
```
You can only commit staged schema with a status of ready.

If you no longer wish to apply the staged schema or if the status is failed, use fauna schema abandon to unstage the schema:
```
fauna schema abandon
```

Before pushing changes, the command displays a diff. If wanted, you can then accept or reject the changes.

Use fauna create-key to create a key for one or more of your databases:
```
fauna create-key <DATABASE_NAME> <ROLE>
```
To create a key for a top-level database, add --environment='':
```
fauna create-key --environment='' <DATABASE_NAME> <ROLE>
```
Your app can use the key’s secret to authenticate Fauna requests using a client driver or the Fauna Core HTTP API. You can also use the key to bootstrap a Fauna-based end-user authentication system.

Next steps

Congratulations! You’ve initialized a project and you’re ready to start building your app with Fauna.

To learn how to run queries from your app, check out the client driver docs or the Query HTTP API endpoint reference.

If you’d like to see a production-ready example, check out the sample apps on GitHub:

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!