bytechefhq / bytechefhq/bytechef
[feature]: ByteChef CLI — remote resource management and AI-agent-friendly terminal access
- Dominant language
- Java
- Stars
- 1k
- Forks
- 170
- Avg merge
- 12h 48m
- Merged PRs (30d)
- 124
Description
### Tell us about the problem you're trying to solve
Today, developers and power users interact with ByteChef almost exclusively through the web UI. The only CLI that ships with the project (`cli/cli-app/`) is a Spring Shell app with a single `component init` command — a build-time generator that scaffolds a Java component from an OpenAPI spec. It is not distributed as a standalone binary, doesn't authenticate against a ByteChef instance, and cannot manage runtime resources.
This creates several gaps:
1. **No scripting surface.** Teams can't integrate ByteChef into CI/CD pipelines, GitOps flows, or shell-based automation. Project/workflow deployments are manual UI actions.
2. **No AI-agent access.** Coding agents (Claude Code, Cursor, Codex) have no terminal-level way to create/modify/inspect ByteChef resources the way they can with `git`, `gh`, `gcloud`, or `make-cli`. This is a fast-growing use case for low-code platforms.
3. **No cross-workspace operations.** Bulk actions (export all workflows, sync connections between environments, promote a project from staging to prod) require either clicking through the UI or writing raw REST/GraphQL clients against undocumented endpoints.
4. **Component authoring is unfriendly outside the repo.** Users building embedded integrations or external tooling need a distributable client they can install with one command, not a Gradle subproject they have to build themselves.
Make released [Make CLI](https://help.make.com/the-make-cli-is-now-live) in 2025 covering exactly this space — scenarios, connections, data stores, webhooks, custom apps, organizations, teams. ByteChef should have a comparable developer surface area, positioned around its own domain model (Projects, Workflows, Connections, Data Tables, Components, Workspaces, Environments).
### Describe the solution you'd like
Extend the existing Spring Shell CLI at `cli/cli-app/` into a distributable `bytechef` CLI that authenticates against a ByteChef instance (self-hosted or cloud) and provides full remote resource management, modeled after the Make CLI but mapped onto ByteChef's domain.
#### Framework
Keep the current stack:
- **Spring Shell** (`@Command`, `@Option`) for command definition
- **Spring Boot 4.0.5** as the application runtime
- **Spring `RestClient`** (plus a small GraphQL client) for talking to the ByteChef API on `:9555`
- New commands added as `@Component`-annotated classes registered via `@EnableCommand(...)` in `CliApplication.java`, matching the existing `ComponentCommand` pattern
#### Distribution
A Spring Boot app isn't a one-file binary out of the box, so the build pipeline needs to produce both:
- **GraalVM `native-image` builds** via Spring Boot AOT — one static binary per platform (macOS Intel + Apple Silicon, Linux x86_64 + arm64, Windows x86_64), published to GitHub Releases
- **Homebrew tap** (`brew install bytechefhq/tap/bytechef-cli`) wrapping the native binaries
- **`.deb` package** for Debian/Ubuntu
- **npm wrapper package** (`@bytechef/cli`) that downloads the right native binary on `postinstall` — lets users do `npm install -g @bytechef/cli` and `npx @bytechef/cli ` the same way Make's CLI works, without actually implementing the CLI in Node
- Fallback **fat JAR** for environments where native binaries aren't acceptable (requires JRE 25+)
#### Authentication
Match Make's three-tier credential resolution (per-command flags > env vars > saved credentials):
- `bytechef login` — interactive Spring Shell wizard, stores credentials at `~/.config/bytechef-cli/config.json` (macOS/Linux) or `%APPDATA%\bytechef-cli\config.json` (Windows)
- `bytechef logout` — clears saved credentials
- `bytechef whoami` — prints the active user, workspace, and instance URL
- `BYTECHEF_API_KEY` + `BYTECHEF_INSTANCE_URL` env vars
- `--api-key` + `--instance-url` per-command flags
- Multiple profiles (e.g., `--profile staging`) for users juggling several instances
- API keys issued/managed via the existing workspace settings in the web UI — no new server work beyond exposing the existing token endpoints
#### Global options
- `--output json|table|compact` — format selection for piping into `jq`, scripts, etc.
- `--instance-url` — target a specific ByteChef instance (self-hosted URL or cloud zone)
- `--profile` — named credential set
- `-V, --version`, `-h, --help`
#### Command surface (mapped from Make → ByteChef)
| Make concept | ByteChef equivalent | Proposed commands |
|---|---|---|
| Scenarios | Projects & Workflows | `bytechef project [list\|get\|create\|update\|delete\|publish\|export\|import]`, `bytechef workflow [list\|get\|create\|update\|delete\|run\|test]` |
| Scenario executions | Job executions | `bytechef execution [list\|get\|logs\|cancel\|resume]` |
| Connections | Connections | `bytechef connection [list\|get\|create\|update\|delete\|test]` with visibility flags (`--visibility private\|workspace\|project\|organization`) |
| Data stores | Data tables | `bytechef datatable [list\|get\|create\|delete]`, `bytechef datatable record [list\|get\|create\|update\|delete]` |
| Webhooks | Webhook triggers | `bytechef webhook [list\|get\|create\|delete\|enable\|disable]` |
| Custom apps | Components | `bytechef component init` (keep existing), `bytechef component [list\|validate\|publish\|test]`, `bytechef component action [list\|test]`, `bytechef component trigger [list\|test]` |
| Teams / Organizations | Workspaces / Environments | `bytechef workspace [list\|get\|switch]`, `bytechef environment [list\|switch]` |
| Incomplete executions | Suspended/failed jobs | `bytechef execution resume `, `bytechef execution retry ` |
| Custom functions | Custom code (Java/JS/Python/Ruby via GraalVM Polyglot) | `bytechef function [create\|test\|deploy]` |
ByteChef-specific additions not present in Make CLI:
- `bytechef copilot ` — terminal access to the AI Copilot for workflow authoring
- `bytechef mcp [serve\|status]` — expose the CLI as an MCP server so Claude/Cursor can drive ByteChef without re-wrapping every command
- `bytechef component generate` — already partially exists as `component init`; extend to also emit TypeScript/Python SDK stubs
#### AI-agent ergonomics
The Make CLI announcement specifically calls out coding agents. ByteChef should design for this from day one:
- Every command returns structured JSON by default when invoked non-interactively (stdout is not a TTY)
- Error output is structured with stable error codes so agents can branch on them
- Ship an MCP server wrapper (`bytechef mcp serve`) so agents can drive the CLI without learning flag syntax
- Documented cookbook of agent recipes (e.g., duplicate a project from staging to prod, find all workflows using a deprecated connection)
#### Migration path for the existing CLI
- Keep `component init` and its OpenAPI generator at `cli/commands/component/` — useful and has users
- Add new command modules under `cli/commands/` (`project`, `workflow`, `connection`, `datatable`, `execution`, `webhook`, `workspace`, `auth`), each a Gradle subproject pulled into `cli-app` via `@EnableCommand`
- Extract a shared `cli-core` library for credential storage, HTTP client, output formatting, and profile handling so command modules don't duplicate plumbing
- Verify Spring Shell + Spring Boot AOT can native-image cleanly; fix reflection/proxy registrations as needed (GraalVM hints)
### Describe the alternative you've considered or used
- **Raw `curl` / Postman against REST + GraphQL.** Works but endpoints are undocumented externally, auth is awkward, and agents can't discover capabilities.
- **The existing `cli-app` as-is.** Only does component scaffolding; can't talk to a running instance.
- **Per-language SDKs only (e.g., `sdks/backend/java/`).** Useful for embedded integrations, but doesn't help shell users or AI agents that reach for a terminal command first.
- **Rewriting in Go or Node/TypeScript for easier binary distribution.** Rejected — Spring Shell is already the framework, the team owns Java deeply, and GraalVM native-image solves the distribution concern without throwing away the existing generator code.
- **Building our own MCP server without a CLI underneath.** Couples us to MCP-only consumers; a CLI gives both shell users and MCP users a single implementation.
### Additional context
Existing ByteChef CLI code to build on:
- `cli/cli-app/src/main/java/com/bytechef/cli/CliApplication.java` — Spring Boot + Spring Shell entrypoint
- `cli/commands/component/src/main/java/com/bytechef/cli/command/component/ComponentCommand.java` — the one shipped command (`component init`)
- `cli/commands/component/init/openapi/` — OpenAPI-to-component generator
Suggested breakdown into sub-tickets:
1. CLI framework hardening & distribution (GraalVM native-image, release automation, Homebrew tap, npm wrapper, install docs)
2. `cli-core` shared library (credential store, HTTP/GraphQL client, output formatting, profiles)
3. Authentication commands (`login`, `logout`, `whoami`, profiles)
4. Project & Workflow commands — read-only first (`list`, `get`, `export`)
5. Workflow mutations + execution (`create`, `update`, `run`, `execution list|logs|resume`)
6. Connection commands with EE visibility support
7. Data table commands
8. Component commands (preserve `init`, add `list`, `validate`, `publish`, `test`)
9. Webhook / trigger commands
10. Workspace & environment switching
11. MCP server wrapper + AI-agent documentation cookbook
Contributor guide
Assessment
This issue has not been assessed yet.