Command Line Interface - Administrator Guide

Tom_Garrett · August 29, 2023, 6:13pm

The Command Line Interface (CLI) replaces the Bluescape Config Center, allowing instance admins to use a terminal to make configuration changes to their instances and teams.

Many administrative features are now available in Bluescape Home. Those that are restricted to instance administrators are only configurable using CLI. Log in to Bluescape with your instance administrator account and use the Gear icon in the Bluescape application to Open CLI. The terminal opens in a new tab where you can begin running commands.

The key functionalities and commands available through the CLI include creating teams, configuring features for a team, managing users, and setting up SSO and integrations.

CLI Commands

applications
applications read
broadcasts
broadcasts create
broadcasts delete [ID]
broadcasts read
broadcasts update [ID]
help [COMMANDS]
helpmenus
helpmenus create
helpmenus delete [ID]
helpmenus read
helpmenus update [ID]
organizations
organizations create
organizations delete [ID]
organizations metadata [ID] [KEYS]
organizations read
organizations update [ID]
sso
sso create
sso delete [ID]
sso read
sso update [ID]
users
users create
users delete [ID]
users read
users update [ID]

Running Commands

There are three types of commands supported by bluescape-cli. They are:

General Commands
Entity CRUD Commands
Workflow Commands

Note: Configuration changes made using the CLI do not take effect immediately. The CLI tool works by calling API endpoints to send the packet of desired changes to the database. Since the client app caches the previous settings, the updated settings are picked up in approximately 5 minutes or by triggering a refresh by manually clicking on the refresh button in the browser.

CLI Command Structure

The CLI can process one or more commands using the following structure:

[entity-type] command [subcommand] [args] [flags]

Entity Type

The Entity Type identifies the object that is acted upon by the command, such as a user, organization, SSO provider, instance, etc. For general commands, the entity type is just the command, such as help or applications.

Command

The primary action to be performed on an entity or a general command such as create, read, or update.

Subcommand (or option)

A subcommand provides additional granular control to a command to perform a specific task. For example, metadata is a subcommand.

Arguments

Arguments are further inputs into commands that are mandatory, such as the id of the entity to be operated on.

Flags

Flags allows different types of logic control based on the nature of the command (and subcommand). Examples include --input=<file path> to specify the path to an input file, and --environment=<domain> to indicate which domain(s) to operation the command on.

Command types

General Commands

Operate on bluescape-cli. Supported general commands are:

Command	Description
`help`	Display help for bluescape-cli
`instances`	List of instances. For connected domains, it also shows the signed-in account email

Entity CRUD commands

These commands operate on entities inside an instance. Such as organizations update.

Supported entities are:

Command	Description
`applications`	Lists 3rd party applications
`broadcasts`	Displays Broadcast messages
`helpmenus`	Lists help items added to help menus in all products
`metadata*`	Displays Options/preferences for a particular entity
`organizations`	Lists All organizations - enterprise and self-serve
`sso`	Lists SSO providers (aka IDPs)
`users`	Lists all users in an instance, including archived users

Note: metadata is a nested entity. It is always used with another entity such as organizations metadata

Available commands to do CRUD on an entity

[entity-type] read [id(s)] [flags]
[entity-type] create [flags]
[entity-type] update [id(s)] [flags]
[entity-type] delete [id(s)] [flags]

Read Commands

Specifying only the entity shows a list of the first 50 entities that match any filtering criteria in the sorting order, i.e., organizations. Alternately, use read
To control which 50 entities are returned. Use the sorting and filtering flags.

Filtering and Sorting

Often filtering statements are composed of multiple filtering statements to allow for more complex filtering. The composition use AND, OR, and NOT operators. The operators hold a collection of zero or more filtering statements. Visually, the collection looks like a JavaScript array, i.e. with square brackets. These operators can be siblings to other filtering statements or nested within filtering statements. It’s important to be aware that sibling filtering statements are combined with an implied AND operator.

Delete Commands

Delete commands take only the IdList as a parameter and performs a “soft” delete. For a “hard” delete the --permanent=true or -p flag must be set. This triggers the confirmation prompt. To avoid the prompt use the --force=true flag.

Workflow Commands

Workflow commands combine multiple tasks into one command and/or contain special logic that doesn’t translate to bluescape-cli commands. Workflow commands have workflow in front of them. Individual help for each workflow is available by calling on help for a specific command. For details on accessing help for each command see the Command Details section of this guide. Currently, we only have one workflow command, email-migration.

Running Commands

When using the CLI, commands are run in one of two ways. A single command can be run from the command line, such as organizations The command outputs its results, and then control is returned to the terminal, like so:

$ bluescape login {insert your Bluescape URL}
Successfully signed in to {your Bluescape URL} as instance@bluescape.com`
$

If you want to run multiple commands, it’s more efficient to enter them into the CLI like so:

$ bluescape
bluescape > login {insert your Bluescape URL}
Successfully signed in to {your Bluescape URL} as instance@bluescape.com`
bluescape > organizations create -f new-org-settings.json
successfully created organization <org name> with the following settings:
<list of options from the file>
$

Help Command

A help command is added to each workflow. Call --help in your command for the available flags and usage.

users --help
List of users. By default display only IDs. For other formats, use [--output json or table].

USAGE

$ users [-o id|json|table|csv] [-e <value>] [-f <value>] [-c <value>] [--offset <value>]
    [--suppress max-records-reached|confirm|all]

FLAGS

  -c, --count=<value>        [default: 50] max records to process. Errors when reached and Process return code 2.
                             Error can be suppressed by --suppress=max-records-reached
  -e, --environment=<value>  comma-separated environment (domain)

List of Helpful Commands

How to Check the Version of CLI

Log in to Bluescape with your instance administrator account and use the Gear icon in the Bluescape application to Open CLI. The terminal opens in a new tab where you can begin running commands. The version is visible in the first line in the terminal window.

Example:

Welcome to the Bluescape Command Line Interface. Version: 1.0.13

How to Search for a Users Email

users "--filter={ email: { contains: \"<Input Email>\" } }"

Example:

║ James             │ Bond          │ jb007@bluescape.com           │ Instance Admin   │ ACCEPTED         │  07/27/2023  │ <ID>

How to Search for an Organization by Name

organizations --filter="{name:{contains:\"<Name>\"}}"  -f name,id,owner.email

Example:

testval                                  │ <ID> │ hello@test.com

How to create an SSO provider

sso create -i '{
"name": "name",
"type": "type of SSO",
"metadataUrl": "metadata URL",
"adminEmail": "Admin email"
}'

How to Search for an SSO provider by name

sso --filter='{name:{contains:"okta"}}' -f name,id,owner.email

How to Update SSO details

Capture the SSO ID by SSO provider name:

sso --filter='{name:{contains:"<Input SSO Provider Name>"}}'` `-f name,id,owner.email

Indicate the URL’s attached to the SSO ID:

sso --id=<Input SSO ID> -o json

Update the Metadata URL of an SSO provider:

sso update <Input Org ID> -i '{"metadataUrl": "URL"}'

How to create an Organization

organizations create -i '{"name":"<orgname>","ownerId":"<userID>"}

Example:

organizations create -i '{"name":"testOrg111", "metadata": {"canUploadVideoFiles":true,"enableVideoUnmuteAll":true,"userGroupsInUse": true,"enableSendToWall":true,"laserPointerEnabled":true, "enableMetabaseDashboard":true, "metabaseDashboardId":<ID> },"ownerId":"<Input Owner ID>"}'

How to change the name of an Organization

organizations update --id=<Input ID> -i '{"name":"<Input New Org Name>"}'

How to List an Organization’s Metadata by ID

organizations --filter='{name:{contains:"bluescape"}}' -f name,id,owner.email

organizations metadata <Input Org ID>

Example:

"id": "<ID of Org>",
 "metadata": {
    "canHideRevealContent": true,
    "canUploadVideoFiles": true,
    "disableMeet": false,
    "disablePublicWorkspace": false,
    "displayImageFilename": true,
    "displayMode": "dark",
    "enableAem": false,
    "enableAntivirusScan": false,
    "enableDocumentSupport": true,
    "enableDrm": false,

etc.

How to Enable an Organization’s Metadata Flag

organizations metadata <Org ID> <Input Metadata Flag=true/false>

Example:

[
{
  "id": "<Org ID>",
  "metadata": {
    "hasBox": true
  },
  "__typename": "Organization"
}
]

How to update an organization’s “Feature” flag

Organizations update --id=<ID> -i '{"<featureDBkey>":<true/false>}'

Change an Organization’s Expiration Date

organizations update --id= <ID>  -i {"expiredAt":"2023-00-22T00:00:00.000Z"}

Find the owner of existing org by name and get owner ID

organizations --count=3 -l '{name: { contains: "al" } }' -f name,owner.email,owner.id

Change an Organization’s Owner

organizations update --id=<Org ID> -i '{"ownerId":"New Owner ID"}'

Create Broadcast message

Input the start, end, and body of the broadcast message, paste the code block into Cloud CLI, and press enter.

broadcasts create -i '{"body": "CLI Test <a href=\"[https://bluescape.com](https://bluescape.com/)\">link</a>","isDismissable": true,"type": "Public"}'

Example:

broadcasts create -i '{
"isDismissable": true,
"type": "Public",
"startAt":"2023-XX-XXT12:00:00Z",
"endAt":"2023-XX-XXT21:00:00Z",
"body":"Sample Message to Broadcast."
}'

Find owner of existing org by name and get owner ID

organizations --count=3 -l '{name: { contains: "al" } }' -f name,owner.email,owner.id

How to change an application role

Search for the user to capture their user id.
Determine the application role id that the user needs to be upgraded to using the roles command.
Update the application role id.

The commands detailed above are visible in the following example:

Command to locate user and their id:

users "--filter={ email: { contains: \"jane.doe@bluescape.com\" } }"

Command to list available roles and their ids:

roles

Command to update the application role id:

users update --id=<Input User ID> -i '{"applicationRoleId":"<Input Application ID>"}'

Find a user ID

users -l '{lastName:{contains:"INSERT USER LAST NAME"}}'
users -l '{email:{contains:"INSERT PORTION OF USERS EMAIL"}}'

Change user’s associated email address

users update [userID] -i '{"email":"INSERT NEW EMAIL ADDRESS HERE"}'

Enable native large display functionality

organizations metadata <orgID> enableLargeDisplay=true

Clear all CLI contents

clear + Enter / Return key on keyboard

Command Details

For full details on each CLI command, use the following syntax in the CLI.

[entity type] [command] --help

e.g., organizations delete --help

This example returns the following information:

Delete organization object. Prints deleted object
USAGE
  $ organizations delete [ID]
  [-p]  [--force <value>] [-d
  gql|curl|fetch]  [-t <value.] [-e
  <value>]  [--id <value>]
ARGUMENTS
  ID id of object to be deleted. If omitted, it has to be provided in JSON
FLAGS
  -d, --debug=<option>
       Dump the requests parameters sufficient to be replicated manually via GraphQL inspector, CURL unix command, or fetch() JS API in browser debug console.
       <options: gql|curl|fetch>
  -e, --environment=<value>
       comma-separated list of instances (environments)
  -i  --input=<value>
      input file | stdin | user | json
      string
  -o --output=<option>
      [default: id] output format.
      <options: id|json|table|csv>
  -p, --permanent
      When "ispermanentDlete" is true,
      1) A request to Collab to Delete Workspaces of the Organization is initiated
      2) The Organization and its relationships are Hard Deleted. 
      When"isPermanentDelete" is false,
      1) Users who belong to only this organization are archived
      2) User Organization relationship is Soft deleted
      3) Organization is Soft Deleted.
  -t, --token=<value>
      idToken from authorized session
  --force=<value>
      set as true to override the prompt for hard deletes
  --id=<value>
      comma-separated ID list. Use instead of passing id(s) via an argument.
DESCRIPTION
   Delete organization object. Prints deleted object
EXAMPLES
  $ organizations delete i7cS4mTkC2TwETcA5gwc
  { deleteOrganization: true }

Topic		Replies	Views
Bluescape for Government \| August 2023 Release Notes Product Updates	0	476	August 29, 2023
Administrative Functionality in Bluescape Home Using Bluescape team-admin	0	1064	June 6, 2023
Bulk User Deletion Process Support on-premises , api	1	674	September 11, 2022
Bluescape Plugin for Rocket.Chat Developer	0	424	April 25, 2024
Command History is Not Recorded After Reaching Timeout Period for Cloud CLI Support known-issue	1	382	December 7, 2023

Command Line Interface - Administrator Guide

CLI Commands

Running Commands

CLI Command Structure

Entity Type

Command

Subcommand (or option)

Arguments

Flags

Command types

General Commands

Entity CRUD commands

Available commands to do CRUD on an entity

Read Commands

Filtering and Sorting

Delete Commands

Workflow Commands

Running Commands

Help Command

List of Helpful Commands

How to Check the Version of CLI

How to Search for a Users Email

How to Search for an Organization by Name

How to create an SSO provider

How to Search for an SSO provider by name

How to Update SSO details

How to create an Organization

How to change the name of an Organization

How to List an Organization’s Metadata by ID

How to Enable an Organization’s Metadata Flag

How to update an organization’s “Feature” flag

Change an Organization’s Expiration Date

Find the owner of existing org by name and get owner ID

Change an Organization’s Owner

Create Broadcast message

Find owner of existing org by name and get owner ID

How to change an application role

Find a user ID

Change user’s associated email address

Enable native large display functionality

Clear all CLI contents

Command Details

Related topics