There are two possible ways of installing CleverMaps Shell - locally and using Docker.
To install it locally, you have to:
Install Java Development Kit - JDK
Download the Shell .jar file
Run it in cmd.exe or Terminal
To install using Docker:
Download and install the Docker platform
Pull the latest Shell image
Run it in a Docker container
CleverMaps Shell runs in Terminal on Unix systems (Linux, Mac OS) and in cmd.exe on Windows systems. If you're unfamiliar with these tools, we recommend completing a basic usage tutorial on the web.
We've encountered character encoding problems on Windows 7. It is recommended to use Windows 8 or higher.
To run Shell locally, your machine must have the Java Development Kit, version 17 or higher, installed. To check if JDK is installed, open Terminal or cmd.exe and run this command.
If you receive a version number back - you have installed JDK already and you can skip to the next step.
Otherwise, we recommend to download Java Development Kit - JDK 17 from Oracle:
Choose the installation file according to your platform, and follow the installation instructions. You can also opt for the open-source version - OpenJDK.
After successfully installing JDK, download the Shell executable file from this page. Navigate to the folder where you've downloaded the Shell, and run it using a script distributed with the executable .jar file. The script must be located in the same folder as the .jar file.
<path> is the path to the folder where you've downloaded Shell.
Alternatively, run it directly using the
The actual name of the jar (
can-shell-1.6.0-RELEASE-exec.jar) may differ - it depends on the version you've downloaded.
After you have successfully started Shell, we recommend you set up your config and credentials, so you don't have to enter them each time you log in.
You can log in using either credentials or an access token (recommended).
Log in using an access token
First, log in to the application and on the Project page, hover over your profile name and select Generate access token. You will be prompted to log in again, and then you'll receive your access key.
Then, run Shell and use the
setup command to set up your access token.
Your credentials and config files will be stored in your home folder in the
Are you connecting through a proxy server? Set your proxy config using:
setup --proxyHost proxy.example.com
--password proxyPort 3128
To run Shell in Docker, your machine must install and run the Docker container platform. You can get Docker here.
This image runs the lightweight Alpine Linux and already contains the Java Development Kit. It's always distributed with the latest version of Shell.
--env CM_ACCESS_TOKEN=8HZP...WE the security token stays in terminal history. If you are working under unsecured environment consider saving
CM_ACCESS_TOKEN into a file and load it with
--env-file file-name.env .
--rmtells Docker not to persist the container for later use
--namespecifies the name of the container
--pullthe newest version of the image if available
--volumebind mounts a volume, where
/tmp/dumpsis the local directory the image will use, and
/workis the path inside of the container
all dumped metadata and data will be located here (though Shell will indicate that the files were dumped to the
you can specify whatever path you want, e.g.:
--envspecifies the environment variables with credentials. Docker image accepts the following environment variables:
CM_ACCESS_TOKEN- user access token for authentication
AWS_ACCESS_KEY_ID- AWS access key (required only for loading CSV files from AWS S3)
AWS_SECRET_ACCESS_KEY- AWS secret key (required only for loading CSV files from AWS S3)
-tiallocates a terminal so you can directly interact with the container, and also keeps the standard input open
clevermaps/shell:latestis the name of the latest image
Info for Linux/Mac OS
Create the mounted dump dir on your system before runing the
docker run command, e.g.
mkdir -p /tmp/dumps.
Otherwise it will be created as owned by
root user and
dumpProject command inside container will fail with error message:
General error=Cannot create project directory=/work/asdfghjkl.
Execution failed. Please contact support for assistance with request_id=qwertzuiop
Shell Docker images are hosted in this DockerHub repository.
There are some useful tricks, which will make the work with Shell much easier:
reverse command search - using the Ctrl+R shortcut, you can search through your command history (stored in spring-shell.log file in the Shell working directory - not available for Docker installation)
Ctrl+R → type "k5" →
openProject --project k5t8mf2a80tay2ng
command completion - using the Tab key, Shell will finish the command/parameter, or list all available commands/parameters
lo→ Tab →
li→ Tab →
listP→ Tab →
command history - by pressing the Up and Down arrow keys, you can navigate through the command history
Having trouble with installation or configuration of CleverMaps Shell? Don't hesitate to contact us at firstname.lastname@example.org.