CLI - Nodex

CLI

CLI commands

The Nodex CLI mirrors the Express developer flow: scaffold a project, develop it with a watch loop, then run it for one-shot execution. Install it alongside the package — pip install nodex-ai puts the nodex command on your PATH.

nodex new <name>	Scaffold a starter agent project in a new directory.
nodex dev <target>	Run an agent in watch mode — restart on file save while editing.
nodex run <target>	Run an agent once for production-style execution.

cli

$ nodex new my-agent
$ cd my-agent
$ nodex dev agent:app
$ nodex run agent:app --input '{"query":"hello"}'

Scaffold

nodex new

Creates a starter project with agent.py, .env, requirements.txt, and .gitignore.

nodex new <project-name>

<project-name>	Name of the new directory to create for the project.

scaffold

$ nodex new research-agent
$ cd research-agent
$ ls
agent.py  .env  requirements.txt  .gitignore

Development

nodex dev

Runs the agent in watch mode. The agent re-executes automatically when source files change — useful while iterating on node logic.

nodex dev <module>:<instance> [--input JSON]

<module>:<instance>	Python module path and the `Agent` variable name, e.g. `agent:app`.
--input JSON	Initial state as a JSON string. Passed to `app.run()` on each reload.

Production

nodex run

Executes the agent once. Prints the full execution trace and exits.

nodex run <module>:<instance> [--input JSON]

<module>:<instance>	Python module path and the `Agent` variable name.
--input JSON	Initial state as a valid JSON string.

nodex run agent:app --input '{"query":"AI trends"}'

Input

Pass initial state as JSON

The --input flag accepts a valid JSON object. It is parsed and passed as the initial state dictionary to app.run().

nodex run agent:app --input '{"query":"hello","debug":true}'

The target format is module:instance, such as agent:app. The module is imported relative to the current working directory.

Windows users Use double quotes for the JSON string on Windows CMD (nodex run agent:app --input "{\"query\":\"hello\"}"), or single quotes in PowerShell (nodex run agent:app --input '{"query":"hello"}').