{"id":50971887,"url":"https://github.com/workato-devs/wk","last_synced_at":"2026-06-19T03:01:24.203Z","repository":{"id":354279503,"uuid":"1160487720","full_name":"workato-devs/wk","owner":"workato-devs","description":"Fast, single-binary CLI (Go) for managing Workato recipes, connections, and workspaces. Pull, push, diff, and validate from your terminal. Extensible via plugins — linters, recipe skills, custom workflows.","archived":false,"fork":false,"pushed_at":"2026-06-18T05:37:50.000Z","size":3690,"stargazers_count":2,"open_issues_count":7,"forks_count":0,"subscribers_count":2,"default_branch":"develop","last_synced_at":"2026-06-18T07:26:00.820Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/workato-devs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-18T02:04:38.000Z","updated_at":"2026-06-18T05:33:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/workato-devs/wk","commit_stats":null,"previous_names":["workato-devs/wk-cli-beta","workato-devs/wk"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/workato-devs/wk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workato-devs%2Fwk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workato-devs%2Fwk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workato-devs%2Fwk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workato-devs%2Fwk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/workato-devs","download_url":"https://codeload.github.com/workato-devs/wk/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/workato-devs%2Fwk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34491501,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-18T02:00:06.871Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-19T03:01:22.956Z","updated_at":"2026-06-19T03:01:24.193Z","avatar_url":"https://github.com/workato-devs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# wk\n\nThe CLI component of the [Workato Labs](https://github.com/workato-devs/labs) toolkit — workspace operations, recipe sync, and plugin system. See the Labs README for the full toolkit overview.\n\n## Install\n\nInstall with a package manager — this is the supported path and keeps `wk` up to date.\n\n**macOS / Linux (Homebrew):**\n\n```sh\nbrew install workato-devs/tap/wk\n```\n\n**Windows (Scoop):**\n\n```sh\nscoop bucket add workato https://github.com/workato-devs/scoop-bucket\nscoop install workato/wk\n```\n\nUpgrade later with `brew upgrade wk` or `scoop update wk`.\n\n\u003e Go developers can `go install github.com/workato-devs/wk@latest`, but Homebrew\n\u003e and Scoop are the recommended channels. Pre-built binaries are attached to each\n\u003e [GitHub Release](https://github.com/workato-devs/wk/releases) and feed the\n\u003e Homebrew/Scoop packages — you don't need to download them manually.\n\n## Getting started\n\n### Authenticate\n\nBefore you can use the CLI, you need a Workato API token. Creating one\nrequires several steps in the Workato UI:\n\n1. **Create a Client Role** — go to **Workspace admin \u003e API clients \u003e Client\n   roles** and create a role with the permissions you need (projects,\n   connections, recipes, lifecycle management, etc.)\n2. **Create an API Client** — go to **Workspace admin \u003e API clients**, create\n   a client, assign the role, and specify environment/project access\n3. **Copy the token** — the token (starts with `wrk`) is shown once at\n   creation time\n\nSee the [Workato docs on API clients](https://docs.workato.com/en/platform-cli.html#authentication)\nfor the full walkthrough.\n\nOnce you have a token, create an auth profile:\n\n```sh\nwk auth login --token \u003cyour-token\u003e --environment prod\n```\n\n`--token` and `--environment` are required — they can't be introspected.\nEverything else (workspace name, workspace ID, email) is pulled from\n`GET /users/me` after the token is validated. The profile name is\nauto-computed as `\u003cregion\u003e-\u003cworkspace-slug\u003e-\u003cenvironment\u003e`.\n\nThe region defaults to `us`. Pass `--region` to override:\n\n```sh\nwk auth login --token \u003cyour-token\u003e --environment prod --region eu\n```\n\nValid regions: `us`, `eu`, `jp`, `au`, `sg`, `il`, `cn`, `trial` (Developer Sandbox).\n\n```sh\nwk auth list               # show all profiles\nwk auth switch \u003cprofile\u003e   # change active profile\nwk auth status             # verify connectivity\n```\n\nCredentials are stored in the system keychain by default. For CI/CD, use\n`--store-type file` to write a `profiles.env` credential file instead. See\n[docs/ci-setup.md](./docs/ci-setup.md) for non-interactive flag requirements\nand example pipelines.\n\n### New project (greenfield)\n\n```sh\nwk init --project \"Marketing Recipes\" --project \"Sales Recipes\"\n```\n\nThis creates a `wk` project container with a `.wk/` directory for CLI state and scaffolds local directories for each declared Workato project. The project name is derived from your active auth profile as `\u003cregion\u003e-\u003cworkspace-slug\u003e-\u003cenvironment\u003e`, keeping your project directory, auth profile, and workspace aligned automatically. Override with `--name` if needed.\n\nAfter init, the directory looks like this:\n\n```\nus-acme-corp-prod/\n├── .wk/                          # CLI state (gitignored)\n│   ├── wk.toml                   # project config\n│   └── .gitignore\n├── Marketing Recipes/            # local directory for this Workato project\n└── Sales Recipes/                # local directory for this Workato project\n```\n\nPull to sync server content down to your local directories:\n\n```sh\ncd us-acme-corp-prod\nwk pull\n```\n\nAfter pull, `.wk/` mirrors the asset tree with `.meta.json` sidecar files\nthat track each asset's server-side identity and content hash. These power\n`wk status` and `wk diff`:\n\n```\nus-acme-corp-prod/\n├── .wk/\n│   ├── wk.toml\n│   ├── .gitignore\n│   ├── Marketing Recipes/\n│   │   └── welcome-email.recipe.json.meta.json\n│   └── Sales Recipes/\n│       └── lead-sync.recipe.json.meta.json\n├── Marketing Recipes/\n│   └── welcome-email.recipe.json\n└── Sales Recipes/\n    └── lead-sync.recipe.json\n```\n\n```sh\nwk status        # show what's changed locally vs. last pull\nwk diff          # show content differences between local and remote\nwk push          # push local changes to remote workspace\n```\n\n### Existing project (rehydration)\n\nIf you already have a local `wk` project layout, use `init --verify` to register it against a workspace:\n\n```sh\nwk init --projects-dir us-acme-corp-prod --verify\n```\n\n`--projects-dir` registers each immediate subdirectory of `us-acme-corp-prod` as a sync entry in `wk.toml`. `--verify` confirms each entry exists on the server and caches the resolved folder/project IDs.\n\nThen pull to hydrate your local directories with the server's current state:\n\n```sh\ncd us-acme-corp-prod\nwk pull\n```\n\nFrom here the workflow is the same — edit, status, diff, push.\n\n## Commands\n\nThe CLI covers auth, recipes, connections, folders, tags, API Platform,\nMCP, workspace management, sync, and plugins. Every command supports\n`--json` for scripting and `--help` for usage details.\n\nSee [docs/command-reference.md](./docs/command-reference.md) for the full\ncommand tree and global flags.\n\n## Project config\n\nAn auth profile maps to an environment/workspace/region tuple. A project's\n`wk.toml` declares which workspace it targets and what to sync.\n\n```mermaid\nflowchart TD\n    R[\"Region: us\"] --\u003e W[\"Workspace: acme-corp\"]\n    W --\u003e E[\"Environment: prod\"]\n\n    subgraph \"Auth Profile\"\n        P[\"Profile: us-acme-corp-prod\u003cbr/\u003e(token scoped to this tuple)\"]\n    end\n\n    P -.-\u003e E\n\n    subgraph \"Project (.wk/wk.toml)\"\n        T[\"wk.toml\"]\n        T --\u003e S1[\"[[sync]] Marketing Recipes → ./marketing\"]\n        T --\u003e S2[\"[[sync]] Sales Recipes → ./sales\"]\n    end\n\n    P -.-\u003e|\"--profile or active\"| T\n    S1 --\u003e|\"push / pull\"| E\n    S2 --\u003e|\"push / pull\"| E\n```\n\nEvery `wk` project is defined by a `.wk/wk.toml` file. The CLI walks up from\nthe current directory to find it.\n\n```toml\nname = \"us-acme-corp-prod\"\ndescription = \"Production workspace recipes\"\nworkspace = \"acme-corp\"\nplugins = [\"recipe-lint\"]\n\n[[sync]]\nserver_path = \"/Marketing Recipes\"\nlocal_path = \"./Marketing Recipes\"\nfolder_id = 12345\nproject_id = 678\n\n[[sync]]\nserver_path = \"/Sales Recipes\"\nlocal_path = \"./Sales Recipes\"\nfolder_id = 12346\nproject_id = 679\n```\n\n| Field | Required | Purpose |\n|---|---|---|\n| `name` | yes | Project name (also the container directory name) |\n| `workspace` | yes | Workspace identifier (matches auth profile) |\n| `description` | no | Human-readable description |\n| `plugins` | no | List of plugins to load |\n| `[[sync]]` | yes | Array of server-path-to-local-path mappings |\n| `server_path` | yes | Workato folder path on the server |\n| `local_path` | yes | Local directory to sync into |\n| `folder_id` | no | Cached Workato folder ID — populated by `--verify` or on first sync, avoids repeated folder-hierarchy API walks. Use `wk sync refresh` to re-resolve. |\n| `project_id` | no | Cached Workato project ID — present only when the folder is a Workato project. Required for project-level operations (`folders delete` on projects). Zero/absent for plain folders. |\n| `include` | no | Glob filter for which files to sync |\n\n## Plugin system\n\nPlugins extend `wk` with additional commands via JSON-RPC. A plugin is a\ndirectory containing a `plugin.toml` manifest and a Go binary entrypoint.\nThe linter (`recipe-lint`) is the primary plugin.\n\n```sh\nwk plugins install ./recipe-lint     # install from a local directory\nwk plugins list                      # list installed plugins\nwk plugins remove \u003cname\u003e             # remove a plugin\n```\n\n### Plugin manifest format\n\n```toml\nname = \"recipe-lint\"\nversion = \"0.1.0\"\ndescription = \"Tiered recipe validation for Workato\"\nentrypoint = \"./recipe-lint\"\n\n[[commands]]\nname = \"lint\"\ndescription = \"Validate recipe files\"\nmethod = \"lint.run\"\n```\n\n## Working safely\n\n**The CLI can modify your Workato workspace.** Commands like `push`, `recipes\nstart`, `recipes stop`, `recipes delete`, `connections delete`, and `folders\ndelete` make real changes. We recommend working in a Developer Sandbox or\nnon-production workspace.\n\nThe CLI includes a workspace isolation check (`wk.toml` workspace vs. active\nprofile) that prevents accidental cross-workspace operations, but it is not a\nsubstitute for environment discipline.\n\n## Current limitations\n\nThese are tracked in the [ROADMAP](./docs/ROADMAP.md) but are not yet available:\n\n- **Auth Tier 1** — external secrets-manager backends (Vault, AWS Secrets Manager, Doppler)\n- **Auth Tier 4** — encrypted file-based credential store\n- **`wk auth rotate`** — credential rotation\n- **`wk migrate`** — automated migration from the legacy Python CLI\n- **`--toml` output format** — `--json` and text tables are supported\n- **`--no-color`** — accepted on all commands but currently a no-op\n\n## Development (CLI internals only)\n\nThis section is for contributors working on the `wk` CLI itself. If you're\nusing `wk` to build and deploy Workato recipes, you can stop reading here.\n\n### Make targets\n\n```sh\nmake build     # build to ./bin/wk\nmake test      # run all tests\nmake lint      # golangci-lint\nmake fmt       # gofmt\nmake tidy      # go mod tidy\nmake clean     # remove ./bin/\nmake install   # build + copy to $GOPATH/bin\n```\n\n### Project structure\n\n```\ncmd/wk/              Entry point (main.go)\ninternal/\n  commands/          Cobra command definitions and RunContext\n  api/               Workato API client\n  auth/              Credential storage, profiles, regions\n  config/            wk.toml parsing and project root discovery\n  sync/              Pull/push sync logic\n  plugin/            Plugin loading and JSON-RPC dispatch\n  output/            Text and JSON formatters\n  errors/            Structured error types\nplugins/             Bundled plugin examples\n```\n\n### Release\n\nReleases are built with [GoReleaser](https://goreleaser.com/). Cross-compiled\nbinaries are produced for linux, darwin, and windows on amd64 and arm64.\n\n```sh\ngoreleaser release --snapshot --clean\n```\n\n## License\n\nSee [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkato-devs%2Fwk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fworkato-devs%2Fwk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fworkato-devs%2Fwk/lists"}