CLI reference
Create, inspect, validate, and run local Octonode workflows from your terminal.
The CLI reads your local project manifest and executes its configured node commands. Use Node.js 24 and a compatible Octonode CLI build.
Check your executable
octonode --version
octonode --helpIn a built source checkout, the executable is
packages/cli/dist/index.js. You can run it directly with Node:
node /absolute/path/to/octonode/packages/cli/dist/index.js --helpFor an MCP client using this checkout, set command to the absolute Node executable
and args to ["/absolute/path/to/octonode/packages/cli/dist/index.js", "mcp"].
The source checkout must already have its dependencies installed and packages built.
The first workflow walkthrough uses this setup.
Everyday commands
The examples use .octonode.yaml explicitly. Run them from your project directory.
| Task | Command |
|---|---|
| Create a manifest | octonode init .octonode.yaml --name orders |
| List built-in nodes | octonode add --list |
| Add an editable node | octonode add math.add --id add-1 --config .octonode.yaml |
| Refresh discovered signatures | octonode scan --config .octonode.yaml |
| Check drift without writing | octonode scan --check --config .octonode.yaml |
| Validate the manifest | octonode validate --config .octonode.yaml |
| Inspect human-owned settings | octonode settings show |
| Print the workflow graph | octonode graph total --config .octonode.yaml |
| Start API and built Studio | octonode serve --config .octonode.yaml |
| Start the MCP stdio server | octonode mcp |
scan discovers node contracts by invoking their describe protocol; ensure the
configured commands can execute. validate checks the configuration but does not
prove an external service is reachable or that its credentials are correct.
Invoke a node or run a workflow
After following the first-workflow setup:
octonode invoke add-1 --config .octonode.yaml --input '{"a":2,"b":3}'
octonode run total --config .octonode.yaml --input '{"a":2,"b":3}'invoke runs one registered node; run follows the workflow's connections.
Use --input-file input.json instead of --input for a larger JSON input, and
--env NAME to select a configured environment. Results are written to stdout;
diagnostic messages go to stderr.
Record and replay
octonode run total --config .octonode.yaml --input '{"a":2,"b":3}' --record run.json
octonode replay run.json square-1 --config .octonode.yamlA recording captures node inputs for inspection. Treat recordings according to the sensitivity of their data. Replay invokes the selected node again and may repeat external effects such as a write or notification.
Connect other tools
serve defaults to http://localhost:4000 and serves Studio when its build is
available. --port selects a different port. Use
access tokens and API calls to connect a backend, and
MCP setup for an AI client.
API connection variables configure API-backed MCP tools. Local run, invoke,
and scan continue to use your local manifest.
For reusable integrations, continue with TypeScript SDK and Nodes and plugins.
App authoring CLI
The separate octonodes developer CLI creates and publishes marketplace apps.
Follow Install the developer CLI for npm, Homebrew, Windows,
Linux and other installation options, then Create your first app. The octonode
engine CLI on this page builds and runs local workflow projects.