workato-developer

name	workato-developer
description	Workato developer using Platform CLI. Use when working with Workato locally.

Workato Platform CLI Developer Guide

Overview

The Workato Platform CLI is a modern, type-safe command-line interface for the Workato API. It enables developers to build, validate, and manage Workato recipes, connections, and projects locally with version control integration.

System Requirements

• Python 3.12 or later
• uv package manager (preferred over pip)
• Valid Workato account with API token
• Network access to Workato API endpoints
• Recommended: Git for version control

Installation

uv add workato-platform-cli
workato --version

Note: Always ensure the virtual environment is activated before running CLI commands:

source ~/.zshrc

Authentication Setup

1. Create a Client Role

Navigate to Workspace admin > API clients > Client roles and create a role with these permissions:

Projects tab (all selected):

• Projects & folders
• Connections
• Recipes
• Recipe versions
• Lifecycle management
• Export manifests

Tools tab:

• Collections & endpoints operations (list, create, enable/disable)

Admin tab:

• Workspace details (all selected)

2. Create an API Client

1. Go to Workspace admin > API clients
2. Select Create API client
3. Assign your client role
4. Configure environment and project access
5. Set allowed IPs if needed
6. Copy and save your API token immediately (begins with wrk, e.g., wrkprod-...)

3. Initialize the CLI

workato init

This guides you through:

1. Profile name (default or custom)
2. Data center region selection
3. API token entry
4. Project selection

Verify with:

workato workspace

Environment Variables

• WORKATO_PROFILE - Active profile name
• WORKATO_API_TOKEN - API token for authentication
• WORKATO_API_HOST - API endpoint host

---

CLI Command Reference

Global Options

Option	Description
--profile TEXT	Specifies authentication profile
--version	Shows CLI version
--help	Displays available commands
--output-format	Output as table (default) or JSON

Pagination Options (where applicable)

Option	Description
--page INTEGER	Page number (min 1)
--per-page INTEGER	Results per page (max 100)

---

Initialization & Workspace

workato init

Sets up authentication, region selection, and project configuration.

workato workspace

Displays current workspace information and connection status.

workato pull

Synchronizes recipes, connections, and data tables from workspace to local directory.

workato pull

workato push

Uploads local modifications to workspace with optional recipe restart.

workato push

---

Profile Management

Local Profile Storage

Workato CLI profiles are stored in ~/.workato/profiles as a JSON file:

{
  "current_profile": "agent-workato-demo",
  "profiles": {
    "default": {
      "region": "trial",
      "region_url": "https://app.trial.workato.com",
      "workspace_id": 2100003058
    },
    "production": {
      "region": "us",
      "region_url": "https://app.workato.com",
      "workspace_id": 1234567890
    }
  }
}

Field	Description
current_profile	Name of the active profile
profiles	Map of profile name to configuration
region	Data center region (trial, us, eu, jp, sg)
region_url	API endpoint URL
workspace_id	Workato workspace identifier

workato profiles list

Shows all configured authentication profiles.

workato profiles use <NAME>

Switches active profile for subsequent operations.

workato profiles use production

workato profiles status

Displays currently active profile with configuration details.

workato profiles delete <NAME>

Removes a profile from configuration.

---

Project Management

workato projects list

Enumerates available projects in workspace.

workato projects use <NAME>

Changes active project context.

workato projects use "Enterprise Second Brain"

---

Recipe Operations

workato recipes list

Lists recipes with filtering options.

workato recipes list
workato recipes list --folder "subfolder"
workato recipes list --status running

workato recipes validate --path <FILE>

Checks JSON syntax and schema compliance locally.

workato recipes validate --path ./recipes/my_recipe.recipe.json

workato recipes start

Enables stopped recipes by ID or name.

workato recipes start --name "My Recipe"
workato recipes start --id 12345

workato recipes stop

Halts running recipes by ID or name.

workato recipes stop --name "My Recipe"

workato recipes update-connection

Modifies connector credentials in stopped recipes.

workato recipes jobs

Shows recipe execution history.

workato recipes jobs --name "My Recipe"

---

Connection Management

workato connections list

Shows all connections with provider filtering.

workato connections list
workato connections list --provider slack

workato connections create

Establishes new connections with authentication details.

workato connections create-oauth

Initiates OAuth authentication flow.

workato connections get-oauth-url

Generates OAuth authorization URL.

workato connections update

Modifies connection properties.

workato connections pick-list

Retrieves dynamic field values from connections.

---

Connector Information

workato connectors list

Displays available standard and custom connectors.

workato connectors parameters

Shows authentication requirements and configuration fields.

---

Data Tables & Properties

workato data-tables list

Enumerates data tables with schema information.

workato data-tables create

Creates structured data storage with defined schema.

workato properties list

Lists environment or project-level configuration variables.

workato properties upsert

Creates or updates configuration properties.

workato properties upsert --file properties.json

---

API Management

workato api-collections list

Shows recipe endpoint groupings.

workato api-collections create

Establishes new endpoint collections.

workato api-collections list-endpoints

Displays endpoints within a collection.

workato api-collections enable-endpoint

Activates specific API endpoints.

workato api-clients list

Shows programmatic access clients.

workato api-clients create

Establishes new API clients with credentials.

---

Documentation & Assets

workato guide topics

Lists available help documentation sections.

workato guide search <QUERY>

Searches documentation by keywords.

workato guide content <TOPIC>

Displays full documentation for specific topics.

workato assets

Comprehensive listing of all workspace assets with types and locations.

---

Local JSON File Structures

Recipe JSON Structure (*.recipe.json)

Recipe files define automation workflows with triggers, actions, and logic.

{
  "name": "Recipe Name",
  "description": "Recipe description",
  "version": 1,
  "private": false,
  "concurrency": 1,
  "code": {
    "number": 0,
    "provider": "connector_name",
    "name": "trigger_or_action_name",
    "as": "unique_step_id",
    "keyword": "trigger",
    "input": { },
    "block": [ ]
  },
  "config": [ ]
}

Top-Level Properties

Property	Type	Description
name	string	Display name of the recipe
description	string	Recipe description
version	integer	Recipe version number
private	boolean	Whether recipe is private
concurrency	integer	Max concurrent executions
code	object	Recipe logic (trigger + steps)
config	array	Connection configurations

Code Block Structure

Each step in a recipe follows this structure:

{
  "number": 0,
  "provider": "slack",
  "name": "new_event",
  "as": "91503a3a",
  "keyword": "trigger",
  "input": { },
  "filter": { },
  "block": [ ],
  "extended_input_schema": [ ],
  "extended_output_schema": [ ],
  "uuid": "unique-uuid"
}

Step Keywords

Keyword	Description
trigger	Recipe trigger (entry point)
action	Connector action
if	Conditional branch
try	Error handling block
catch	Error catch block
stop	Stop recipe execution

Data Pills (Dynamic Values)

Data pills reference output from previous steps using the _dp() function:

"#{_dp('{\"pill_type\":\"output\",\"provider\":\"slack\",\"line\":\"91503a3a\",\"path\":[\"event\",\"text\"]}')}"

Components:

• pill_type: Always "output"
• provider: Connector name
• line: Step ID (as value)
• path: Array path to the field

Formula Mode

Prefix with = for formula mode (Ruby expressions):

"message": "=\"Hello \" + _dp('{...}')"

Filter/Condition Structure

{
  "filter": {
    "conditions": [
      {
        "operand": "equals_to",
        "lhs": "#{_dp('...')}",
        "rhs": "value",
        "uuid": "condition-uuid"
      }
    ],
    "operand": "and",
    "type": "compound"
  }
}

Operand types: equals_to, present, not_equals_to, contains, starts_with, ends_with, greater_than, less_than

Recipe Function (Callable Recipe)

Trigger for callable recipes:

{
  "provider": "workato_recipe_function",
  "name": "execute",
  "keyword": "trigger",
  "input": {
    "parameters_schema_json": "[{\"control_type\":\"text\",\"label\":\"Message\",\"type\":\"string\",\"name\":\"message\"}]",
    "result_schema_json": "[{\"name\":\"result\",\"type\":\"string\"}]"
  }
}

Calling Another Recipe

{
  "provider": "workato_recipe_function",
  "name": "call_recipe",
  "keyword": "action",
  "input": {
    "flow_id": {
      "zip_name": "other_recipe.recipe.json",
      "name": "Other Recipe",
      "folder": ""
    },
    "parameters": {
      "param1": "value"
    }
  }
}

Return Result

{
  "provider": "workato_recipe_function",
  "name": "return_result",
  "keyword": "action",
  "input": {
    "result": {
      "field1": "#{_dp('...')}"
    }
  }
}

Config Section

Defines connections used by the recipe:

{
  "config": [
    {
      "keyword": "application",
      "provider": "slack",
      "skip_validation": false,
      "account_id": {
        "zip_name": "myslackworkspace.connection.json",
        "name": "MySlackWorkspace",
        "folder": ""
      }
    },
    {
      "keyword": "application",
      "provider": "logger",
      "skip_validation": false,
      "account_id": null
    }
  ]
}

For custom connectors:

{
  "account_id": {
    "zip_name": "myconnection.connection.json",
    "name": "MyConnection",
    "folder": "",
    "custom": true
  }
}

---

Connection JSON Structure (*.connection.json)

Connection files define authentication to external services.

{
  "name": "MySlackWorkspace",
  "provider": "slack",
  "root_folder": false
}

Property	Type	Description
name	string	Connection display name
provider	string	Connector identifier
root_folder	boolean	Whether in root folder

Note: Actual credentials are not stored in JSON files for security. OAuth connections are managed via CLI commands.

---

Lookup Table Reference

Lookup tables are referenced in recipes with this structure:

{
  "provider": "lookup_table",
  "name": "get_entry",
  "input": {
    "lookup_table_id": {
      "zip_name": "my_table.lookup_table.json",
      "name": "my_table",
      "folder": ""
    },
    "parameters": {
      "col1": "search_value"
    }
  }
}

Actions: get_entry, add_entry, update_entry, delete_entry

---

Schema Definition Structure

Used in extended_input_schema and extended_output_schema:

{
  "control_type": "text",
  "label": "Field Label",
  "name": "field_name",
  "type": "string",
  "optional": false,
  "hint": "Help text",
  "sticky": true
}

Control Types

Type	Description
text	Single-line text input
text-area	Multi-line text input
number	Numeric input
integer	Integer input
select	Dropdown selection
switch	Boolean toggle
schema-designer	Dynamic schema builder

Field Types

Type	Description
string	Text value
integer	Integer number
number	Decimal number
boolean	True/false
object	Nested object with properties
array	List with of or properties
date	Date value
date_time	DateTime value

---

Common Providers

Provider	Description
slack	Slack integration
salesforce	Salesforce CRM
logger	Workato logging
lookup_table	Lookup table operations
workato_recipe_function	Callable recipes
variables	Recipe variables
http	HTTP requests

---

Development Workflow

Typical Workflow

1. Initialize: workato init
2. Pull: workato pull to get current state
3. Edit: Modify recipe JSON files locally
4. Validate: workato recipes validate --path <file>
5. Push: workato push to deploy changes
6. Monitor: workato recipes jobs to check executions

Best Practices

Project Organization

• Group recipes by business function
• Use descriptive connection names
• Implement consistent tagging
• Conduct regular maintenance reviews

Version Control

• Commit after each logical change
• Use meaningful commit messages
• Review diffs before pushing

Multi-Environment

• Use separate profiles per environment
• workato profiles use dev
• workato profiles use production

---

Troubleshooting

Python Version Error

"Python 3.12+ required"

Update Python and verify: python --version

Command Not Found

uv show workato-platform-cli
python -m workato_platform.cli.main --help

API Credentials Error

"Could not resolve API credentials"

Run workato init and enter your API token.

Validation Errors

Check JSON syntax and ensure all referenced connections exist.

---

Quick Reference

# Setup
uv add workato-platform-cli
workato init
workato workspace

# Daily workflow
workato pull
# ... edit files ...
workato recipes validate --path ./recipe.recipe.json
workato push

# Management
workato recipes list
workato recipes start --name "Recipe Name"
workato recipes stop --name "Recipe Name"
workato connections list
workato profiles use production