Command Line
The Cloud CMS command-line client gives developers a way to work with their Cloud CMS tenant projects, applications, data stores and other resources from the command line. The CLI (command-line client) is a Node.js based command line tool that is very easy to use and available at no charge.
Note: A valid Cloud CMS subscription is required to connect to Cloud CMS with the command-line client. This subscription can be a paid subscription or a free trial account.
Getting Started
To get started, you need to install Node.js on your development laptop and then use NPM to install the command-line client.
Step 1: Install Node.js
Visit http://www.nodejs.org and pick an installation package that is suitable for your operating system. Run the installer and pick all the default options. You're all set!
Step 2: Install the Cloud CMS command-line client
Once Node.js has been installed, you should open up a terminal window to drop into the command line. And then run,
npm install cloudcms-cli -g
Step 3: Connect to Cloud CMS
You should now connect your Cloud CMS tenant. Run the following:
cloudcms init
And walk through the prompts. You will be asked for the URL to your UI server. If you're connecting to a trial account, this will be something like https://mytenant.cloudcms.net
. For the API server, you can put https://api.cloudcms.com
.
If you're connecting to a locally installed Cloud CMS environment that uses the Docker samples that we provide, the UI server will typically be http://localhost
and the API server may be http://localhost:8080
.
If you're otherwise connecting to an on-premise or self-hosted instance of Cloud CMS, please check with your system administrator for information about the URLs to use for the UI and API servers.
To get your Cloud CMS client keys and login credentials,
visit "https://gitana.io".
Enter the URL to your Cloud CMS UI endpoint: https://mytenant.cloudcms.net
Enter the URL to your Cloud CMS API endpoint: https://api.cloudcms.com
Enter your username: myUsername
Enter your password: myPassword
Testing connectivity...
Successfully connected to Cloud CMS!
Cloud CMS platform connection credentials were saved to:
/Users/username/.cloudcms/credentials.json
You can also invoke this using switches, like this:
cloudcms init --ui https://mytenant.cloudcms.net --api https://api.cloudcms.com --username myUsername --password myPassword
Usage
In general, you run the command line tool like this:
cloudcms <command> [switches]
Many commands are also grouped. Grouped commands work like this:
cloudcms <group> <command> [switches]
Switches are either key/value pairs or booleans. Key/value pairs are specified in the form --<key> <value>
. Booleans are simply specified as --<key>
.
To see the list of commands, simply type:
cloudcms
You can then pull up commands for a group, like this:
cloudcms <group>
To pull up information about a specific command, use the --help
switch.
cloudcms <command> --help
cloudcms <group> <command> --help
To see the version of the command line tool:
cloudcms --version
Using an .rc
file
You can create an .rc
file and populate it with command line arguments that you would like to have automatically get passed in by default. This is very useful when working with a repository or branch where you have fixed IDs that you know ahead of time.
The .rc
file should sit in the same directory as where you're executing the command line tool.
Here is a sample .rc
file:
{
"global": {
"arguments": {
"repository": "7d18d8bafa6923e6d126",
"branch": "2b2fac2fdb6ae406fe8f",
"pretty": "true"
}
}
}
With this .rc
file in place, a command like:
cloudcms node query --repository 7d18d8bafa6923e6d126 --branch 2b2fac2fdb6ae406fe8f --query "{'rating': { '$gt': 3 }}" --pretty
Can be run like this:
cloudcms node query --query "{'rating': { '$gt': 3 }}"
Or you might pull back the children of a node at a given path like this:
cloudcms node children --path /System/Themes
Using the .last_command
file
When the command line tool runs, a file named .last_command
will be generated that stores the arguments and options passed to the tool on the previous invocation.
If you pass the --last
switch to the command line client, the tool will scan the current directory for a .last_command
file. If one is found, it will be picked up and the values from within will be merged in.
This provides a way for values passed in to the command line tool to be preserved so that they can be used on subsequent calls.
Here is an example of what the .last_command
file may look like:
{
"command": {
"group": "node",
"name": "relatives"
},
"arguments": {
"repository": "894e48dcc5a2fa248e8d",
"branch": "master"
}
}
Connecting with Multiple Profiles
You can manage multiple Cloud CMS connection profiles and select between them using the --profile
switch. For example,
cloudcms init --profile dev
Will walk you through the prompts to initialize a connection to Cloud CMS. The resulting file is saved to:
~/.cloudcms/credentials/dev.json
You can use the --profile
switch to connect to multiple Cloud CMS clusters, each with their own stored credentials.
You can then invoke commands and use the --profile
switch to pick which profile to use. For example:
cloudcms platform list-repositories --profile dev
This will list all the repositories on the dev
environment.
Examples
Here are a few examples of how the tool is used.
Query for Nodes on a branch
Find all content where the rating
is greater than 3:
cloudcms node query --repository 7d18d8bafa6923e6d126 --branch 2b2fac2fdb6ae406fe8f --query "{'rating': { '$gt': 3 }}"
Find all content where the rating
is greater than 3 and hand back 25 items starting while sorting by customer.name
ascending and format things to be readable:
cloudcms node query --repository 7d18d8bafa6923e6d126 --branch 2b2fac2fdb6ae406fe8f --query "{'rating': { '$gt': 3 }}" --limit 50 --sort "{'customer.name': -1}" --pretty
Find all content where rating
is less than 5 and limit the response so that we only get back the title
and customer
fields:
cloudcms node query --repository 7d18d8bafa6923e6d126 --branch 2b2fac2fdb6ae406fe8f --query "{'rating': { '$lt': 5 }}" --fields "{'title': 1, 'customer': 1}" --pretty
Search for Nodes on a branch
Find all content where the word hello
appears in the text:
cloudcms node search --repository 7d18d8bafa6923e6d126 --branch 2b2fac2fdb6ae406fe8f --text "hello"
Find all content where the word hello
appears and hand back 50 items starting at the 100th entry while sorting by title
descending and format things to be readable:
cloudcms node search --repository 7d18d8bafa6923e6d126 --branch 2b2fac2fdb6ae406fe8f --text "hello" --limit 50 --skip 100 --sort "{'title': -1}" --pretty