Use the AWS CLI

Install and use Granica AWS CLI plugin for S3 bucket management.

The Granica AWS CLI plugin allows you to manage crunched data using standard AWS CLI S3 commands. With the plugin installed, S3 API requests made with the CLI will be redirected to Granica for handling by Crunch. With the Granica plugin you can easily and consistently access all your data, whether crunched or not, without complicated environment modifications. Any requests for objects not crunched by Crunch are simply passed through directly to S3, and requests for other AWS services will continue to work normally. Having Granica as the single endpoint for all S3 requests greatly simplifies your application code.

Install AWS CLI


If you set up a Granica Admin Server using the setup script from our installation guide, then the Python 3 version of the AWS CLI and the Granica plugin will both be preinstalled, so you can skip ahead to the configuration step below.

The Granica plugin works with the AWS CLI, so first install the AWS CLI on the host where you will deploy the plugin:

pip3 install awscli --user

Enable Python 3

After installing and configuring the plugin ensure that AWS CLI utilizes Python 3 (Python 3 is required). On Linux AMI instances, the default installation in usr/bin/aws uses Python 2. To override this, add an entry to your PATH that will load in the newly installed version.

echo 'export PATH=~/.local/bin:$PATH' >> ~/.bash_profile
source ~/.bash_profile

The AWS CLI and corresponding version of Python can be also verified by executing:

aws --version
# Result should look like
aws-cli/1.18.187 Python/3.7.9 Linux/4.14.203-156.332.amzn2.x86_64 botocore/1.19.27

Install Granica plugin

To install the plugin package, run:

pip3 install awscli-plugin-granica --user

Configure AWS profile to use Granica

To configure the plugin after it has been installed, use aws configure command:

aws configure set plugins.granica awscli-plugin-granica
aws [--profile PROFILE] configure set granica_custom_domain <custom domain>
aws [--profile PROFILE] configure set region <Region>

For example, to activate a Granica service using a load balancer hosted at for the staging AWS profile, run:

aws --profile staging configure set granica_custom_domain
aws --profile staging configure set region us-east-1

Here is a sample ~/.aws/config file with the Granica plugin installed and configured for the staging profile:

[profile staging]
role_arn = arn:aws:iam::123456789012:role/staging
source_profile = default
region = us-east-1
bolt_az = use1-az1
granica_custom_domain =
granica = awscli-plugin-granica

Verify plugin

To verify the plugin functionality simply issue an aws s3 CLI command directed at an S3 bucket. For example:

aws --profile staging s3 ls s3://bucket1


aws --profile staging s3api list-objects-v2 --bucket bucket1

In the example above bucket1 can be any S3 bucket, regardless whether or not it is crunched by Granica Crunch.


The IAM principal (user or role) used to make the requests to Granica must be granted the necessary permissions. See the command documentation for permissions for more info on authorizing access through Granica.


This plugin has been tested for compatibility with AWS CLI version 2, but please take note of the plugins configuration breaking changes. In particular, you will need to add a block like:

cli_legacy_plugin_path = <path-to-plugins>/python3.7/site-packages

in your ~/.aws/config file for the plugin registration to succeed.

To find the correct location for cli_legacy_plugin_path after installing the plugin, run:

pip3 show awscli-plugin-bolt | grep Location:

See also