#a3s-flow CLI

a3s-flow ships with @a3s-lab/flow-ui. It reads the same node manifests as the canvas cards, configuration panels, and node reference pages, so field names, defaults, ports, and runtime bindings stay aligned. The CLI works on workflow documents and standard streams. It does not connect to model providers, read credentials, or execute host tasks.

#Install and verify

npm install @a3s-lab/flow-ui @a3s-lab/ui
npx a3s-flow help --pretty

The second command should return JSON with ok set to true and list nodes, new, validate, compile, and digest. If the shell cannot find the command, confirm that the dependencies are installed in the current project and invoke the local binary through npx or a project script.

A project script can call the locally installed binary directly.

{
  "scripts": {
    "flow:check": "a3s-flow validate workflow.json --pretty"
  }
}

Every command emits JSON. Exit code 0 means the command succeeded. Exit code 1 means the workflow structure or node settings were rejected. Exit code 2 means the invocation, arguments, or file operation was invalid. Automation should check both the process status and the top-level ok value.

#Command reference

Use --pretty for readable output and --output <file> to write JSON to a file. Pass - as the input path to read standard input. --include-internal applies to catalog inspection and exposes iteration-start and loop-start. Those internal types belong only inside matching containers and cannot be created as public nodes with new.

#Inspect and create a node

Inspect the catalog, read the target manifest, and then create an instance with a stable ID.

a3s-flow nodes --pretty
a3s-flow node flow.hook --pretty
a3s-flow new flow.hook --id approval --pretty

The node result is authoritative for field names, option values, and connection handles. Editors and scripts should not maintain a separate hand-written schema. The new command fills every manifest default and preserves the structure expected by validation. Once a run exists, the node ID is durable identity. Changing it can disconnect new graph state from committed steps, hooks, progress records, or child runs.

#Create the sample document

a3s-flow sample --output workflow.json --pretty
a3s-flow validate workflow.json --pretty

The sample registers graph structure only. It does not execute task.run. A host must provide that task handler and choose an event store, scheduler, and worker topology. For a real project, change the workflow name and node IDs before creating the first persistent run.

#Validate, compile, and digest

Run the three commands in this order after every semantic field or edge change.

a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --output workflow.plan.json --pretty
a3s-flow digest workflow.json --output workflow.digest.json --pretty

Validation checks the document envelope, public node types, field constraints, port connections, duplicate IDs, dangling edges, self edges, ordinary cycles, and container scope. Successful compilation proves that the top-level graph and each iteration or loop child canvas have deterministic order. Digests ignore position, title, description, dimensions, and selection state while binding executable node settings and edges. If a host needs an integrity pin, store the digest in release metadata instead of writing it back into the workflow document.

#Standard input and CI

git show HEAD:workflows/order-review.json |
  a3s-flow validate - --pretty

In CI, validate first and retain the compiled plan and digest as build artifacts when review requires them. Rejected output contains code, path, and message for every issue. Repair the field or edge named by the path instead of deleting unknown extension fields. For imported workflows, separately review task names, runtime entry points, public callbacks, and host bindings because the CLI does not make authorization or credential decisions.

#Custom node boundary

The CLI ships with the official built-in registry and does not load host application modules. A workflow containing a custom type will fail CLI validation with flow.node.unknown_type. Keep that rejection in place. Projects with custom nodes should provide a typed release command that imports the project catalog and calls compileA3SFlowWorkflowDagForPublication. See Custom nodes for the registration and publication contract.

#Diagnosing failures

unknown_node means the installed package does not expose the requested public type, so inspect nodes before changing the document. flow.node.internal_scope_required means an internal start marker has escaped its matching container. Graph errors usually point to an incorrect handle, a cross-scope edge, or a back edge. Field errors identify the exact node data path under workflow.graph.nodes.

For a file-read failure, check the working directory and supplied path first. When standard input never completes, the upstream command has probably kept its output open; write the document to a temporary file and validate it separately. After repair, rerun validation, compilation, and digesting so the final plan and release document come from the same check.