Help us improve
Share bugs, ideas, or general feedback.
Workato Connector SDK CLI reference (Ruby gem workato-connector-sdk). Use when the user asks about "workato gem", "workato-connector-sdk", "run connector locally", "rspec test", "write connector tests", "vcr cassettes", "connector_spec", "workato exec", "workato push", "workato new connector", "workato generate schema", or needs to develop, test, or debug Workato custom connectors locally with the Ruby CLI. NOT the Platform CLI (Python) for workspace management — use workato-platform-cli for that.
npx claudepluginhub grailautomation/claude-plugins --plugin workato-connector-sdkHow this skill is triggered — by the user, by Claude, or both
Slash command
/workato-connector-sdk:workato-connector-sdk-cliThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide for using the Workato Connector SDK CLI gem to develop, test, and deploy custom connectors locally.
references/cli.mdreferences/cli__guides__cli__actions.mdreferences/cli__guides__cli__download-streaming-actions.mdreferences/cli__guides__cli__methods.mdreferences/cli__guides__cli__multistep-actions.mdreferences/cli__guides__cli__pick_lists.mdreferences/cli__guides__cli__test.mdreferences/cli__guides__cli__triggers.mdreferences/cli__guides__cli__upload-streaming-actions.mdreferences/cli__guides__getting-started.mdreferences/cli__guides__rspec__connector_spec.mdreferences/cli__guides__rspec__enable-ci-cd-on-github.mdreferences/cli__guides__rspec__file_streaming.mdreferences/cli__guides__rspec__vcr.mdreferences/cli__guides__rspec__writing_tests.mdreferences/cli__guides__security-guidelines.mdreferences/cli__guides__troubleshooting.mdreferences/cli__reference__cli-commands.mdreferences/cli__reference__cli-project-directory-reference.mdreferences/cli__reference__rspec-commands.mdCreates, debugs, and modifies data integration workflows using the versori-run SDK. Manages deployments, connections, and logs via the Versori CLI.
Documents the Airbyte per-connector typed SDK packages: public API, connector discovery, PydanticAI patterns, and Anthropic SDK integration.
Guides building and deploying Atlassian Forge Teamwork Graph connector apps that ingest external data into Rovo Search and Chat. Use for building graph:connector modules or connecting third-party tools.
Share bugs, ideas, or general feedback.
Guide for using the Workato Connector SDK CLI gem to develop, test, and deploy custom connectors locally.
Note: This skill covers the Connector SDK CLI (Ruby gem
workato-connector-sdk). For the Platform CLI (Python packageworkato-platform-clifor managing workspace recipes, connections, and projects), see theworkato-platform-cliplugin.
The Workato SDK CLI (workato-connector-sdk gem) enables local connector development with:
gem install workato-connector-sdk
Requirements: Ruby 2.7+, Bundler
A standard connector project:
my-connector/
├── connector.rb # Main connector code
├── settings.yaml # Connection credentials (gitignored)
├── settings.yaml.enc # Encrypted credentials
├── master.key # Encryption key (gitignored)
├── Gemfile
└── spec/
├── connector_spec.rb
└── cassettes/ # VCR recordings
workato new my_connector
Creates project scaffold with connector.rb, Gemfile, and spec structure.
# Execute an action
workato exec actions.search_records --input='{"query": "test"}'
# Execute a trigger
workato exec triggers.new_record --input='{"since": "2024-01-01"}'
# With settings file
workato exec actions.create_record --settings=settings.yaml --input='{"name": "Test"}'
workato exec connection.authorization --settings=settings.yaml
workato push --title="My Connector" --api-token=YOUR_TOKEN
workato pull --connector-id=12345 --api-token=YOUR_TOKEN
RSpec.describe 'connector', :vcr do
let(:connector) { Workato::Connector::Sdk::Connector.from_file('connector.rb') }
let(:settings) { Workato::Connector::Sdk::Settings.from_file('settings.yaml') }
describe 'connection' do
it 'tests successfully' do
result = connector.connection.authorization(settings)
expect(result).to be_truthy
end
end
describe 'actions' do
describe 'search_records' do
it 'returns results' do
input = { query: 'test' }
result = connector.actions.search_records.execute(settings, input)
expect(result[:records]).to be_an(Array)
end
end
end
end
# Run all tests
bundle exec rspec
# Run specific test
bundle exec rspec spec/connector_spec.rb:25
# Run with VCR recording
VCR_RECORD=all bundle exec rspec
VCR records HTTP interactions for deterministic testing:
# spec/spec_helper.rb
require 'vcr'
VCR.configure do |config|
config.cassette_library_dir = 'spec/cassettes'
config.hook_into :webmock
config.filter_sensitive_data('<API_KEY>') { ENV['API_KEY'] }
end
| Mode | Behavior |
|---|---|
none | Only replay, fail if no cassette |
once | Record once, then replay |
new_episodes | Record new requests, replay existing |
all | Always record fresh |
it 'fetches records', :vcr do
# First run: records API call
# Subsequent runs: replays from cassette
result = connector.actions.get_records.execute(settings, {})
expect(result).to include(:records)
end
# Generate master key and encrypt settings
workato generate_key
workato encrypt settings.yaml
Creates settings.yaml.enc (safe to commit) and master.key (gitignore).
# settings.yaml
api_key: your-api-key
subdomain: your-subdomain
environment: sandbox
export WORKATO_API_KEY=your-key
workato exec actions.test --settings-from-env
workato exec actions.search --verbose
it 'debugs action' do
result = connector.actions.my_action.execute(settings, input)
pp result # Pretty print result
binding.pry # Drop into debugger
end
Connection fails locally but works in Workato:
VCR cassette mismatch:
rm spec/cassettes/my_test.ymlAction returns nil:
execute block returns a hashafter_response in HTTP callsname: Test Connector
on: [push, pull_request]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: ruby/setup-ruby@v1
with:
ruby-version: '3.1'
bundler-cache: true
- run: bundle exec rspec
Store master.key as GitHub secret, create during CI:
- name: Setup credentials
run: echo "${{ secrets.MASTER_KEY }}" > master.key
For detailed documentation, consult the reference files:
references/cli.md - CLI overview and installationreferences/cli__guides__getting-started.md - Getting started guidereferences/cli__guides__cli__actions.md - Testing actions locallyreferences/cli__guides__cli__triggers.md - Testing triggers locallyreferences/cli__guides__cli__methods.md - Testing methodsreferences/cli__guides__cli__pick_lists.md - Testing pick listsreferences/cli__guides__cli__test.md - Test command referencereferences/cli__guides__cli__multistep-actions.md - Multistep action testingreferences/cli__guides__cli__download-streaming-actions.md - Download streamingreferences/cli__guides__cli__upload-streaming-actions.md - Upload streamingreferences/cli__guides__rspec__writing_tests.md - Writing RSpec testsreferences/cli__guides__rspec__connector_spec.md - Connector spec patternsreferences/cli__guides__rspec__vcr.md - VCR cassette configurationreferences/cli__guides__rspec__file_streaming.md - File streaming testsreferences/cli__guides__rspec__enable-ci-cd-on-github.md - CI/CD setupreferences/cli__reference__cli-commands.md - Complete CLI command referencereferences/cli__reference__cli-project-directory-reference.md - Project structurereferences/cli__reference__rspec-commands.md - RSpec command referencereferences/cli__guides__security-guidelines.md - Security best practicesreferences/cli__guides__troubleshooting.md - Troubleshooting guide