Command Transitions – Shell and Filesystem Execution
Command transitions execute shell commands and filesystem operations via the agentic-net-executor service. They enable your Petri nets to interact with the operating system – running scripts, managing files, invoking CLI tools, and integrating with external processes.
Command transitions dispatch work to the executor service and emit batch results.
Command Token Schema
Command transitions consume special command tokens that specify what to execute:
{
"kind": "command", // Always "command" for command tokens
"id": "cmd-001", // Unique command identifier
"executor": "bash", // Target executor: "bash" or "fs"
"command": "exec", // Command type: "exec" or "script"
"args": {
"command": "echo 'Hello World'",
"workingDir": "/path/to/dir",
"timeoutMs": 60000,
"captureStderr": true,
"env": { "KEY": "value" }
},
"expect": "text", // Expected return: "json", "text", "binary"
"meta": {
"correlationId": "req-001"
}
}
Executor Types
Bash Command Examples
Simple Command Execution
{
"kind": "command",
"id": "list-files",
"executor": "bash",
"command": "exec",
"args": {
"command": "ls -la /tmp",
"timeoutMs": 30000
},
"expect": "text"
}
Command with Environment Variables
{
"kind": "command",
"id": "build-project",
"executor": "bash",
"command": "exec",
"args": {
"command": "npm run build",
"workingDir": "/path/to/project",
"env": {
"NODE_ENV": "production",
"CI": "true"
},
"timeoutMs": 300000
},
"expect": "text"
}
Claude CLI Command (Critical Pattern)
Critical: CLI tools like Claude can block waiting for stdin. Always redirect stdin:
{
"kind": "command",
"id": "ask-claude",
"executor": "bash",
"command": "exec",
"args": {
"command": "claude -p 'Summarize this code' --no-session-persistence < /dev/null",
"workingDir": "/path/to/project",
"timeoutMs": 180000,
"env": { "HOME": "/Users/myuser" }
},
"expect": "text"
}
# Always redirect stdin to prevent blocking:
claude -p '...' --no-session-persistence < /dev/nullCommand Transition Inscription
{
"id": "t-execute-command",
"kind": "command",
"mode": "SINGLE",
"presets": {
"input": {
"placeId": "command-queue",
"host": "cmd-model@localhost:8080",
"arcql": "FROM $ LIMIT 1",
"take": "FIRST",
"consume": true
}
},
"postsets": {
"response": { "placeId": "response-place", "host": "cmd-model@localhost:8080" }
},
"action": {
"type": "command",
"inputPlace": "input",
"groupBy": "executor",
"dispatch": [
{ "executor": "bash", "channel": "default" }
],
"await": "ALL",
"timeoutMs": 300000
},
"emit": [
{ "to": "response", "from": "@result", "when": "success" }
]
}
Command Result Structure
Command transitions return batch results with detailed execution information:
{
"batchPrefix": "t-execute-command-1706123456789",
"batchResults": [{
"executor": "bash",
"results": [{
"id": "cmd-001",
"status": "SUCCESS",
"output": {
"exitCode": 0,
"stdout": "Command output here\n",
"stderr": "",
"success": true,
"command": "echo 'Hello World'"
},
"durationMs": 15
}],
"totalCount": 1,
"successCount": 1,
"failedCount": 0
}],
"success": true
}
Filesystem Operations
Read File
{
"kind": "command",
"id": "read-config",
"executor": "fs",
"command": "readFile",
"args": {
"path": "/etc/app/config.json",
"encoding": "utf-8"
},
"expect": "json"
}
Write File
{
"kind": "command",
"id": "write-report",
"executor": "fs",
"command": "writeFile",
"args": {
"path": "/tmp/report.txt",
"content": "Report generated at...",
"encoding": "utf-8"
},
"expect": "json"
}
List Directory
{
"kind": "command",
"id": "list-logs",
"executor": "fs",
"command": "listDir",
"args": {
"path": "/var/log/app",
"recursive": false
},
"expect": "json"
}
Summary
- kind: “command” – identifies the transition type
- Command tokens – special schema with executor, command, args
- Executors – bash (shell commands) and fs (file operations)
- emit.from: “@result” – batch execution results
- Stdin redirect – always use
< /dev/nullfor CLI tools - Port 8084 – agentic-net-executor service
Command transitions bridge your Petri nets to the operating system – use them for shell automation, file processing, and CLI tool integration.