fh-workflow CLI Reference — Validate, Open & Migrate Agent Workflows
fh-workflow CLI Reference
fh-workflow is the command-line interface for the open-source edge-agents runtime. It opens the visual builder, validates and schema-checks *.workflow.json specs, and migrates workflow schemas. This is a terminal-first reference: one fenced example per subcommand.
Published by ForestHub.ai. Source: github.com/ForestHubAI/edge-agents.
Install
npm i -g @foresthubai/workflow-cli
Once installed, fh-workflow is on your PATH. From a checkout of the repo you can also run the equivalent scripts directly without a global install (see From the working tree).
Commands
fh-workflow open
fh-workflow open my.workflow.json
Launches the React Flow visual builder loaded with the given workflow. Edit nodes (GPIO, ADC/DAC/PWM, UART/Serial, MQTT, LLM, web-search) visually; the builder writes back a plain *.workflow.json.
fh-workflow validate
fh-workflow validate my.workflow.json
Semantic validation: checks that the workflow is internally consistent — node references resolve, required node inputs are wired, and the graph is executable by the engine. Use this before deploying to a device.
fh-workflow check-schema
fh-workflow check-schema my.workflow.json
Structural validation: checks the file against the workflow JSON schema (shape, types, required fields). Think of check-schema as “is this valid JSON-of-the-right-shape” and validate as “does this make sense as a workflow.”
fh-workflow update
fh-workflow update my.workflow.json
Migrates a workflow file to the current schema version. Run this after upgrading the CLI to bring older *.workflow.json files forward.
fh-workflow help
fh-workflow help
Prints the full subcommand list and flags for the installed version.
From the working tree
If you have cloned the repo instead of installing globally, the same checks are available via the package scripts:
# equivalent to: fh-workflow validate my.workflow.json
npm run validate -- my.workflow.json
Validation semantics at a glance
| Command | Layer | Answers |
|---|---|---|
check-schema | Structural | Is the file shaped correctly against the schema? |
validate | Semantic | Is the workflow internally consistent and executable? |
update | Migration | Bring an older spec to the current schema version |
open | Authoring | Edit the workflow in the visual builder |
The schema source of truth lives in the repo’s contract/ directory — an OpenAPI 3.0.3 definition published under Apache-2.0. When the CLI and engine disagree, contract/ wins.
Repo & CTA
// open source · Apache-2.0 contract/ · CLI under AGPL-3.0/commercial
$ fh-workflow validate my.workflow.json★ Star edge-agents on GitHub · ForestHub.ai platform · Book a meeting →
FAQ
Q: What is the difference between validate and check-schema?
check-schema is structural (does the JSON match the schema shape); validate is semantic (does the workflow form an executable graph). Run check-schema first, then validate.
Q: Where does the schema come from?
From the repo’s contract/ directory — an OpenAPI 3.0.3 contract licensed Apache-2.0. The engine and CLI both consume it.
Q: Do I need the engine installed to use the CLI?
No. fh-workflow (open / validate / check-schema / update) operates on workflow files. You only need the Go engine container when you actually run a workflow on a device — see the Runtime Quickstart.