fauna-shell
Advanced tools
This tools gives you access to FaunaDB directly from your CLI.
It also includes a Shell so you can issue queries to FaunaDB without needing to install additional libraries.
You can install it via npm like this:
$ npm install -g fauna-shell
The fauna-shell allows you to do things like creating, deleting and listings databases.
First lets configure our connection to the FaunaDB cloud. (If you don't have an account, you can create a free account here).
Let's run the following command:
$ fauna cloud-login
You will be prompted for your email and password from your FaunaDB Cloud account.
If you would like to use 3rd party identity providers like Github or Netlify, please refer to this guide.
Now that we have an endpoint to connect to we can try to create a database to start playing with FaunaDB. See connecting to different endpoints.
This is how you can create a database called my_app:
$ fauna create-database my_app
creating database my_app
created database my_app
To start a shell with your new database, run:
fauna shell my_app
Or, to create an application key for your database, run:
fauna create-key my_app
And then listing your databases:
$ fauna list-databases
listing databases
my_app
my_second_app
my_other_app
You can also delete a particular database:
$ fauna delete-database my_other_app
deleting database 'my_other_app'
database 'my_other_app' deleted
You can also create, list, and delete keys.
This is how you create a key for the database my_app:
$ fauna create-key my_app
creating key for database 'my_app' with role 'admin'
created key for database 'my_app' with role 'admin'.
secret: ****************************************
To access 'my_app' with this key, create a client using
the driver library for your language of choice using
the above secret.
This is how to list keys (the results may differ from what you see in your instance of FaunaDB)
$ fauna list-keys
listing keys
Key ID Database Role
203269476002562560 my_app admin
203269731203940864 my_app admin
203269732275585536 my_app admin
203269735610057216 test admin
And then delete the key with id: 200219702370238976:
$ fauna delete-key 200219702370238976
deleting key 200219702370238976
key 200219702370238976 deleted
See Commands for a list of commands and help on their usage.
In order to use Fauna Shell, you will need to meet these system requirements:
Node.js version
>= v10.0.0< v12.17.0By default, requests made when using the cloud-login command will hit https://auth-console.fauna-preview.com/login. You can change this behavior by defining the FAUNA_SHELL_LOGIN_URL environment variable in your .env
For example:
FAUNA_SHELL_LOGIN_URL=https://www.mycustomdomain.com/login
The Fauna Shell lets you issue queries directly to your FaunaDB instance without the need for installing additional libraries.
Let's create a database and then we'll jump straight into the Shell to start playing with FaunaDB's data model.
$ fauna create-database my_app
Our next step is to start the shell for a specific database, in this case my_app:
$ fauna shell my_app
Starting shell for database my_app
Connected to http://127.0.0.1:8443
Type Ctrl+D or .exit to exit the shell
my_app>
Once you have the prompt ready, you can start issues queries against your FaunaDB instance. (Note that the results shown here might vary from the ones you see while running the examples).
my_app> CreateCollection({ name: "posts" })
{
ref: Collection("posts"),
ts: 1532624109799742,
history_days: 30,
name: 'posts'
}
Let's create an index for our posts.
my_app> CreateIndex(
{
name: "posts_by_title",
source: Collection("posts"),
terms: [{ field: ["data", "title"] }]
})
{
ref: Index("posts_by_title"),
ts: 1532624135128797,
active: false,
partitions: 1,
name: 'posts_by_title',
source: Collection("posts"),
terms: [ { field: [ 'data', 'title' ] } ]
}
Let's insert a post item:
my_app> Create(
Collection("posts"),
{ data: { title: "What I had for breakfast .." } })
{
ref: Ref(Collection("posts"), "205904004461363712"),
ts: 1532624210670859,
data: { title: 'What I had for breakfast ..' }
}
We can also insert items in bulk by using the Map function.
my_app >
Map(
[
"My cat and other marvels",
"Pondering during a commute",
"Deep meanings in a latte"
],
Lambda(
"post_title",
Create(Collection("posts"), { data: { title: Var("post_title") } })
)
)[
({
ref: Ref(Collection("posts"), "205904031076321792"),
ts: 1532624236071215,
data: { title: "My cat and other marvels" }
},
{
ref: Ref(Collection("posts"), "205904031076320768"),
ts: 1532624236071215,
data: { title: "Pondering during a commute" }
},
{
ref: Ref(Collection("posts"), "205904031076319744"),
ts: 1532624236071215,
data: { title: "Deep meanings in a latte" }
})
];
Now let's try to fetch our post about latte. We need to access it by id like this:
my_app> Get(Ref(Collection("posts"),"205904031076319744"))
{
ref: Ref(Collection("posts"), "205904031076319744"),
ts: 1532624236071215,
data: { title: 'Deep meanings in a latte' }
}
Now let's update our post about our cat, by adding some tags:
my_app> Update(
Ref(Collection("posts"), "205904031076321792"),
{ data: { tags: ["pet", "cute"] } })
{
ref: Ref(Collection("posts"), "205904031076321792"),
ts: 1532624327263554,
data: { title: 'My cat and other marvels', tags: [ 'pet', 'cute' ] }
}
And now let's try to change the content of that post:
my_app> Replace(
Ref(Collection("posts"), "205904031076321792"),
{ data: { title: "My dog and other marvels" } })
{
ref: Ref(Collection("posts"), "205904031076321792"),
ts: 1532624352388889,
data: { title: 'My dog and other marvels' }
}
Now let's try to delete our post about latte:
my_app> Delete(Ref(Collection("posts"), "205904031076319744"))
{
ref: Ref(Collection("posts"), "205904031076319744"),
ts: 1532624236071215,
data: { title: 'Deep meanings in a latte' }
}
If we try to fetch it, we will receive an error:
my_app> Get(Ref(Collection("posts"), "205904031076319744"))
Error: instance not found
Finally you can exit the shell by pressing ctrl+d.
$ fauna COMMAND
running command...
$ fauna (-v|--version|version)
fauna/0.0.1 darwin-x64 node-v8.11.1
$ fauna --help [COMMAND]
USAGE
$ fauna COMMAND
...
We can add endpoints by calling the following command add-endpoint. We will be prompted to enter the authentication key and an alias for the endpoint.
$ fauna add-endpoint "https://example.com"
Endpoint Key: ****************************************
Endpoint Alias [example.com]: example_alias
The Endpoint Alias should be a name that helps you remember the purpose of this endpoint.
If we have defined many endpoints, we could set one of them as the default one with the default-endpoint command:
$ fauna default-endpoint cloud
The default endpoint will be used by the shell to connect to FaunaDB.
Endpoints can be listed with the list-endpoints command like this:
$ fauna list-endpoints
localhost
cloud *
cluster-us-east
There we see that the cloud endpoint has a * next to its name, meaning that it's the current default one.
Finally, endpoints will be saved to a ~/.fauna-shell file like this:
default=cloud
[localhost]
domain=127.0.0.1
port=8443
scheme=http
secret=secret
graphqlHost=127.0.0.1
graphqlPort=8084
[cloud]
domain=db.fauna.com
scheme=https
secret=FAUNA_SECRET_KEY
graphqlHost=graphql.fauna.com
graphqlPort=443
[cluster-us-east]
domain=cluster-us-east.example.com
port=443
scheme=https
secret=OTHER_FAUNA_SECRET
graphqlHost=cluster-us-east.example.com
graphqlPort=443
If you are running Fauna locally using our Docker images, you may need to configure the Shell to work with local endpoints so you can interact with the databases running in the Docker containers.
Once you've installed the Shell and logged in, you can configure this by doing the following:
Run fauna list-endpoints to see all your endpoints. If you haven't added any yet, you should just see the cloud endpoint that was added when you went through the login flow.
By default, the Fauna Docker image serves data via port 8443 (check your Docker logs to confirm the port number). To add this, run the following:
fauna add-endpoint http://localhost:8443 # Doesn't work with HTTPS
When prompted, provide the endpoint key and then give it a name (ex. localhost)
Now, you can interact with your local database through the Fauna Shell by running the command below:
fauna shell --endpoint localhost
Most commands support the following options. You can specify them if you want to connect to your local FaunaDB instance.
OPTIONS
--domain=domain [default: db.fauna.com] FaunaDB server domain
--port=port [default: 443] Connection port
--scheme=https|http [default: https] Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout [default: 80] Connection timeout in milliseconds
--endpoint=alias Overrides the default endpoint set in ~/.fauna-shell
--graphqlHost=domain [default: graphql.fauna.com] The Fauna GraphQL API host
--graphqlPort=port [default: 443] The Fauna GraphQL API port to connect to
They can be used like this:
$ fauna create-database testdb --domain=127.0.0.1 port=8443 --scheme=http --secret=YOUR_FAUNA_SECRET_KEY --timeout=42 --graphqlHost=127.0.0.1 --graphqlPort=443
Options provided via the CLI will override the values set in the .fauna-shell config file.
For example you can start a shell to a different endpoint from the one set in .fauna-shell:
$ fauna shell my_app --endpoint=endpoint_alias
Any options that are not specified either via the .fauna-shell config file or the CLI will be set to the defaults offered by the faunadb-js client.
You can also tell the shell to execute a list of queries that you have stored in a file. For example, you can have a filed called queries.fql with the following content:
CreateCollection({ name: "posts" });
CreateIndex({
name: "posts_by_title",
source: Collection("posts"),
terms: [{ field: ["data", "title"] }]
});
Create(Collection("posts"), { data: { title: "What I had for breakfast .." } });
Map(
[
"My cat and other marvels",
"Pondering during a commute",
"Deep meanings in a latte"
],
Lambda(
"post_title",
Create(Collection("posts"), { data: { title: Var("post_title") } })
)
);
You can tell Fauna Shell to execute all those queries for you by running the following command:
$ fauna eval my_app --file=./queries.fql
Where my_app is the name of your database, and ./queries.fql is the path to the file where you saved the queries. If my_app is left out it will execute the queries file on the default fauna shell endpoint. This was previously called run-queries.
Queries have to be written in the syntax supported by FaunaDB's Javascript driver.
fauna add-endpoint ENDPOINTfauna autocomplete [SHELL]fauna cloud-loginfauna create-database DBNAMEfauna create-key DBNAME [ROLE]fauna default-endpoint ENDPOINT_ALIASfauna delete-database DBNAMEfauna delete-endpoint ENDPOINT_ALIASfauna delete-key KEYNAMEfauna eval [DBNAME] [QUERY]fauna help [COMMAND]fauna importfauna list-databasesfauna list-endpointsfauna list-keysfauna run-queries [DBNAME] [QUERY]fauna shell [DBNAME]fauna upload-graphql-schema GRAPHQLFILEPATHfauna add-endpoint ENDPOINTAdds a connection endpoint for FaunaDB
USAGE
$ fauna add-endpoint ENDPOINT
ARGUMENTS
ENDPOINT FaunaDB server endpoint
OPTIONS
--alias=alias FaunaDB server endpoint alias
--key=key FaunaDB server endpoint key
DESCRIPTION
Adds a connection endpoint for FaunaDB
EXAMPLES
$ fauna add-endpoint https://db.fauna.com:443
$ fauna add-endpoint http://localhost:8443/ --alias localhost --key secret
See code: src/commands/add-endpoint.js
fauna autocomplete [SHELL]display autocomplete installation instructions
USAGE
$ fauna autocomplete [SHELL]
ARGUMENTS
SHELL shell type
OPTIONS
-r, --refresh-cache Refresh cache (ignores displaying instructions)
EXAMPLES
$ fauna autocomplete
$ fauna autocomplete bash
$ fauna autocomplete zsh
$ fauna autocomplete --refresh-cache
See code: @oclif/plugin-autocomplete
fauna cloud-loginAdds the FaunaDB Cloud endpoint
USAGE
$ fauna cloud-login
EXAMPLE
$ fauna cloud-login
See code: src/commands/cloud-login.js
fauna create-database DBNAMECreates a database
USAGE
$ fauna create-database DBNAME
ARGUMENTS
DBNAME database name
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Creates a database
EXAMPLE
$ fauna create-database dbname
See code: src/commands/create-database.js
fauna create-key DBNAME [ROLE]Creates a key for the specified database
USAGE
$ fauna create-key DBNAME [ROLE]
ARGUMENTS
DBNAME database name
ROLE (admin|server|server-readonly|client) key user role
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Creates a key for the specified database
EXAMPLE
$ fauna create-key dbname admin
See code: src/commands/create-key.js
fauna default-endpoint ENDPOINT_ALIASSets an endpoint as the default one
USAGE
$ fauna default-endpoint ENDPOINT_ALIAS
ARGUMENTS
ENDPOINT_ALIAS FaunaDB server endpoint alias
DESCRIPTION
Sets an endpoint as the default one
EXAMPLE
$ fauna default-endpoint endpoint
See code: src/commands/default-endpoint.js
fauna delete-database DBNAMEDeletes a database
USAGE
$ fauna delete-database DBNAME
ARGUMENTS
DBNAME database name
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Deletes a database
EXAMPLE
$ fauna delete-database dbname
See code: src/commands/delete-database.js
fauna delete-endpoint ENDPOINT_ALIASDeletes a connection endpoint for FaunaDB
USAGE
$ fauna delete-endpoint ENDPOINT_ALIAS
ARGUMENTS
ENDPOINT_ALIAS FaunaDB server endpoint alias
DESCRIPTION
Deletes a connection endpoint for FaunaDB
EXAMPLE
$ fauna delete-endpoint endpoint_alias
See code: src/commands/delete-endpoint.js
fauna delete-key KEYNAMEDeletes a key
USAGE
$ fauna delete-key KEYNAME
ARGUMENTS
KEYNAME key name
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Deletes a key
EXAMPLE
$ fauna delete-key 123456789012345678
See code: src/commands/delete-key.js
fauna eval [DBNAME] [QUERY]USAGE
$ fauna eval [DBNAME] [QUERY]
ARGUMENTS
DBNAME Database name
QUERY FQL query to execute
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--file=file File where to read queries from
--format=json|shell [default: json] Output format
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--output=output File to write output to
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--stdin Read file input from stdin. Writes to stdout by default
--timeout=timeout Connection timeout in milliseconds
EXAMPLES
$ fauna eval "Paginate(Collections())"
$ fauna eval nestedDbName "Paginate(Collections())"
$ fauna eval --file=/path/to/queries.fql
$ echo "Add(1,1)" | fauna eval --stdin
$ fauna eval "Add(2,3)" --output=/tmp/result"
$ fauna eval "Add(2,3)" --format=json --output=/tmp/result"
See code: src/commands/eval.js
fauna help [COMMAND]display help for fauna
USAGE
$ fauna help [COMMAND]
ARGUMENTS
COMMAND command to show help for
OPTIONS
--all see all commands in CLI
See code: @oclif/plugin-help
fauna importImport data to Fauna
USAGE
$ fauna import
OPTIONS
--allow-short-rows
Allows rows which are shorter than the number of headers
--append
Allows appending documents to a non-empty collection
--collection=collection
Collection name. When not specified, the collection name is the filename.
--db=db
Child database name; imported documents are stored in this database
--domain=domain
FaunaDB server domain
--dry-run
Dry run the import - committing no documents to Fauna but converting all items to Fauna's format and applying all
requested --type conversions. Enables you to detect issues with your file(s) before writing to your collection(s).
--endpoint=endpoint
FaunaDB server endpoint
--path=path
(required) Path to .csv/.json file, or path to folder containing .csv/.json files. if the path is to a folder,
sub-folders will be skipped.
--port=port
Connection port
--scheme=https|http
Connection scheme
--secret=secret
FaunaDB secret key
--timeout=timeout
Connection timeout in milliseconds
--treat-empty-csv-cells-as=empty|null
[default: null] Treat empty csv cells as empty strings or null, default is null.
--type=type
Column type casting - converts the column value to a Fauna type. Available only in CSVs; will be ignored in
json/jsonl inputs. Null values will be treated as null and no conversion will be performed.
Format: <column>::<type>
<column>: the name of the column to cast values
<type>: one of
'number' - convert string to number
'bool' - convert 'true', 't', 'yes', or '1' to true and all other values to false (saving null which will be treated
as null)
'dateString' - convert a ISO-8601 or RFC-2822 date string to a Fauna Time; will make a best effort on other formats,
'dateEpochMillis' - converts milliseconds since the epoch to a Fauna Time
'dateEpochSeconds' - converts seconds since the epoch to a Fauna Time
EXAMPLES
You can combine the options in any manner of you're choosing (although type translations cannot be applied to JSON or
JSONL files). Below are examples.
... File import examples
Import a file into a new collection - given the same name as the file:
$ fauna import --path ./collection_name.csv
Append a file into a pre-existing collection - having the same name as the file:
$ fauna import --append --path ./collection.csv
Import a file into a new collection named "SampleCollection" in the child database "sampleDB":
$ fauna import --db=sampleDB --collection=SampleCollection --path ./datafile.csv
Import a file into a new collection named "SampleCollection" in the child database "sampleDB":
$ fauna import --type=iso8601_date::dateString --type=hdr2::number --type=hdrX::bool --path ./collection.csv
... Directory import examples
Import a directory - creating a new collection "SampleCollection" with data from every file in the directory:
$ fauna import --path ./my_directory --collection=SampleCollection
Import a directory - creating appending to the pre-existing collection "SampleCollection" with data from every file in
the directory:
$ fauna import --path ./my_directory --collection=SampleCollection --append
Import a directory - creating creating a new collection named after the file name of each file:
$ fauna import --path ./my_directory
Import a directory - creating appending to pre-existing collections named after the file name of each file:
$ fauna import --path ./my_directory --append
See code: src/commands/import.js
fauna list-databasesLists child databases in the current database
USAGE
$ fauna list-databases
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Lists child databases in the current database
EXAMPLE
$ fauna list-databases
See code: src/commands/list-databases.js
fauna list-endpointsLists FaunaDB connection endpoints
USAGE
$ fauna list-endpoints
DESCRIPTION
Lists FaunaDB connection endpoints
EXAMPLE
$ fauna list-endpoints
See code: src/commands/list-endpoints.js
fauna list-keysList keys in the current database or in its child databases
USAGE
$ fauna list-keys
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
List keys in the current database or in its child databases
EXAMPLE
$ fauna list-keys
See code: src/commands/list-keys.js
fauna run-queries [DBNAME] [QUERY]Deprecated: fauna run-queries is deprecated. Use eval instead
USAGE
$ fauna run-queries [DBNAME] [QUERY]
ARGUMENTS
DBNAME Database name
QUERY FQL query to execute
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--file=file (required) File where to read queries from
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Deprecated: fauna run-queries is deprecated. Use eval instead
Runs the queries found on the file passed to the command.
EXAMPLE
$ fauna run-queries dbname --file=/path/to/queries.fql
See code: src/commands/run-queries.js
fauna shell [DBNAME]Starts a FaunaDB shell
USAGE
$ fauna shell [DBNAME]
ARGUMENTS
DBNAME database name
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
DESCRIPTION
Starts a FaunaDB shell
EXAMPLE
$ fauna shell dbname
See code: src/commands/shell.js
fauna upload-graphql-schema GRAPHQLFILEPATHUpload GraphQL schema
USAGE
$ fauna upload-graphql-schema GRAPHQLFILEPATH
ARGUMENTS
GRAPHQLFILEPATH Path to GraphQL schema
OPTIONS
--domain=domain FaunaDB server domain
--endpoint=endpoint FaunaDB server endpoint
--graphqlHost=graphqlHost The Fauna GraphQL API host
--graphqlPort=graphqlPort GraphQL port
--mode=merge|override|replace [default: merge] Upload mode
--port=port Connection port
--scheme=https|http Connection scheme
--secret=secret FaunaDB secret key
--timeout=timeout Connection timeout in milliseconds
EXAMPLES
$ fauna upload-graphql-schema ./schema.gql
$ fauna upload-graphql-schema ./schema.gql --mode override
See code: src/commands/upload-graphql-schema.js
All above commands starts with fauna, but you are able to run them this way after installation of the fauna-shell package.
During development, you might want to test your changes without installing the package every single time.
To do so, you can run commands like this:
# don't forget to install dependencies for your fauna-shell project
npm install
# run a command you need
./bin/run cloud-login
./bin/run import
FAQs
faunadb shell
The npm package fauna-shell receives a total of 855 weekly downloads. As such, fauna-shell popularity was classified as not popular.
We found that fauna-shell demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.