Skip to main content
Version: 2.0

Graphgrid CLI + Installers

Learn how to install and use the GraphGrid CLI.

Installing the Distributions

Installing on Linux

It is assumed you have the distribution available. Installing on Linux is as simple as running the install sh script in the unzipped distribution.

To install the GraphGrid CLI, run the installation script:

sudo ./install

To check that the CLI was installed properly you can run:

/usr/local/bin/graphgrid --help

This will install the GraphGrid CLI at /usr/local/bin/graphgrid. Assuming /usr/local/bin is in your PATH, you can now run:

graphgrid --help

Installing without Sudo

If you don't have sudo permissions or want to install the GraphGrid CLI only for the current user, run the installation script with the -b and -i options:

 ./install -i ~/.local/graphgrid-cli -b ~/.local/bin

This will install the GraphGrid CLI in ~/.local/graphgrid-cli and create symlinks for GraphGrid in ~/.local/bin. For more information about these options, run the install script with -h:

./install -h

Installing on macOS

It is assumed you have the GRAPHGRID-CLI-Installer.pkg distribution available. Simply click and run the pkg installer and follow the wizard to install.

AWS Dependency

For commands relating to AWS (i.e. archive) it is required to have an AWS profile setup. The expected default profile name is graphgrid but this can be overridden with the --profile option in the CLI.

To set up an AWS profile install the AWS CLI and create/configure a new profile with

aws configure --profile graphgrid

General Usage

The GraphGrid team is continuing progress on the GraphGrid CLI. The current GraphGrid CLI utilities are still a work in progress as is logged in the positional arguments upon starting up the GraphGrid CLI.

The command operations: install, start, stop, restart, maps, and passwords are to be implemented.

GraphGrid CLI currently has working archival operations setup under the archive utility.

Optional Arguments

The GraphGrid CLI has the following optional arguments which can be added to the GraphGrid utility commands.

-h, -helpShows help message related to chosen utility and exits.
--profile {{PROFILE}}AWS profile to execute with (default: graphgrid).
--region {{REGION}}AWS region to execute with (default: us-west-2).
--log-level {{ERROR,WARN,INFO,DEBUG}}The log level to use (default: INFO).
--timeout, -tSpecify a custom shutdown timeout in seconds (default: 600 seconds) when using the stop or restart command.

CLI Operations


The archive command provides a set of operations that control the archival process. Running graphgrid archive --help will return a help message listing the available archive operations.

Archive Operations (Archive Sub-commands)
upload"upload" operation. Archives compressed db file onto S3.
download"download" operation. Downloads the file(archive).
list"list" operation. Lists the clusters in the org/Lists the archives in the org/cluster.
Archive Upload Operation

The archive upload operation provides a way to upload an archived file to a specific org/cluster combination. There are 3 arguments required to upload a file using the archive upload operation: org-name, cluster-name, and file. There are two optional arguments,file-name and overwrite.

--org-nameThe organization name used in S3.
--cluster-nameThe cluster named used in S3.
--fileThe path to the compressed db file (upload only).
--file-nameOptional override that changes the file name used when uploaded.
--overwriteOptional Default behavior for upload is to reject overwrites of existing archives. To overwrite an existing archive the flag --overwrite must be used. Prevents accidental overwrites.
Archive Upload Example(s)
 graphgrid archive upload --org-name gg --cluster-name gg-test  --file
 graphgrid archive upload --org-name gg --cluster-name gg-test  --file --file-name
Archive Download Operation

The archive download operation provides a way retrieve archives on S3 and store them locally. There are 3 arguments required to download a file using the archive download operation, org-name, cluster-name,and either file or latest but not both. The file and latest arguments are mutually exclusive, both cannot be used at the same time, but exactly one of them is required for the download command. There is one optional argument of dst which changes the download directory. Archives are downloaded to the working directory by default, this can be overridden with dst.

--org-nameThe organization name used in S3.
--cluster-nameThe cluster named used in S3.
--fileDownloads the file (archive) under the path.
--latestDownloads the most recently modified archive under the path org-name/cluster-name/.
--dstOptional Explicitly set the local destination to download the archive to.
Archive Download Example(s)
graphgrid archive download --org-name gg --cluster-name gg-test --file
graphgrid archive download --org-name gg --cluster-name gg-test --latest
graphgrid archive download --org-name gg --cluster-name gg-test --dst ~/local-archives/

Archive List Operation

The archive list operation provides a way to list out information about your archives/clusters. There are 3 optional arguments, cluster-name, order-by-size (size or S) and quiet(Q). The behavior of archive list depends on whether cluster-name is provided.

Default archive list behavior (only org-name provided) returns a list of the clusters under the org.

When cluster-name is provided to archive list the behavior slightly changes and will return a list of archives under the path org-name/cluster-name/, along with file metadata like lastModified and sizeß.

The optional arguments --order-by-size and --quiet only take effect when cluster-name is provided. If one tries to use those flags when listing out the clusters (ie. only org specified) the flags will have no effect.

--org-nameThe organization name used in S3.
--cluster-name>Optional The cluster named used in S3. Behavior of the list operation depends on if cluster-name is provided.
--order-by-size;--size;-SOptional Orders the returned archives by size rather than modified date.
--quiet;-QOptional Only returns the archive file names without extra information, useful if using results programmatically.
Archive List Command Example(s)

Lists the clusters in the org gg.

graphgrid archive list --org-name gg

Lists the archives in the org/cluster/ path (specifically gg/gg-test/). Default return order is by last modified date. Individually each archive record in the list includes s3 path, size of the archive (units are either in GB, MB, or KB depending on archive size), and the time of last modification to the archive.

graphgrid archive list --org-name gg --cluster-name gg-test