skuid CLI

skuid is a command line interface (CLI) for retrieving and deploying Skuid objects (data and metadata) on Skuid NLX sites.

While Skuid is a cloud user experience platform, it can be helpful to:

  • download an entire site’s worth of pages to make small adjustments locally
  • move Skuid configurations from a sandbox site to a production site
  • store Skuid configurations in a version control system (VCS)

While it’s possible to save individual pieces of metadata, moving entire apps’ worth of Skuid objects from site to site can prove challenging.

Enter the skuid CLI. Using skuid, you can easily pull (download) Skuid metadata and push (upload) Skuid metadata from one site to another using only a few commands.

Note: skuid CLI is open source, and we accept pull requests! If there is a feature you’d like to see, feel free to contribute.

Working with Salesforce?

Using skuid CLI for Salesforce-related processes is no longer supported as of v0.6.x of the CLI.

However, skuid-sfdx is our open-source Salesforce CLI plugin designed to handle Skuid metadata on the Salesforce platform. This plugin can push/pull Skuid pages to and from Salesforce orgs.

Prerequisites

  • Some basic knowledge of the command line is required, including how to open and use a command line program such as Terminal or Powershell.
    • You should feel comfortable interacting with the file system with commands like cd, mv, and rm.
    • You should feel comfortable using the skuid command with the necessary environment variables and flags.

Installation

macOS and Linux

If you have curl, grep and awk in your environment, you can quickly install the application via the command line:

# macOS:
curl -Lo skuid https://github.com/skuid/skuid-cli/releases/latest/download/skuid_darwin_amd64
# Linux:
curl -Lo skuid https://github.com/skuid/skuid-cli/releases/latest/download/skuid_linux_amd64

# Give the skuid application the permissions it needs to run
chmod +x skuid

# Move the skuid application to a folder where it can be used easily, 
# for example, a directory in your $PATH.
# Enter your computer account password if prompted
sudo mv skuid /usr/local/bin/skuid

To manually install the application, follow these steps:

  1. Download the latest release of the skuid application binary.

  2. Navigate to the directory containing the skuid binary file in a terminal application.

    cd /path/to/the/downloaded/binary
    
  3. Rename the downloaded application binary file to skuid:

    # macOS:
    mv skuid_darwin_amd64 skuid
    # Linux:
    # mv skuid_linux_amd64 skuid
    
  4. Give the application executable permissions:

    chmod +x skuid
    
  5. Ensure the binary is accessible in your $PATH variable. This can be done one of two ways:

    • Move the application to a folder that’s already in your $PATH variable, like /usr/local/bin

      mv skuid /usr/local/bin/skuid
      
    • Add the application’s folder to the PATH variable:

      # This method doesn't require moving the `skuid` binary, which may be not be possible depending on user permissions.
      # The location of the `skuid` binary isn't important in this use case, but try to store it in a folder it's unlikely to move from.
      
      # This example assumes the `skuid` binary is located in ~/Documents/Skuid
      export PATH=$PATH:~/Documents/Skuid
      

    Note

    If you choose to update your shell profile you’ll need to source your shell profile or restart your session for those changes to take effect.

  6. Verify that you can run the application:

    skuid --version
    

Windows

  1. Download the latest Windows executable release in your web browser.

  2. (Optional) Move the executable to a more permanent location, such as C:\Program Files\Skuid\.

  3. (Optional) Set an alias to easily access the executable.

    In Windows Powershell, use Set-Alias. For information about saving aliases in Powershell, see Microsoft documentation

    Set-Alias skuid C:\Path\To\skuid_windows_amd64.exe
    

    In the Windows Command Prompt, use doskey. For information about saving doskey aliases for future sessions, see Microsoft documentation.

    doskey skuid=C:\Path\To\skuid_windows_amd64.exe
    
  4. Invoke the executable by typing its name or alias and pressing enter: skuid --help.

Using go

Use the the Go programming language? If so, you can also install skuid by running go get github.com/skuid/skuid-cli.

Building from source

To build the application from the source, first clone the repository or download the source. You also need Go installed on your machine.

  • To build from source for your machine:

    go build
    
  • Building for a specific platform:

    GOOS=linux GOARCH=amd64 go build
    # or
    GOOS=linux GOARCH=amd64 make build #requires docker
    

Upgrading skuid CLI

To upgrade skuid, first remove the previous version’s binary:

# Use the rm command with the appropriate path to the skuid binary
# For example, if the binary is installed in /usr/local/bin:
rm /usr/local/bin/skuid

After removing the previous version, repeat the installation steps listed above.

Configuration

Information can be passed to skuid CLI as flags or as environment variables. At minimum you must provide a username, password, and a host. While you can set username, password, and host with flags, consider setting the following environment variables to avoid entering credentials with every command.

For information that requires set values, set the flag or environment variable to the appropriate value:

# Retrieve using the "exampleuser" user name
# With a flag
skuid retrieve --username "exampleuser"
# With an environment variable
export SKUID_UN='exampleuser'
skuid retrieve

For boolean (on/off) features, set flag or set the environment variable to true/false:

# Retrieve metadata and generate a log file for the action in the parent directory
# With a flag
skuid retrieve --file-logging --log-directory="../"
# With an environment variable
export SKUID_FILE_LOGGING="true"
export SKUID_LOGGING_DIRECTORY="../"
skuid retrieve

macOS and Linux

Enter the appropriate information in the format listed below, listing your own username, password, etc., immediately following the = equals sign. You can drop these in your ~/.bash_profile, ~/.zshrc, or into a .env file in the project directory.

export SKUID_UN='username'
export SKUID_PW='password'
export SKUID_HOST='https://example.skuidsite.com'

Windows

How you set your environment variables differs depending on your command line program of choice:

Powershell

Set-Item Env:SKUID_UN 'username'
Set-Item Env:SKUID_PW 'password'
Set-Item Env:SKUID_HOST 'https://example.skuidsite.com'

Command Prompt

Set SKUID_UN=username
Set SKUID_PW=password
Set SKUID_HOST=https://example.skuidsite.com

Usage

skuid is used to do two things:

  1. Retrieve/pull Skuid data and metadata from a platform hosting Skuid and store it on the local machine
  2. Deploy/push Skuid data and metadata from the local machine to a platform hosting Skuid

All of this is done using the following syntax:

  skuid [command] [flags]

Commands

  • retrieve retrieves metadata from a Skuid NLX site.
  • deploy sends metadata to a Skuid NLX site.
  • watch listens for changes to local metadata files and sends changes to a Skuid NLX site.
  • help displays short documentation about the CLI’s features, and it can be used in combination with other commands, e.g. skuid help deploy displays information about the deploy command

Command Flags

Authentication and Platform

These flags can be used when authenticating to either platform in lieu of exporting environment variables.

  • --host: (string) The Skuid host platform’s base URL, e.g. https://example.skuidsite.com for Skuid NLX
    • Environment variable: SKUID_HOST
  • --password: (string) Skuid NLX password
    • Abbreviated form: -p
    • Environment variable: SKUID_PW
  • --username: (string) Skuid NLX username
    • Abbreviated form: -u
    • Environment variable: SKUID_UN
  • --dataServiceProxy (string): The IP or URI through which traffic should be routed to reach a Skuid site’s data services. May be necessary for cases where skuid CLI is executed from a machine on an internal network and VPN rules require proxy use.
  • --metadataServiceProxy (string): The IP or URI through which traffic should be routed to reach a Skuid site’s metadata service. May be necessary for cases where skuid CLI is executed from a machine on an internal network and VPN rules require proxy use.
  • --app: (string) The Skuid NLX app to retrieve or deploy all associated metadata for. Using this flag means the CLI will not retrieve/deploy any other metadata outside of the app’s resources. Only accepts one argument.
    • Abbreviated form: -a
    • Note: If an app’s name contains spaces, be sure to wrap it in quotes: skuid retrieve --app "Multi-word App Name"

Data management

  • --dir: (string) The input/output directory where files are retrieved and stored to or deployed from.

    • Abbreviated form: -d
    • Environment variable: SKUID_DEFAULT_FOLDER
  • --ignore-skuid-db: Acknowledges the constraints of deploying Skuid Database and ignores any problematic Skuid Database metadata for the current deployment.

    • Environment variable: SKUID_IGNORE_SKUIDDB
  • --since: (string) For use with the retrieve command, only retrieves files that have been modified since the given date value. Date values can appear in any of the layouts mentioned in Go’s time library’s Constants section, and several abbreviations are respected for phrasal values (e.g. minutes can be written as “m,” “min,” “mins,” etc.)

    Some common formats include:

    Timestamp:

    # Retrieve metadata updated since May 22nd, 2023
    skuid retrieve --since "2023-05-22"
    

    Phrasal date:

    # Retrieve metadata updated in the last three days
    skuid retrieve --since "3 days"
    

    Abbreviated combinations:

    # Retrieve metadata updated in the past week, 4 days, 3 hours, and 15 minutes 
    skuid retrieve --since "1w4d3h15m"
    

    Warning: If using a date value with spaces, be sure to encase the value in quotes—otherwise the empty space characters may result in the following error: A --since option was provided but was not parsable as a time or duration

    Note: Due to necessary backend implementation details SQL data sources, and permission sets on those data sources, are typically returned regardless of their updated date.

Debugging

  • --version: Displays the version of the skuid CLI binary in use
  • --verbose: When used, skuid displays additional logging information, including authentication status, file/folder CRUD operations, and confirmation of a successful or erroneous deployment/retrieval.
    • Abbreviated form: -v
    • Environment variable: SKUID_VERBOSE which accepts true/false
  • --trace: When used, skuid displays all information available through --verbose, as well as network request attempts, request details, and additional information on file/folder CRUD operations.
  • --diagnostic: When used, display all information available through --trace, with information on the username, host, attempted process, and start datetime stamp for each event.
    • Environment variable: SKUID_FIELD_LOGGING which accepts true/false
  • --file-logging: When using –file-logging, all information available through --diagnostic and other technical details are logged to a .log file within the current directory with the current timestamp as the file name. Diagnostic information does not appear in the terminal when this flag is used.
    • Environment variable: SKUID_FILE_LOGGING which accepts true/false
  • --log-directory: Determines the output directory for the .log file produced by the --file-logging flag. Target directory for file logging
    • Abbreviated form: -l
    • Environment variable: SKUID_LOGGING_DIRECTORY which accepts a string

Other

It is also possible to use the --api-version flag to select which version of the deployment API to use, however it does not have much use as only version 1 is active at this time.

Deployment with Skuid Database

There are special constraints for working with Skuid Database in skuid CLI:

  • skuid CLI won’t redeploy existing databases to avoid overwriting schema
  • skuid CLI won’t deploy more databases than a site’s allotted limit

skuid CLI will also fail deployments that trip these safeguards—displaying an error describing the duplicate database or database limit. The CLI fails these deployments to prevent updates relying on certain database/database schema from being deployed when the necessary database updates are not.

To acknowledge these constraints and proceed with the deployment by ignoring any error-causing Skuid Database metadata, use the --ignore-skuid-db flag or set the SKUID_IGNORE_SKUIDDB environment variable to true.

To transfer metadata/schema updates from site-to-site, you must manually make these updates in the Database Console user interface.

skuid deploy --ignore-skuid-db

Examples

  • Retrieve all Skuid metadata from a Skuid NLX site and store in the current directory:

    skuid retrieve
    
  • Retrieve all Skuid metadata from a Skuid NLX site and store in a specified directory:

    skuid retrieve -d sites/humboldt-us-trial
    
  • Only retrieve Skuid NLX metadata for an app named “Example app”

    skuid retrieve --app "Example app"
    
  • Deploy all metadata in the current directory to a Skuid NLX site:

    skuid deploy
    
  • Deploy all metadata in a different directory to a Skuid NLX site:

    skuid deploy -d path/to/directory
    
  • Deploy metadata from a different directory, but only for an app named “Example app,” to a Skuid NLX site:

    skuid deploy -d path/to/directory --app "Example app"
    
  • Listen for changes to Skuid metadata in the current directory and deploy changed files to a Skuid NLX site:

    skuid watch
    
  • Listen for changes to Skuid metadata in a different directory, and deploy changed files to a Skuid NLX site:

    skuid watch -d path/to/directory
    

Skuid Object Structure

When retrieving from Skuid NLX sites, the following is downloaded:

What Is Not Retrieved by skuid

  • Created by and Modified by metadata for pages
    • When deploying Skuid pages to a site, the created/modified by user and date matches the identity of whoever is running the deployment, as well as the time and date of the deployment.
  • Authentication provider credentials
    • You must re-enter any client ID and client secret pairs on all Skuid authentication providers in the target site, even if those authentication providers already existed.
  • Users and user data for Skuid NLX
    • While user profiles are transferred, individual user accounts and their information are not. Users must be manually re-created—or provisioned through single sign-on—for at least the first deployment.

Use Cases

Version control

Retrieving Skuid data objects for local storage allows for the use of version control systems, such as git.

For example, you could create a directory for your Skuid site and initiate a git repository:

mkdir my-skuid-site
cd my-skuid-site
git init

After exporting the proper Skuid authentication credentials, you could retrieve and commit Skuid data within that git repo:

skuid retrieve
git add -A
git commit -m 'Initial commit of Skuid site'

With a workflow like this, it’s easier to capture snapshots of Skuid sites at certain points in time, allowing for both easy rollbacks (should issues arise) as well as developer collaboration on these Skuid objects.

Sandboxes

skuid is particularly useful for moving Skuid data from a sandbox—or testing space—to production for end-users.

The -u, -p and --host flags can be used to temporarily set different authentication and platform settings.

For example, consider a workflow like below:

# Set the authentication credentials for the sandbox site, assuming they are not set already
export SKUID_UN='{sandbox-username}'
export SKUID_PW='{sandbox-password}'
export SKUID_HOST='{https://example-sandbox.skuidsite.com}'
# Retrieve sandbox data
skuid retrieve
# Deploy sandbox data to production by temporarily using different credentials
skuid deploy -u production-username -p production-password  --host https://production-sandbox.skuidsite.com}

Consider automating this process using shell scripts. Experiment to find the workflow that best suits your lifecycle management processes.

Troubleshooting

skuid tries to only show basic information to avoid cluttering the terminal. If you’re seeing errors, a good first step is try the command again with the -v or --verbose flag to log more information.

Some possible error messages include:

  • unexpected end of JSON input
    • This may mean that the SKUID_UN and SKUID_PW variables are not set.
  • Error deploying metadata: Post https://example.skuidsite.com/api/v1/metadata/deploy: EOF
    • This may mean your Skuid credentials are not correct within your environment variables. Verify both your username and password.
  • Error retrieving metadata:  Error making HTTP request%!(EXTRA string=413 Payload Too Large)
    • This can indicate that there are files besides Skuid data within the directory you are attempting to deploy. Verify that there are no other applications or files in the Skuid data directory. If you are using the skuid CLI application in the same directory as your data, you’ll need to move your data a different directory and use the --dir flag to point to it.
  • Error retrieving metadata:  Error making HTTP request%!(EXTRA string=401 Unauthorized)
    • Your SKUID_UN or SKUID_PW may not be set correctly. Verify your user credentials.
    • Ensure you have the latest version of the skuid CLI. If your credentials are correct, try removing your current installation and reinstalling the binary.
  • Error deploying metadata: Error making HTTP request%!(EXTRA string=400 Bad Request) or Error deploying metadata: Error making HTTP request%!(EXTRA string=500 Internal Server Error)
    • These errors indicate there may be an issue with the retrieval of your Skuid NLX apps.
      • Ensure that all apps you have retrieved are properly configured, with correct routes and corresponding pages for those routes.
      • Verify there are no issues with user profile access to the apps you are attempting to deploy.
      • If all the options appear correct, delete the apps folder on your local machine and attempt skuid deploy again. Recreate your apps manually on the destination NLX site.
  • Error executing retrieve plan: Post https://<IP address>/api/v2/metadata/retrieve: dial tcp <IP address>: i/o timeout
    • This error indicates an issue retrieving metadata from a data service. Verify the URLs/IP addresses of all data services listed in Configure > Data Sources > Data Services are correct, and ensure that they all can respond to Skuid’s metadata requests.

skuid vs skuid-grunt

skuid-grunt previously provided the above-documented push/pull functionality as a Grunt plugin. While great for projects already using NodeJS and Grunt, the plugin was problematic if you didn’t want to require those dependencies. skuid solves that dependency problem by producing a self-contained CLI to perform all the same operations.