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

Further Reading