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

Pagination Options (where applicable)

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
    }
  }
}

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

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

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
}

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

Field Types

Common Providers

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