Your first workflow — end to end

This walks you from an empty directory to a running two-node workflow, then shows the same workflow executed as a generated function. Every command is real; copy them as you go. (Run octonode from a clone via node packages/cli/dist/index.js or after npm link -w @octonode/cli — see docs/README.md.)

1. Scaffold a project

mkdir orders && cd orders
octonode init --name orders --format yaml

This writes a .octonode with a # yaml-language-server: $schema= line, so editors that understand JSON Schema give you autocomplete (the schema is published and versioned — octonode schema prints it).

2. Add two native nodes

Native nodes are materialized into real source files you own:

octonode add math.add --id add-1            # inputs { a, b } -> { result }
octonode add math.square --id square-1      # inputs { a }    -> { result }

Each writes nodes/add_1.ts / nodes/square_1.ts plus runtime artifacts and registers the node (with its described signature + checksum) in .octonode. List the catalog with octonode add --list.

3. Wire them into a workflow

Edit .octonode and add a workflow that feeds add's result into square's a:

workflows:
  - id: wf
    nodes: [add-1, square-1]
    edges:
      - from: { node: add-1, output: result }
        to:   { node: square-1, input: a }

Check it: octonode validate (warns on dangling edges, unconsumed flow.switch default ports, signature drift, …).

4. Run it

octonode run wf --input '{"a":2,"b":3}'
# → {"square-1":{"result":25}}     (2 + 3 = 5, then 5² = 25)

Inputs flow node→node along edges; independent branches run in parallel; terminal nodes' outputs are the result. Add --record run.json to capture the run, then octonode replay run.json square-1 to re-run one node from its recorded inputs.

Export the shape with octonode graph wf (Mermaid, or --format dot).

5. (Optional) Run it as a generated function

Octonode is code-first, so a workflow can also be compiled into an idiomatic, runnable function that imports each node and composes them:

octonode codegen orchestrate wf       # writes nodes/_workflows/wf.js
octonode run wf --compiled --input '{"a":2,"b":3}'
# → {"square-1":{"result":25}}        (same result as the DAG run)

The generated file has a machine-owned region between // <octonode:flow> markers (regenerated when the canvas changes, checksum-guarded against hand-edits) and a user region below it that's preserved. Internal TypeScript nodes run in-process; external plugin nodes go through a subprocess shim, so the result matches the DAG path for any validly-wired workflow.

Where next

• native-nodes.md — the full built-in catalog (math, logic, flow, data, text, datetime, code).
• plugins.md — install marketplace plugins (HTTP, Slack, GitHub, Postgres, Claude) or generate one from an OpenAPI spec (octonode plugin from-swagger).
• config-reference.md — the .octonode ownership model.