cloud-login

The cloud-login command creates a Fauna endpoint in the configuration file based on your Fauna credentials.

fauna cloud-login

Description

The cloud-login command prompts you for your Fauna credentials, and if you authenticate successfully, creates a cloud endpoint in the configuration file that you can use to query your top-level Fauna database.

There are several prompts that help you to create endpoints that work with Region Groups, GitHub and Netlify authentication, or secrets for existing databases:

  • Endpoint alias prefix: Since the introduction of Region Groups, you might need to access databases in multiple Region Groups. This prompt asks you for a prefix that can be applied to multiple Region Group endpoints.

    For example, entering cloud as the prefix (which is the default) could result in the endpoints:

    • cloud: This represents the Classic Region Group that replicates your database data globally.

    • cloud-us: This represents the US Region Group that replicates data within the continental United States.

    • cloud-eu: This represents the EU Region Group that replicates data within Europe.

  • How do you prefer to authenticate?: This prompt asks you for your authentication preference:

    • Email and Password: You can use your Fauna Dashboard credentials to authenticate.

      When you choose this option, you are then asked for your email address and password.

    • Secret: You can use a secret for an existing database, similar to how your client applications would authenticate.

      When you choose this option, you are then asked for a secret, which is the authentication bearer token acquired by creating a key or token.

      You are then asked which Region Group to connect to, Classic, EU, or US. The secret is associated with a specific database in a specific region: if you choose incorrectly, a "could not connect" error appears and you are prompted for your secret again.

  • Multi-factor authentication: When multi-factor authentication (MFA) is enabled for your account in the Dashboard, the cloud-login function prompts you for the current (time-based) multi-factor authentication code — you can see the current code in your authenticator app. If you do not enter the correct code, cloud-login exits with an error. Note that this does not occur when you authenticate using a secret.

  • Default endpoint: When your fauna-shell configuration file contains an existing endpoint, you are asked whether the new endpoint that cloud-login creates should be made the default.

Arguments

None.

Options

Option Description

--domain=<domain>

Optional - The Fauna server domain, that is, the hostname where Fauna is running. Defaults to db.fauna.com.
Since the introduction of Region Groups, three cloud domains are available. Use the correct domain for your database’s Region Group.
Classic (US and EU): db.fauna.com
United States (US): db.us.fauna.com
Europe (EU): db.eu.fauna.com

--endpoint=<endpoint>

Optional - The name of the endpoint to use for the command.

--port=<port>

Optional - The connection port. Defaults to 8443.

--scheme=<scheme>

Optional - The connection scheme. Must be one of https or http. Defaults to https.

--secret=<secret>

Optional - The secret to use. A secret authenticates your connection to Fauna, and connects you to a specific database.

--timeout=<timeout>

Optional - The connection timeout, an integer number of milliseconds. When the specified period has elapsed, fauna-shell stops waiting for a response and displays an error.

The default is zero, which means that fauna-shell waits until a response is received.

Examples

The following example demonstrates the use of cloud-login, and the prompts for email/secret and password:

fauna cloud-login
? The endpoint alias prefix (to combine with a region): cloud
? How do you prefer to authenticate? Email and Password
? Email address: docs@fauna.com
? Password: [hidden]
? Enter your multi-factor authentication code 377277
? Endpoints created. Would you like to set one of them as default? Keep 'cloud'
endpoint as default
Endpoint 'cloud' set as default endpoint.

After a successful login, your configuration file now contains a cloud endpoint that includes the secret to access your top-level database.

To see the configuration file, perform one of these steps:

  1. On Linux, macOS, and other Unix-like operating systems, run the following command in a terminal:

    cat $HOME/.fauna-shell
  2. On Windows, run the following command in a command terminal:

    type %userprofile%\.fauna-shell

The configuration file should resemble:

default=cloud

[cloud]
domain=db.fauna.com
scheme=https
secret=fnADS@PxN@2CE@n7z@kDa4_p6Z@fIBaZm@Qt@bYT
graphqlHost=graphql.fauna.com
Every secret provided by Fauna is unique, so the secret you see when you run cloud-login is guaranteed to differ from the one above. The secret above has been modified; it cannot be used to access a real database.

Was this article helpful?

We're sorry to hear that.
Tell us how we can improve!
Visit Fauna's Discourse forums or email docs@fauna.com

Thank you for your feedback!