@amaster.ai/runtime-cli 1.1.9 → 1.1.11

package/README.md

@@ -1,6 +1,6 @@
 # @amaster.ai/runtime-cli
 
-CLI for Amaster SDK - Multi-app support for OpenClaw. Manage multiple Amaster applications, entities, BPM processes, workflows, and S3 files from a single command-line interface.
+CLI for Amaster SDK - Multi-app support for OpenClaw. Manage multiple Amaster applications, entities, BPM processes, workflows, and S3 object operations from a single command-line interface.
 
 ## Features
 
@@ -9,8 +9,8 @@ CLI for Amaster SDK - Multi-app support for OpenClaw. Manage multiple Amaster ap
 - **Structured Output**: `json`, `pretty`, `table`, `ndjson`, and `csv`
 - **Entity Management**: CRUD, options lookup, and bulk operations on entities
 - **BPM**: Manage Camunda processes, tasks, and instances
-- **Workflow**: Execute and monitor workflows
-- **S3 Storage**: Upload, download, list, and manage files
+- **Workflow**: Run workflows
+- **S3 Storage**: Upload files, download objects, and inspect metadata
 - **OpenClaw Integration**: Initialize app-specific skills and MCP servers
 
 ## Installation
@@ -42,6 +42,8 @@ npm_config_ignore_scripts=1 npm uninstall -g @amaster.ai/runtime-cli
 
 ## Quick Start
 
+Apps that expose anonymous endpoints do not require `amaster login` first. When no local token exists, the CLI now sends unauthenticated requests and lets the server decide whether the endpoint is public or requires auth.
+
 ### 1. Initialize an App
 
 ```bash
@@ -84,6 +86,10 @@ amaster logout --app myapp
 ### 4. Use SDK Features
 
 ```bash
+# Run an anonymous workflow when the app exposes it publicly
+amaster workflow run text-sentiment-analysis --app myapp \
+  --input '{"input_text":"I love this product. It is fast and easy to use."}'
+
 # List entities - full JSON output (default)
 amaster entity list default products --app myapp
 
@@ -169,7 +175,7 @@ amaster entity bulk-delete default products --app myapp --ids 1,2,3
 amaster entity bulk-delete default products --app myapp --ids '[1,2,3]'
 ```
 
-For `amaster entity list`, explicit options such as `--fields`, `--relations`, and `--order-by` override the same keys inside `--query`.
+For `amaster entity list`, explicit options such as `--page`, `--page-size`, `--fields`, `--relations`, and `--order-by` override the same keys inside `--query`. If you omit `--page` and `--page-size`, the CLI does not inject pagination defaults and forwards only the parameters you provided.
 
 ## Commands
 
@@ -223,8 +229,8 @@ amaster whoami [options]              # Show current user information
 ```bash
 amaster entity list <namespace> <entity> [options]
   --app <app-code>                    # App code (uses default if not specified)
-  --page <page>                       # Page number (default: 1)
-  --page-size <size>                  # Page size (default: 10)
+  --page <page>                       # Page number
+  --page-size <size>                  # Page size
   -f, --fields <fields>               # Comma-separated fields to return
   -r, --relations <relations>         # Comma-separated relations to load
   -k, --keyword <keyword>             # Keyword to search
@@ -341,42 +347,290 @@ amaster entity bulk-delete default products --app myapp --ids 1,2,3
 ```bash
 amaster bpm processes [options]       # List process definitions
   --app <app-code>                    # App code (uses default if not specified)
+  --key <key>                         # Filter by process definition key
+  --name <name>                       # Filter by process definition name
+  --latest-version                    # Only return latest version
+  --active                            # Only return active process definitions
+  --suspended                         # Only return suspended process definitions
+  --sort-by <field>                   # Sort field
+  --sort-order <order>                # Sort order: asc | desc
+  -q, --query <json>                  # Additional ProcessDefinitionQueryParams as JSON or @file
+
+amaster bpm xml <key> [options]       # Get BPMN XML for a process definition key
+  --app <app-code>                    # App code (uses default if not specified)
 
 amaster bpm start <key> [options]     # Start a process instance
   --app <app-code>                    # App code (uses default if not specified)
-  -v, --variables <json>              # Process variables as JSON
+  -v, --variables <json>              # Process variables as JSON or @file
+
+amaster bpm instances [options]       # List process instances
+  --app <app-code>                    # App code (uses default if not specified)
+  --process-definition-key <key>      # Filter by process definition key
+  --active                            # Only return active instances
+  --first-result <n>                  # Pagination offset
+  --max-results <n>                   # Maximum number of results
+  -q, --query <json>                  # Additional ProcessInstanceQueryParams as JSON or @file
+
+amaster bpm instance <id> [options]   # Get a process instance by ID
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm instance-tree <id> [options]  # Get activity instance tree
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm active-activities <id> [options]  # Get active activities
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm runtime-variables <id> [options]  # Get runtime variables
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm variables <id> [options]  # Get historic variables
+  --app <app-code>                    # App code (uses default if not specified)
+  --name <name>                       # Filter by variable name
+
+amaster bpm delete-instance <id> [options]   # Delete a process instance
+  --app <app-code>                    # App code (uses default if not specified)
+  --skip-custom-listeners             # Skip custom listeners during deletion
+
+amaster bpm suspend-instance <id> [options]  # Suspend a process instance
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm activate-instance <id> [options] # Activate a process instance
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm modify-instance <id> [options]   # Modify a process instance
+  --app <app-code>                    # App code (uses default if not specified)
+  -m, --modification <json>           # ProcessInstanceModification JSON or @file
 
 amaster bpm tasks [options]           # List tasks
   --app <app-code>                    # App code (uses default if not specified)
   -a, --assignee <assignee>           # Filter by assignee
+  --process-instance-id <id>          # Filter by process instance ID
+  --candidate-user <user>             # Filter by candidate user
+  --candidate-group <group>           # Filter by candidate group
+  --name <name>                       # Filter by exact task name
+  --name-like <name>                  # Filter by fuzzy task name
+  --task-definition-key <key>         # Filter by task definition key
+  --first-result <n>                  # Pagination offset
+  --max-results <n>                   # Maximum number of results
+  --sort-by <field>                   # Sort field
+  --sort-order <order>                # Sort order: asc | desc
+  -q, --query <json>                  # Additional TaskQueryParams as JSON or @file
+
+amaster bpm task <id> [options]       # Get a task by ID
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster bpm task-count [options]      # Get task count
+  --app <app-code>                    # App code (uses default if not specified)
+  -a, --assignee <assignee>           # Filter by assignee
+  --process-instance-id <id>          # Filter by process instance ID
+  --candidate-user <user>             # Filter by candidate user
+  --candidate-group <group>           # Filter by candidate group
+  --name <name>                       # Filter by exact task name
+  --name-like <name>                  # Filter by fuzzy task name
+  --task-definition-key <key>         # Filter by task definition key
+  --first-result <n>                  # Pagination offset
+  --max-results <n>                   # Maximum number of results
+  --sort-by <field>                   # Sort field
+  --sort-order <order>                # Sort order: asc | desc
+  -q, --query <json>                  # Additional TaskQueryParams as JSON or @file
 
 amaster bpm complete <id> [options]   # Complete a task
   --app <app-code>                    # App code (uses default if not specified)
-  -v, --variables <json>              # Task variables as JSON
+  -v, --variables <json>              # Task variables as JSON or @file
+
+amaster bpm delegate <id> [options]   # Delegate a task
+  --app <app-code>                    # App code (uses default if not specified)
+  --user-id <userId>                  # Delegate target user ID
+
+amaster bpm task-form <id> [options]          # Get task form metadata
+amaster bpm task-form-schema <id> [options]   # Get task form schema
+  --redirect <url>                            # Optional redirect URL
+amaster bpm task-form-variables <id> [options]  # Get task form variables
+amaster bpm task-rendered-form <id> [options]   # Get rendered task form HTML
+amaster bpm task-deployed-form <id> [options]   # Get deployed task form definition
+  --app <app-code>                             # App code (uses default if not specified)
+
+amaster bpm start-form <key> [options]            # Get start form info
+amaster bpm start-form-variables <key> [options]  # Get start form variables
+amaster bpm start-form-deployed <key> [options]   # Get deployed start form
+  --app <app-code>                                # App code (uses default if not specified)
+
+amaster bpm history-tasks [options]               # List history tasks
+  --app <app-code>                                # App code (uses default if not specified)
+  --task-assignee <assignee>                      # Filter by historical task assignee
+  --process-instance-id <id>                      # Filter by process instance ID
+  --finished                                      # Only return finished history tasks
+  --unfinished                                    # Only return unfinished history tasks
+  --scope <scope>                                 # handled
+  --first-result <n>                              # Pagination offset
+  --max-results <n>                               # Maximum number of results
+  --sort-by <field>                               # Sort field
+  --sort-order <order>                            # Sort order: asc | desc
+  -q, --query <json>                              # Additional HistoryTaskQueryParams as JSON or @file
+
+amaster bpm history-task-count [options]          # Get history task count
+  --app <app-code>                                # App code (uses default if not specified)
+  [same filters as history-tasks]
+
+amaster bpm history-instances [options]           # List history process instances
+  --app <app-code>                                # App code (uses default if not specified)
+  --started-by <userId>                           # Filter by starter user ID
+  --process-definition-key <key>                  # Filter by process definition key
+  --finished                                      # Only return finished history instances
+  --unfinished                                    # Only return unfinished history instances
+  --scope <scope>                                 # initiated
+  --sort-by <field>                               # Sort field
+  --sort-order <order>                            # Sort order: asc | desc
+  --first-result <n>                              # Pagination offset
+  --max-results <n>                               # Maximum number of results
+  -q, --query <json>                              # Additional HistoryProcessInstanceQueryParams as JSON or @file
+
+amaster bpm history-instance-count [options]      # Get history process instance count
+  --app <app-code>                                # App code (uses default if not specified)
+  [same filters as history-instances]
+
+amaster bpm history-instance <id> [options]       # Get a history process instance by ID
+  --app <app-code>                                # App code (uses default if not specified)
+
+amaster bpm history-activities [options]          # List history activity instances
+  --app <app-code>                                # App code (uses default if not specified)
+  --process-instance-id <id>                      # Filter by process instance ID
+  --activity-id <activityId>                      # Filter by BPMN activity ID
+  --activity-type <activityType>                  # Filter by activity type
+  --finished                                      # Only return finished activity instances
+  --sort-by <field>                               # Sort field
+  --sort-order <order>                            # Sort order: asc | desc
+  -q, --query <json>                              # Additional HistoryActivityQueryParams as JSON or @file
+
+amaster bpm history-variables [options]           # List history variable instances
+  --app <app-code>                                # App code (uses default if not specified)
+  --process-instance-id <id>                      # Filter by process instance ID
+  --variable-name <name>                          # Filter by variable name
+  --deserialize-values                            # Deserialize complex variable values
+  -q, --query <json>                              # Additional HistoryVariableQueryParams as JSON or @file
+
+amaster bpm user-operations [options]             # List user operation logs
+  --app <app-code>                                # App code (uses default if not specified)
+  --process-instance-id <id>                      # Filter by process instance ID
+  --task-id <id>                                  # Filter by task ID
+  --user-id <userId>                              # Filter by user ID
+  --operation-type <type>                         # Filter by operation type
+  --sort-by <field>                               # Sort field
+  --sort-order <order>                            # Sort order: asc | desc
+  --first-result <n>                              # Pagination offset
+  --max-results <n>                               # Maximum number of results
+  -q, --query <json>                              # Additional UserOperationLogQueryParams as JSON or @file
+
+amaster bpm delete-history-instance <id> [options]  # Delete a history process instance
+  --app <app-code>                                   # App code (uses default if not specified)
+
+amaster bpm roles [options]                       # List runtime roles
+  --app <app-code>                                # App code (uses default if not specified)
+
+amaster bpm user-roles <userId> [options]        # List roles assigned to a user
+  --app <app-code>                                # App code (uses default if not specified)
 ```
 
-### Workflow
+#### BPM Parameter Examples
 
 ```bash
-amaster workflow list [options]       # List workflows
-  --app <app-code>                    # App code (uses default if not specified)
+# Filter process definitions
+amaster bpm processes --app myapp --key order-approval --latest-version
+
+# Get BPMN XML
+amaster bpm xml order-approval --app myapp --format pretty
+
+# Start a process with inline JSON
+amaster bpm start order-approval --app myapp \
+  --variables '{"orderId":"123","amount":199.5}'
+
+# Start a process with @file
+amaster bpm start order-approval --app myapp \
+  --variables @./process-start.json
+
+# List instances
+amaster bpm instances --app myapp --process-definition-key order-approval --active
+
+# Inspect a single instance
+amaster bpm instance proc-123 --app myapp
+
+# Read active activities
+amaster bpm active-activities proc-123 --app myapp
+
+# Read runtime variables
+amaster bpm runtime-variables proc-123 --app myapp
+
+# Read historic variables
+amaster bpm variables proc-123 --app myapp --name amount
+
+# List tasks with filters
+amaster bpm tasks --app myapp --assignee user-1 --sort-by created --sort-order desc
+
+# Count tasks
+amaster bpm task-count --app myapp --candidate-group finance
+
+# Complete a task
+amaster bpm complete task-123 --app myapp --variables '{"approved":true}'
+
+# Delegate a task
+amaster bpm delegate task-123 --app myapp --user-id user-2
+
+# Read task form schema
+amaster bpm task-form-schema task-123 --app myapp
+
+# Read start form info
+amaster bpm start-form order-approval --app myapp
 
-amaster workflow execute <id> [options]  # Execute a workflow
+# Query history tasks and process instances
+amaster bpm history-tasks --app myapp --task-assignee user-1 --finished
+amaster bpm history-instances --app myapp --process-definition-key order-approval --finished
+
+# Query history activities / variables / user operations
+amaster bpm history-activities --app myapp --process-instance-id proc-123
+amaster bpm history-variables --app myapp --process-instance-id proc-123 --variable-name amount
+amaster bpm user-operations --app myapp --process-instance-id proc-123 --sort-by timestamp --sort-order desc
+
+# Runtime roles
+amaster bpm roles --app myapp
+amaster bpm user-roles user-2 --app myapp
+
+# Suspend / activate / delete instance
+amaster bpm suspend-instance proc-123 --app myapp
+amaster bpm activate-instance proc-123 --app myapp
+amaster bpm delete-instance proc-123 --app myapp --skip-custom-listeners
+
+# Delete a historical instance
+amaster bpm delete-history-instance proc-123 --app myapp
+
+# Modify an instance from @file
+amaster bpm modify-instance proc-123 --app myapp \
+  --modification @./process-modification.json
+```
+
+### Workflow
+
+```bash
+amaster workflow run <name> [options]    # Run a workflow
   --app <app-code>                    # App code (uses default if not specified)
-  -i, --input <json>                  # Workflow input as JSON
+  -i, --input <json>                  # Workflow inputs object as JSON or @file
+  -r, --request <json>                # Full WorkflowRunRequest as JSON or @file
+  --response-mode <mode>              # blocking | streaming
+  --user <user>                       # Workflow user identifier
+  --files <json>                      # Workflow files array as JSON or @file
+  --trace-id <traceId>                # Workflow trace ID
 ```
 
 ### S3 Storage
 
 ```bash
-amaster s3 list [options]             # List files
+amaster s3 upload <file> [options]    # Upload a file
   --app <app-code>                    # App code (uses default if not specified)
-  -b, --bucket <bucket>               # Bucket name
 
-amaster s3 upload <file> [options]    # Upload a file
+amaster s3 download <key> <output> [options]
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster s3 metadata <key> [options]
   --app <app-code>                    # App code (uses default if not specified)
-  -b, --bucket <bucket>               # Bucket name
-  -k, --key <key>                     # Object key
 ```
 
 ## Configuration