Nightmarish Pawnshop Mystic

    fauna-shell

    0.12.6 • Public • Published

    fauna-shell

    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

    Usage

    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.

    Technical Requirements

    In order to use Fauna Shell, you will need to meet these system requirements:

    Node.js version

    • >= v10.0.0
    • < v12.17.0

    Configuration

    By 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

    Shell

    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.

    Command Details

    $ fauna COMMAND
    running command...
    $ fauna (-v|--version|version)
    fauna/0.0.1 darwin-x64 node-v8.11.1
    $ fauna --help [COMMAND]
    USAGE
      $ fauna COMMAND
    ...

    Connecting to different endpoints

    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

    Connecting to local endpoints

    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:

    1. 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.

    2. 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
    1. When prompted, provide the endpoint key and then give it a name (ex. localhost)

    2. Now, you can interact with your local database through the Fauna Shell by running the command below:

    fauna shell --endpoint localhost

    Overriding Connection Parameters

    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.

    Executing queries from a file

    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 run-queries 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.

    Queries have to be written in the syntax supported by FaunaDB's Javascript driver.

    List of Commands

    fauna add-endpoint ENDPOINT

    Adds a connection endpoint for FaunaDB

    Adds 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

    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-login

    Adds the FaunaDB Cloud endpoint

    Adds the FaunaDB Cloud endpoint
    
    USAGE
      $ fauna cloud-login
    
    EXAMPLE
      $ fauna cloud-login
    

    See code: src/commands/cloud-login.js

    fauna create-database DBNAME

    Creates a database

    Creates 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

    Creates a key for the specified database
    
    
    USAGE
      $ fauna create-key DBNAME [ROLE]
    
    ARGUMENTS
      DBNAME  database name
      ROLE    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_ALIAS

    Sets an endpoint as the default one

    Sets 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 DBNAME

    Deletes a database

    Deletes 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_ALIAS

    Deletes a connection endpoint for FaunaDB

    Deletes 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 KEYNAME

    Deletes a key

    Deletes 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]

    undefined
    
    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

    display help for <%= config.bin %>
    
    USAGE
      $ fauna help [COMMAND]
    
    ARGUMENTS
      COMMAND  command to show help for
    
    OPTIONS
      --all  see all commands in CLI
    

    See code: @oclif/plugin-help

    fauna list-databases

    Lists child databases in the current database

    Lists 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-endpoints

    Lists FaunaDB connection endpoints

    Lists 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-keys

    List keys in the current database or in its child databases

    List 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

    Deprecated: fauna run-queries is deprecated. Use eval instead
    Runs the queries found on the file passed to the command.
    
    
    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

    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 GRAPHQLFILEPATH

    Upload GraphQL schema

    Upload 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

    Install

    npm i fauna-shell

    DownloadsWeekly Downloads

    129

    Version

    0.12.6

    License

    MPL-2.0

    Unpacked Size

    95.3 kB

    Total Files

    24

    Last publish

    Collaborators

    • fauna-bot