Graphgrid CLI + Installers
Learn how to install and use the GraphGrid CLI.
Installing the Distributions
Installing on Linux
It is assumed you have the graphgrid-exe-linux.zip 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.
| Argument | Description |
|---|---|
-h, -help | Shows 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, -t | Specify a custom shutdown timeout in seconds (default: 600 seconds) when using the stop or restart command. |
CLI Operations
Archive
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)
| Operation | Description |
|---|---|
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.
| Argument | Description |
|---|---|
--org-name | The organization name used in S3. |
--cluster-name | The cluster named used in S3. |
--file | The path to the compressed db file (upload only). |
--file-name | Optional override that changes the file name used when uploaded. |
--overwrite | Optional 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 test-upload.zip
graphgrid archive upload --org-name gg --cluster-name gg-test --file test-upload.zip --file-name file_name_on_s3.zip
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.
| Argument | Description |
|---|---|
--org-name | The organization name used in S3. |
--cluster-name | The cluster named used in S3. |
--file | Downloads the file (archive) under the path. |
--latest | Downloads the most recently modified archive under the path org-name/cluster-name/. |
--dst | Optional 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 test-upload.zip
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.
| Argument | Description |
|---|---|
--org-name | The 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;-S | Optional Orders the returned archives by size rather than modified date. |
--quiet;-Q | Optional 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