Use the Sigma CLI

You can programmatically manage your Sigma documents, users, and data using the Sigma CLI. For instructions to set up the Sigma CLI, see Install and configure the Sigma CLI.

This document explains the basic command structure of the Sigma CLI, outputs, and logging.

Command structure

Commands in the Sigma CLI follow a common structure, in the format:

sigma api <resource> <action> [--flags]

For example, the following command lists workbooks in the organization associated with the current profile:

sigma api workbooks list

To see a list of all resources you can interact with via the Sigma CLI, run the following command:

sigma --help

To see a list of actions and flags for a particular resource type, run the following command:

sigma api <resource> --help

For example, to see all actions and flags for connections, run the following command:

sigma api connections --help

Structure API calls using the Sigma CLI

To see the parameters a command accepts, including each parameter name and whether it’s required, run the schema command for that command path:

# Print the schema for the workbooks get command
sigma api schema workbooks get

To pass a path parameter, include it as a key in the JSON object you provide to the --params flag. For example, the Get a workbook endpoint requires a workbookId path parameter:

# Retrieve a single workbook by its ID
sigma api workbooks get --params '{"workbookId":"<workbook-id>"}'

To pass query parameters, add them as additional keys. For example, you can limit the number of results the List workbooks endpoint returns:

# List workbooks, returning at most two results
sigma api workbooks list --params '{"limit":2}'

You can combine path and query parameters in the same JSON object. For example, the following command lists the pages of a specific workbook and limits the results:

# List up to three pages of a specific workbook
sigma api workbooks pages list --params '{"workbookId":"<workbook-id>","limit":3}'

Provide a request body

Endpoints that accept a request body take that body through the --body flag. For example, the following command grants a member view access to a workbook:

# Grant a member view access to a workbook
sigma api workbooks grants create --params '{"workbookId":"<workbook-id>"}' --body '{"grants":[{"grantee":{"memberId":"<member-id>"},"permission":"view"}]}'

Read parameters and request bodies from a file or stdin

The --params and --body flags accept a JSON or YAML value, either written inline to the command or read from a file. To read the value from a file, prefix the file path with @:

# Read the request body from a local file
sigma api connections create --body @connection.yaml

To read the value from stdin, pass @-:

# Pipe the request body from another command
cat connection.json | sigma api connections create --body @-

Because stdin can be read only once, use @- with a single flag per command. If you pass @- to both --params and --body, --params consumes the input regardless of the order you list the flags, and --body sends an empty request body without reporting an error.

If the specified file doesn’t exist, or if the content isn’t valid JSON or YAML, the command returns a validation error and exits with code 3.

Manage command output

You can pipe command output from the Sigma CLI to other commands to create custom scripts and workflows.

All command output in the Sigma CLI is formatted as JSON printed to stdout.

For example, to filter a list of workbooks using jq, run the following command:

# Pipe to jq for filtering
sigma api workbooks list | jq '.entries[].name'

To save the metadata for a workbook to a file titled workbook.json, run the following command:

# Save to a file
sigma api workbooks get --params '{"workbookId":"<workbook-id>"}' > workbook.json

Interpret exit codes and manage errors

To check if a Sigma CLI command was successful, or to understand the cause of an error when using the Sigma CLI, refer to the following exit codes:

All errors are formatted as JSON printed to stdout, with a colored label printed to stderr.

For example, if you request a workbook with an invalid workbookId, such as in the following command:

sigma api workbooks get --params '{"workbookId":"invalid-id"}'

The following structured error prints to stdout:

{
  "code": 400,
  "error": "api",
  "message": "Expecting UUID at workbookId but instead got: \"inva...\"",
  "requestId": null
}

The error label prints to stderr:

error[api]: Expecting UUID at workbookId but instead got: "inva..."

Enable debug logging

To troubleshoot errors when working with the Sigma CLI, you can enable debug logging by setting the SIGMA_CLI_LOG environment variable.

For example, to see the debug log when requesting a list of connections, run the following command:

SIGMA_CLI_LOG=debug sigma api connections list