steamharness run Loads a workflow directory on the local device, installs the global workflow runtime API, executes the createInput and workflow run of the selected entry (Conversation, executor), and outputs the result in normal CLI mode.
This command supports only Workflow and Conversation. Kanban is a static HTML project that returns an explicit execution-not-supported error; inspect it with steamharness structure, then preview it with steamharness web, Studio, or a Server Web static preview.
steamharness run [workflow-dir] [--entrypoint <id>] [--json] [--run-id <id>] [--conversation-id <id>] [--file-store-dir <dir>] [--related-project <alias>=<absolute-project-dir>] [--resolved-user-inputs-json <json>] [--tool-permissions-json <json>] [--] [...args]
Parameter
| Parameter | Description |
|---|
workflow-dir | workflow project directory. Use the current directory when not passing. |
args | The createInput({ args }) readable array of raw parameters for the selected entry (Conversation, executor). |
Options
| Options | Description |
|---|
--json | Toggles to JSON report output. The behavior is close to steamharness json. |
--entrypoint <id> | Run specifies the Workflow entry; use defaultEntrypoint when omitted. Conversation Passing a non-null value will result in failure. |
--run-id <id> | Specify the execution ID for this operation. Used to restore the same runId during waiting_for_input run. |
--conversation-id <id> | Specify the session ID. State read-write significance only for items that declare executor.projectType: "conversation". |
--file-store-dir <dir> | Specify the local file storage directory. Read STEAMHARNESS_FILE_STORE_DIR when not passed. |
--related-project <alias>=<absolute-project-dir> | Explicitly provide one related-project directory; repeatable. The two packages must confirm the relationship, and UUID and alias must match. |
--resolved-user-inputs-json <json> | Injects an array of submitted user input or tool approval answers. |
--tool-permissions-json <json> | Host-passed tool permission override policy; for regular manual CLI debugging, it is usually not required. |
File parameters accept a local path or JSON file reference. A parameter declared with control: "audio" accepts one audio file; CLI does not use a microphone, so pass a WAV, AIFF, FLAC, M4A, MP3, AAC, Opus, or Ogg path.
Execution process
| Phase | Description |
|---|
| Analysis Directory | workflow-dir uses the current directory by default. |
| Load Environment | Execute before loading workflow directory .env. |
| Select entrance | Workflow Press --entrypoint or defaultEntrypoint to select the execution configuration;Conversation uses executor itself. |
| Create Input | Invokes the createInput(context) of the selected entry or Conversation executor. |
| Execute workflow | Only steamharness.run(input, context) of the selected configuration is called, and the normal node will trigger CLI output hooks. |
| Set Exit Code | The exit code is 1 if workflow fails, pauses waiting for input, or payload errCode is not 0. |
Output
| Situation | Output |
|---|
Successful and not forwarded --json | The contents of the output node are written to stdout. |
Failed and not passed --json | The full JSON execution report is written to stderr. |
waiting_for_input and not passed --json | It does not interactively read from stdin; we recommend using steamharness json to view pendingUserInput and restore it instead. |
Imported --json | The full JSON execution report is written to stdout. |
Example
steamharness run .
steamharness run . --entrypoint validate -- --message "Validate only"
steamharness run workspace/workflow/hello -- --message "hello"
steamharness run workspace/workflow/runtime-timer -- --title "Fixture Timer" --milliseconds 2000
steamharness run . --conversation-id demo -- --message "Continue"
steamharness run . --related-project inventory=/srv/workflows/inventory -- --message "Read inventory"
STEAMHARNESS_KV_STORE_DIR="$PWD/.workflow-kv" \
STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR="$PWD/.workflow-persistent-values" \
steamharness run workspace/workflow/conversation-knowledge --conversation-id demo -- --message "Record today's conclusion"
steamharness run . --json -- --message "debug"
Precautions
| Scene | Recommendation |
|---|
The workflow parameter starts with --. | Using the delimiter --, the parameters following the delimiter will be passed to workflow as-is. |
workflow also defines the --entrypoint parameter | The entry selection of CLI is placed before the separator; the parameter with the same name after the separator enters the service args as it is. |
| Need to check node report | Use --json or use steamharness json instead. |
| User input or tool approval needs to be restored. | Use the same --run-id and --resolved-user-inputs-json; during debugging, prioritize using steamharness json. |
| A stable session is required. | Explicitly pass --conversation-id, otherwise the session ID may be generated by runtime based on input. |
| workflow calls PersistentValue or a Knowledge helper | Pass context.storage.local or .server explicitly. Local uses STEAMHARNESS_PERSISTENT_VALUE_STORE_DIR; server uses the project UUID and STEAMHARNESS_SERVER_URL / STEAMHARNESS_SERVER_ADMIN_KEY or workspace login. A forbidden or unavailable location fails without fallback or synchronization. |
| workflow accesses related-project KV | Repeat --related-project for every direct relationship. CLI validates the directory, UUID, alias, and both current declarations. A one-sided pending relationship is unavailable, and resolution never recurses through the target's other relationships. |
workflow call context.files.createFile(...) | The local operation reads the connection to the same server and uploads it to the server file API. If the server is not connected, the call will report an error and will not be written to the local file store. |
Project configurations
All three project types expose fields, named profiles and complete import/export. Studio and local CLI share local storage; Server values are per project and account. Studio Control can query and manage configurations even when the panel is closed. See Project configurations for the JSON actions, version checks and execution snapshot rules.