# CLI Command Reference

Learn more about the commands you can use in CLI after installing the SDK gem.


# workato

Root command of the Workato gem. Synonymous with workato help.

# Usage

$ workato

# Output

Description of commands available in the Workato gem.


# workato edit

Creates or edits an encrypted file.

# Usage

$ workato edit <PATH>

# Input

Input Description
EDITOR The editor you'll use to edit the file. For example: nano
PATH The path to the file that should be created or updated, in dot notation.

# Options

Option Description
--key, -k The path to the encrypt/decrypt key.

If this isn't provided, defaults to master.key.

If a master.key file doesn't exist and no option is provided, a new master.key file is created.

# Result

Encrypted file is created or updated. master.key is created if the file didn't previously exist and an option wasn't provided.

# Example

For Windows:
  $ set EDITOR=notepad
  $ workato edit settings.yaml.enc
For Mac:
  $ EDITOR="nano" workato edit settings.yaml.enc

# workato exec

Executes a specific lambda function in your connector for testing.

# Usage

$ workato exec <PATH> <OPTIONS>

# Input

Input Description
PATH The path to the lambda to execute, in dot notation. For example: actions.search_customers.execute would correspond to the action search_customers and the execute lambda. You may also simulate the entire action with the path actions.search_customers.

# Options

Option Description
-c or --connector The path to the connector.rb file to execute. Defaults to connector.rb if not provided.
-s or --settings The path to the settings.yaml file that stores the credentials. Defaults to settings.yaml.enc, then settings.yaml if not provided.
-n or --connection The connection name in the settings.yaml file. Only required if there are multiple credential sets.
-i or --input The path to the JSON file that stores the input. Used for execute, webhook_notification, or poll lambdas.
--closure The path to the JSON file that stores the closure. Used for poll lambdas to simulate polls after the initial poll.
-a or --args The path to the JSON file that stores arguments for a method or picklists. Used for methods or pick_lists lambdas to simulate their invocation. An error may arise if arguments were expected but not provided.
--extended-input-schema and --extended-output-schema The path to the JSON file that stores the extended_input_schema and extended_output_schema. Used for execute, webhook_notification, or poll lambdas.
--config-fields The path to the JSON file that stores the config_fields data. Used for object_definitions, input_fields, or output_fields lambdas.
--webhook-headers The path to the JSON file(s) that store incoming webhook header data. Used for webhook_notification lambdas.
--webhook-params The path to the JSON files that store incoming webhook parameter data. Used for webhook_notification lambdas.
--webhook-payload The path to the JSON files that store incoming webhook payload data. Used for webhook_notification lambdas.
--webhook-url The path to the file that stores the webhook URL. Used for webhook_subscribe lambdas.
-o or --output The path to the file that saves the output of the lambda function.
--oauth2-code The OAuth2 code used to invoke the acquire lamabda function.
--redirect-url The redirect-url used to invoke the refresh lamabda function.
--refresh-token The refresh-token used to invoke the refresh lamabda function.
--verbose Include this option to make the execution verbose. This means that all HTTP requests and request payloads will be shown. Response bodies won't be shown but can be inspected with byebug.
--debug Include this option to show errors from the entire stackrace, rather than just the last encountered error.

# Result

The output of the lambda function.

# Examples

Invoke a specific method.

$ workato exec methods.sample_method --args='input/sample_method_input.json'

Invoke the test lambda. Connector and settings are all specified.

workato exec test --connector='zoominfo.rb' --settings='settings.yaml' --connection='My Valid Connection' --verbose

Invoke a specific action and pass it inputs.

$ workato exec actions.search_customers.execute --input='input/search_customer_input.json' --verbose

Invoke a specific polling trigger and pass it inputs. This command simulates the trigger paginating through a series of records when can_poll_more is set to true in the closure.

$ workato exec triggers.new_updated_customers.poll --input='input/new_updated_customers_input.json' --verbose

Invoke a specific polling trigger and pass it inputs. Output will be a single page of the poll. This command simulates a single trigger poll and returns only the first page.

$ workato exec triggers.new_updated_customers.poll_page --input='input/new_updated_customers_input.json' --verbose

# workato generate

Executes a specific lambda function in your connector for testing.

# Usage

$ workato generate <SUBCOMMAND>

# Input

Input Description
SUBCOMMAND The specific lambda function to be tested.

# workato help

Displays help for a specified SDK gem command.

# Usage

$ workato help <COMMAND>

# Input

Input Description
COMMAND The command which you want to help displayed for. For example: edit

# Output

Elaborated help for the specified SDK gem command.

# Example

$ workato help edit
Usage:
  workato edit PATH

Options:
  -k, [--key=KEY]                  # Path to file with encrypt/decrypt key. NOTE: key from WORKATO_CONNECTOR_MASTER_KEY has higher priority
      [--verbose], [--no-verbose]  

Edit encrypted file, e.g. settings.yaml.enc

# workato new

Creates a new connector project in your chosen directory.

When you create a new connector project, you will be asked if you want to select secure or simple for your HTTP mocking behaviour:

Please select default HTTP mocking behavior suitable for your project?

1 - secure. Cause an error to be raised for any unknown requests, all request recordings are encrypted.
            To record a new cassette you need set VCR_RECORD_MODE environment variable

            Example: VCR_RECORD_MODE=once bundle exec rspec spec/actions/test_action_spec.rb

2 - simple. Record new interaction if it is a new request, requests are stored as plain text and expose secret tokens.
When you select secure, VCR recordings made for your unit tests are encrypted. This is recommended. You'll need to set your environment variable for VCR_RECORD_MODE as well.

# Usage

$ workato new <PATH>

# Input

Input Description
PATH The path where the connector project should be created.

# Result

Generates a new connector project.

# Example

$ workato new ~/Desktop/my-new-connector

# workato oauth2

TIP

The command workato oauth2 requires SDK Gem version 0.1.2 and above.

Use this to implement the OAuth2 Authorization code grant flow for applicable connectors. Applicable connectors are ones where the connection hash has `type: 'oauth2`. For more information, check out this handy Okta article.

# Usage

$ workato oauth2 <OPTIONS>

# Options

Option Description
-c or --connector The path to the connector source code. Defaults to connector.rb if not provided.
-s or --settings The path to the settings.yaml file that stores the credentials. Defaults to settings.yaml.enc, then settings.yaml if not provided.
-n or --connection The connection name in the settings.yaml file. Only required if there are multiple credential sets.
--key, -k The path to the encrypt/decrypt key.

If this isn't provided, defaults to master.key.

If a master.key file doesn't exist and no option is provided, a new master.key file is created.
--port By default, the SDK Gem spins up a webserver at "http://localhost:45555/oauth/callback" which is used to receive the OAuth callback. Use this option to change the port. i.e. --port='3010' will spin up the webserver at "http://localhost:3010/oauth/callback" This is useful when your OAuth app is configured to a specific redirect uri.
--ip Allows you to override the default ip address. Defaults to "127.0.0.1"
--https, --no-https Allows you to start the webserver with a self-signed certificate. Required in cases where the OAuth App requires a redirect uri with a "https://" prefix.
--verbose Include this option to make the execution verbose. This means that all HTTP requests and request payloads will be shown. Response bodies won't be shown but can be inspected with byebug.

# Result

Emulates the OAuth2 Authorization Code Grant Flow on Workato. Applicable connectors are ones where the connection hash has `type: 'oauth2`. For more information, check out this handy Okta article.

# Example

$ workato oauth2

# workato push

TIP

Prior to version 0.2.0 of the Workato Gem, the workato push command required you to have a target folder in your Workato workspace. The action has been since improved to default to your Workspace's home folder.

Creates a new connector project in your chosen Workato folder.

# Usage

$ workato push <OPTIONS>

# Options

Option Description
--api-email REQUIRED. The API email for the workspace you're pushing the connector to This can be found in the Account settings page of your target workspace. If not provided, the environment variable WORKATO_API_EMAIL will be used.
--api-token REQUIRED. The API email for the workspace you're pushing the connector to This can be found in the Account settings page of your target workspace. If not provided, the environment variable WORKATO_API_TOKEN will be used
--folder The ID of the folder in your Workato workspace where the connector will be pushed. By default, we assume the home folder of your workspace but any folder may be used.

Folder IDs are located in the URL when you're viewing the folder. For example: If the URL is https://app.workato.com/?fid=106070#assets, the folder ID is 106070.
-t or --title The title of your connector. Defaults to the title key in your connector code if not provided.
-d or --description The path to your connector's description, which could be a Markdown or plain text file. Defaults to README.md if not provided.
-l or --logo The link to the png or jpeg of your connector's logo. Defaults to logo.png if not provided.
-n or --notes The version notes attached to this uploaded version.
-c or --connector The path to the connector source code. Defaults to connector.rb if not provided.
--environment The Workato environment to push to. Defaults to app.workato.com if not provided.

# Result

Your connector is pushed to the specified folder of your Workato workspace.

# Example

$ workato push