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.

1
$ cd ~/bin/ # (or somewhere on your $PATH)
2
$ 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
3
$ 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

1
$ 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:

1
$ 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

1
$ 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:

1
$ 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

1
$ 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:

1
$ 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

1
$ 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:

1
$ brightspot-cma download -p "Example Site" -e Production -q "Site Settings"
2
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

1
$ 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:

1
$ brightspot-cma upload -p "Example Site" -e Production -i 70f5b9fb-8bf0-4e8e-999d-b7d5052f64e6
2
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

1
    init      Initialize Project or Environment with given credentials
2
      Usage: init [options]
3
        Options:
4
        * --project, -p
5
            Project
6
        * --environment, -e
7
            Environment
8
        * --endpoint-url, -u
9
            Endpoint URL
10
        * --client-id, -c
11
            Client ID
12
        * --client-secret, -s
13
            Client Secret
14

15
    list-projects      List all Projects
16
      Usage: list-projects
17

18
    list-environments      List all Environments for a given Project
19
      Usage: list-environments [options]
20
        Options:
21
        * --project, -p
22
            Project
23

24
    refresh-types      Refresh Local DB copy of all Content Types
25
      Usage: refresh-types [options]
26
        Options:
27
        * --project, -p
28
            Project
29
        * --environment, -e
30
            Environment
31

32
    list-types      List all Content Types
33
      Usage: list-types [options]
34
        Options:
35
        * --project, -p
36
            Project
37
        * --environment, -e
38
            Environment
39

40
    show-type      Show details for a single Content Type
41
      Usage: show-type [options]
42
        Options:
43
        * --project, -p
44
            Project
45
        * --environment, -e
46
            Environment
47
        * --type, -t
48
            Type
49

50
    test-query      Test Query Without Saving
51
      Usage: test-query [options]
52
        Options:
53
        * --project, -p
54
            Project
55
        * --environment, -e
56
            Environment
57
        * --type, -t
58
            Content Type
59
          --where, -w
60
            Where Clause
61
          --fields, -f
62
            Field Names, comma separated (field1,field2,field3)
63
          --limit, -l
64
            Limit
65
          --offset, -o
66
            Offset
67
          --indent, -i
68
            Indent?
69
            Default: false
70

71
    create-query      Create a query that can be used to download backups
72
      Usage: create-query [options]
73
        Options:
74
        * --project, -p
75
            Project
76
        * --query, -q
77
            Query Name
78
        * --type, -t
79
            Content Type
80
          --where, -w
81
            Where Clause
82
          --fields, -f
83
            Field Names, comma separated (field1,field2,field3)
84

85
    list-queries      List All Queries
86
      Usage: list-queries [options]
87
        Options:
88
          --verbose, -v
89
            List Verbose Details
90
            Default: false
91
        * --project, -p
92
            Project
93

94
    download      Copy data from a Project/Environment to the Local DB
95
      Usage: download [options]
96
        Options:
97
        * --project, -p
98
            Project
99
        * --environment, -e
100
            Environment
101
        * --query, -q
102
            Query Name
103
          --limit, -l
104
            Limit
105

106
    list-downloads      List All Downloads
107
      Usage: list-downloads [options]
108
        Options:
109
        * --project, -p
110
            Project
111
          --environment, -e
112
            Environment
113
          --query, -q
114
            Query Name
115
          --latest-only, -l
116
            Only display latest download
117
            Default: false
118
          --verbose, -v
119
            Display verbose details
120
            Default: false
121
          --json, -j
122
            Display in JSON format
123
            Default: false
124

125
    upload      Upload data to a project environment
126
      Usage: upload [options]
127
        Options:
128
        * --project, -p
129
            Project
130
        * --environment, -e
131
            Environment
132
        * --download-id, -i
133
            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.