workato-dev-api 1.2.0 → 1.2.1

package/README.md

@@ -1,8 +1,29 @@
 # workato-dev-api
 
-A zero-dependency CLI for the [Workato Developer API](https://docs.workato.com/workato-api.html). Read and edit recipes, connections, data tables, projects, folders, and jobs from your terminal.
+Zero-dependency CLI and SDK for the [Workato Developer API](https://docs.workato.com/workato-api.html). Built for use with AI coding assistants and programmatic tooling — read and write recipes, connections, data tables, projects, folders, and jobs.
 
-## Install
+---
+
+## Claude Code / Cursor / Windsurf / ...
+
+In a clean working directory, run these two commands once before opening your AI assistant:
+
+```sh
+npx workato-dev-api auth YOUR_API_TOKEN
+npx workato-dev-api bootstrap
+```
+
+The first saves your token to `.env`. The second drops a `CLAUDE.md` into the directory — picked up automatically by Claude Code, Cursor, Windsurf, and other assistants that support project context files — giving it full Workato context: recipe structure, wiring syntax, data table column naming, and how to use this CLI.
+
+Then open your assistant in that directory and start working.
+
+> **Workato free sandbox?** Just tell your assistant — it will update your `package.json` automatically so the CLI points at the right URL.
+
+---
+
+## SDK / CLI Reference
+
+### Install
 
 ```sh
 npm install -g workato-dev-api
@@ -14,44 +35,42 @@ Or use without installing:
 npx workato-dev-api <command>
 ```
 
-## Authentication
+### Authentication
 
-Set `WORKATO_API_TOKEN` in a `.env` file. The CLI checks these locations in order, with **later files winning**:
-
-1. `<package-dir>/.env` — lowest priority (rarely used)
-2. `~/.env` — your home directory default
-3. `./.env` (cwd) — **highest priority**, project-specific override
+Set `WORKATO_API_TOKEN` in a `.env` file, or run:
 
 ```sh
-# .env
-WORKATO_API_TOKEN=your_token_here
+workato auth YOUR_API_TOKEN
 ```
 
-You can also export it directly in your shell environment.
+The CLI checks `.env` files in this order, with later files winning:
 
-## Claude Code setup
+1. `<package-dir>/.env`
+2. `~/.env`
+3. `./.env` (cwd) — highest priority
 
-In a clean working directory, run these two commands once before starting Claude Code:
+### Sandbox configuration
 
-```sh
-npx workato-dev-api auth YOUR_API_TOKEN
-npx workato-dev-api bootstrap-claude
-```
+By default the CLI targets `app.workato.com`. For a Workato free sandbox (trial account), set in your `package.json`:
 
-That's it. The first command saves your token to `.env`. The second drops a `CLAUDE.md` into the directory so Claude Code automatically has full context — recipe structure, wiring syntax, data table column names, and project reference IDs.
+```json
+{
+  "workato": { "sandbox": true }
+}
+```
 
-Then open Claude Code in that directory and start working. If you're on a **Workato free sandbox**, just tell Claude — it will update your `package.json` automatically so the CLI points at the right URL.
+This switches the base URL to `app.trial.workato.com`.
 
-## Commands
+### Commands
 
-### Setup
+#### Setup
 
 | Command | Description |
 |---|---|
-| `workato bootstrap-claude` | Copy `CLAUDE.md` into the current directory |
-| `workato auth <token>` | Save your API token to `.env` in the current directory |
+| `workato auth <token>` | Save API token to `.env` in the current directory |
+| `workato bootstrap` | Copy `CLAUDE.md` into the current directory |
 
-### Read
+#### Read
 
 | Command | Description |
 |---|---|
@@ -65,7 +84,7 @@ Then open Claude Code in that directory and start working. If you're on a **Work
 | `workato get-jobs <recipe_id>` | List recent jobs. Filters: `--limit <n>`, `--status <status>` |
 | `workato get-job <recipe_id> <job_id>` | Fetch a single job |
 
-### Write
+#### Write
 
 | Command | Description |
 |---|---|
@@ -77,48 +96,19 @@ Then open Claude Code in that directory and start working. If you're on a **Work
 | `workato stop <recipe_id>` | Stop a recipe |
 | `workato delete <recipe_id>` | Delete a recipe |
 
-## Examples
-
-```sh
-# Fetch recipe code and save to file
-workato get 167603
-
-# List all recipes in a project
-workato list-recipes --project 14318
-
-# List jobs that failed
-workato get-jobs 167603 --limit 20 --status failed
-
-# Start a recipe
-workato start 167603
-
-# Patch a single step's input fields
-cat > patch.json <<'EOF'
-{
-  "input": {
-    "language": "fr"
-  }
-}
-EOF
-workato update-step 167603 5df21cfd patch.json
-
-# Replace entire recipe code
-workato put-code 167603 recipe_167603_code.json
-```
-
-## Recipe code structure
+### Recipe code structure
 
 A recipe's code is a JSON object. The top-level object is the **trigger** step; action steps live in `code.block[]`. Each step has a unique `as` field (8-char hex) used for cross-step wiring (datapills).
 
-`workato get <id>` saves the code to `recipe_<id>_code.json` so you can inspect and edit it before pushing back with `put-code`.
+`workato get <id>` saves the code to `recipe_<id>_code.json` for inspection and editing before pushing back with `put-code`.
 
-## Development
+### Development
 
 ```sh
-git clone ...
+git clone https://github.com/bill-bishop/workato-dev-api
 cd workato-dev-api
 cp .env.example .env   # add your token
-npm test               # runs 88 unit tests, no network required
+npm test               # 110 unit tests, no network required
 ```
 
 Tests use Node's built-in `node:test` runner — no extra dependencies.

package/cli.js

@@ -5,7 +5,7 @@ const os = require('os');
 const path = require('path');
 const {
   loadEnv, setConfig, resolveBaseUrl, readProjectConfig,
-  cmdBootstrapClaude, cmdAuth,
+  cmdBootstrap, cmdAuth,
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,
   cmdGetJobs, cmdGetJob,
@@ -15,8 +15,8 @@ const {
 
 // Setup commands run before env/token setup
 const _setupCmd = process.argv[2];
-if (_setupCmd === 'bootstrap-claude') {
-  cmdBootstrapClaude(process.cwd());
+if (_setupCmd === 'bootstrap') {
+  cmdBootstrap(process.cwd());
   process.exit(0);
 }
 if (_setupCmd === 'auth') {
@@ -71,7 +71,7 @@ function usage() {
 workato <command> [options]
 
 Setup:
-  bootstrap-claude                           Copy CLAUDE.md into the current directory
+  bootstrap                                  Copy CLAUDE.md into the current directory
   auth <token>                               Save API token to .env in the current directory
 
 Read commands:

package/lib.js

@@ -160,7 +160,7 @@ function apiTriggerConfig() {
 
 // ── Setup commands ────────────────────────────────────────────────────────────
 
-function cmdBootstrapClaude(destDir) {
+function cmdBootstrap(destDir) {
   const src = path.join(__dirname, 'CLAUDE.md');
   const dest = path.join(destDir ?? process.cwd(), 'CLAUDE.md');
   fs.copyFileSync(src, dest);
@@ -353,7 +353,7 @@ module.exports = {
   findStep, deepMerge, extractCode,
   apiTriggerCode, apiTriggerConfig,
   // setup commands
-  cmdBootstrapClaude, cmdAuth,
+  cmdBootstrap, cmdAuth,
   // read commands
   cmdGet, cmdListRecipes, cmdListProjects, cmdListFolders,
   cmdListConnections, cmdListDataTables, cmdGetDataTable,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "workato-dev-api",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "CLI for the Workato Developer API — recipes, connections, data tables, and more",
   "bin": {
     "workato": "cli.js"

package/test/cli.test.js

@@ -1083,9 +1083,9 @@ describe('readProjectConfig', () => {
   });
 });
 
-// ── cmdBootstrapClaude ────────────────────────────────────────────────────────
+// ── cmdBootstrap ────────────────────────────────────────────────────────
 
-describe('cmdBootstrapClaude', () => {
+describe('cmdBootstrap', () => {
   function tmpDir() {
     const d = path.join(os.tmpdir(), `workato-test-${Date.now()}-${Math.random()}`);
     fs.mkdirSync(d, { recursive: true });
@@ -1095,7 +1095,7 @@ describe('cmdBootstrapClaude', () => {
   test('copies CLAUDE.md into the destination directory', () => {
     const dir = tmpDir();
     try {
-      lib.cmdBootstrapClaude(dir);
+      lib.cmdBootstrap(dir);
       assert.ok(fs.existsSync(path.join(dir, 'CLAUDE.md')), 'CLAUDE.md should exist in dest dir');
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
@@ -1105,7 +1105,7 @@ describe('cmdBootstrapClaude', () => {
   test('written file content matches the source CLAUDE.md', () => {
     const dir = tmpDir();
     try {
-      lib.cmdBootstrapClaude(dir);
+      lib.cmdBootstrap(dir);
       const srcPath = path.join(__dirname, '..', 'CLAUDE.md');
       const src = fs.readFileSync(srcPath, 'utf8');
       const dest = fs.readFileSync(path.join(dir, 'CLAUDE.md'), 'utf8');
@@ -1118,7 +1118,7 @@ describe('cmdBootstrapClaude', () => {
   test('returns the destination file path', () => {
     const dir = tmpDir();
     try {
-      const result = lib.cmdBootstrapClaude(dir);
+      const result = lib.cmdBootstrap(dir);
       assert.equal(result, path.join(dir, 'CLAUDE.md'));
     } finally {
       fs.rmSync(dir, { recursive: true, force: true });
@@ -1129,7 +1129,7 @@ describe('cmdBootstrapClaude', () => {
     const dir = tmpDir();
     try {
       fs.writeFileSync(path.join(dir, 'CLAUDE.md'), 'old content');
-      lib.cmdBootstrapClaude(dir);
+      lib.cmdBootstrap(dir);
       const content = fs.readFileSync(path.join(dir, 'CLAUDE.md'), 'utf8');
       assert.notEqual(content, 'old content');
     } finally {