Skip to main content

Brightspot REST CMA Command Line Interface

This tool provides a command line interface to Brightspot's REST CMA API.

note

This requires the optional dependency com.psddev:cms-api, which is available as of Brightspot version 4.2.20.

Installation​

Download the brightspot-cma script and rest-api-cli.jar and place them together in your $PATH.

$ cd ~/bin/ # (or somewhere on your $PATH)
$ curl -o rest-api-cli.jar https://artifactory.psdops.com/public/com/psddev/component-lib/rest-api-cli/%5BRELEASE%5D/rest-api-cli-%5BRELEASE%5D.jar
$ unzip rest-api-cli.jar brightspot-cma

Dependencies​

At least Java 8 and java on your $PATH.

Command Overview​

Step 1: Initialize project and environment​

$ brightspot-cma init -p <project-name> -e <environment-name> -u <endpoint-url> -c <client-id> -s <client-secret> [-n <basic-auth-username> -w <basic-auth-password>]

This command create a Local DB using the normalized <project-name>, initialized or reinitializes an environment named <environment-name> with the specified <endpoint-url>, <client-id>, and <client-secret>.

Example:

$ brightspot-cma init -p "Example Site" -e "Production" -u https://example.com/api/rest/cma -c 00000000000000000000000000000000 -s xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx -n debug -w 12345123451234512345123451234512

Tip: You can see which projects and environments have been created by using the list-projects and list-environments commands.

Step 2: Test a Query​

$ brightspot-cma test-query -p <project-name> -e <environment-name> -t <content-type> [-w <where>] [-f <comma,separated,fields>] [-l <limit>] [-o <offset>] [-i]

This command simply executes a query and displays the results. Check the documentation for details on how to write a Brightspot query.

Example:

$ brightspot-cma test-query -p "Example Site" -e Production -t com.psddev.cms.db.Site -f urls,simplestAuth.simplestAuthConfiguration -i

Tip: Use the commands refresh-types, list-types, and show-type to find the content type(s) you need.

Step 3: Create a Query​

$ brightspot-cma create-query -p <project-name> -t <content-type> -q <query-name> [-f <comma,separated,fields>]

This command saves the given Query in the Local DB.

Example:

$ brightspot-cma create-query -p "Example Site" -t com.psddev.cms.db.Site -f urls,simplestAuth.simplestAuthConfiguration -q "Site Settings"

Tip: Use the command list-queries to list existing queries.

Step 4: Download Query Data from an Environment​

$ brightspot-cma download -p <project-name> -e <environment-name> -q <query-name>

This command downloads all data matching the given query and saves it to your Local DB. It also prints the Download ID, which you'll use later to upload the downloaded data.

Example:

$ brightspot-cma download -p "Example Site" -e Production -q "Site Settings"
70f5b9fb-8bf0-4e8e-999d-b7d5052f64e6

Tip: Use the command list-downloads -v to list all downloads and their IDs.

Step 5: Upload Downloaded Query Data to an Environment​

$ brightspot-cma upload -p <project-name> -e <environment-name> -i <download-id>

This command uploads all data downloaded in Step 4 to the given environment.

Example:

$ brightspot-cma upload -p "Example Site" -e Production -i 70f5b9fb-8bf0-4e8e-999d-b7d5052f64e6
Uploading [0000017e-5916-d0fd-a7fe-fb9f88170000] [1/1]

Tip: By specifying a subset of fields in the Query, you can limit which fields will be updated on the target environment.

Command Reference​

    init      Initialize Project or Environment with given credentials
      Usage: init [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment
        * --endpoint-url, -u
            Endpoint URL
        * --client-id, -c
            Client ID
        * --client-secret, -s
            Client Secret

    list-projects      List all Projects
      Usage: list-projects

    list-environments      List all Environments for a given Project
      Usage: list-environments [options]
        Options:
        * --project, -p
            Project

    refresh-types      Refresh Local DB copy of all Content Types
      Usage: refresh-types [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment

    list-types      List all Content Types
      Usage: list-types [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment

    show-type      Show details for a single Content Type
      Usage: show-type [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment
        * --type, -t
            Type

    test-query      Test Query Without Saving
      Usage: test-query [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment
        * --type, -t
            Content Type
          --where, -w
            Where Clause
          --fields, -f
            Field Names, comma separated (field1,field2,field3)
          --limit, -l
            Limit
          --offset, -o
            Offset
          --indent, -i
            Indent?
            Default: false

    create-query      Create a query that can be used to download backups
      Usage: create-query [options]
        Options:
        * --project, -p
            Project
        * --query, -q
            Query Name
        * --type, -t
            Content Type
          --where, -w
            Where Clause
          --fields, -f
            Field Names, comma separated (field1,field2,field3)

    list-queries      List All Queries
      Usage: list-queries [options]
        Options:
          --verbose, -v
            List Verbose Details
            Default: false
        * --project, -p
            Project

    download      Copy data from a Project/Environment to the Local DB
      Usage: download [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment
        * --query, -q
            Query Name
          --limit, -l
            Limit

    list-downloads      List All Downloads
      Usage: list-downloads [options]
        Options:
        * --project, -p
            Project
          --environment, -e
            Environment
          --query, -q
            Query Name
          --latest-only, -l
            Only display latest download
            Default: false
          --verbose, -v
            Display verbose details
            Default: false
          --json, -j
            Display in JSON format
            Default: false

    upload      Upload data to a project environment
      Usage: upload [options]
        Options:
        * --project, -p
            Project
        * --environment, -e
            Environment
        * --download-id, -i
            Download ID

Definitions​

Project​

A Project represents a logical Brightspot application belonging to a single customer and consisting of one or more Environments. Data can be copied between Environments on a single Project, but not from one Project to another Project.

All configuration and locally cached data for a given Project is stored in a single Local DB file.

Environment​

An Environment is a single instance of Brightspot in a Project. QA, UAT, and Production are all Environments. Each environment will have a single Endpoint URL, Client ID, and Client Secret.

Endpoint URL, Client ID, and Client Secret​

These settings can be found on the REST API configuration in Brightspot.

Local DB​

This tool uses a collection of SQLite databases in $HOME/.brightspot_api_data; one per project. These can be queried and modified using any compatible SQLite utilities.