@amaster.ai/runtime-cli

v1.1.27

Published

3 days ago

CLI for Amaster SDK - Multi-app support for OpenClaw

0High
0Medium
0Low

amaster openclaw cli sdk runtime

@amaster.ai/runtime-cli

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

Multi-App Support: Manage multiple Amaster applications simultaneously
Authentication: Login/logout with per-app token storage
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: Discover, inspect, and run workflows
S3 Storage: Upload files, download objects, and inspect metadata
OpenClaw Integration: Initialize app-specific skills and MCP servers

Installation

npm install -g @amaster.ai/runtime-cli

Or use with npx:

npx @amaster.ai/runtime-cli

Automatic Cleanup

When you uninstall @amaster.ai/runtime-cli, it will automatically clean up:

npm uninstall -g @amaster.ai/runtime-cli
# Automatically removes auth sessions

To skip automatic cleanup:

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

# Initialize a new app
amaster init --app-code myapp --url https://myapp.helige.cn

# With API key for OSS access
amaster init --app-code myapp --url https://myapp.helige.cn --api-key YOUR_API_KEY

2. Set Default App (Optional)

# Set default app for subsequent commands
amaster use myapp

# List all configured apps
amaster apps

3. Authenticate

# Login (interactive - will prompt for username/email and password)
amaster login --app myapp

# Login with email
amaster login --app myapp -e [email protected] -p secret

# Login with username
amaster login --app myapp -u admin -p secret

# Check current user
amaster whoami --app myapp

# Logout
amaster logout --app myapp

4. Use SDK Features

# Discover runnable workflows and inspect required inputs
amaster workflow list --app myapp --format pretty
amaster workflow get <workflow-app-id> --app myapp --format pretty

# 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

# Human-friendly output
amaster entity list default products --app myapp --format pretty

# Table output
amaster entity list default products --app myapp --format table

# Newline-delimited JSON
amaster entity list default products --app myapp --format ndjson

# CSV output
amaster entity list default products --app myapp --format csv

# List entities with pagination
amaster entity list default products --app myapp --page 1 --page-size 10

# List entities with explicit query params
amaster entity list default products --app myapp \
  --fields id,name,price \
  --relations category \
  --order-by created_at \
  --order-dir desc

# Multi-order sorting
amaster entity list default products --app myapp \
  --orders created_at:desc,name:asc

# Keyword search in specific fields
amaster entity list default products --app myapp \
  --keyword keyboard \
  --keyword-fields name,description

# Advanced filter via JSON or @file
amaster entity list default products --app myapp \
  --filter '{"conjunction":"and","children":[]}'

# Offset/limit pagination
amaster entity list default products --app myapp --limit 20 --offset 40

# Raw query escape hatch for any remaining EntityQueryParams
amaster entity list default products --app myapp \
  --query '{"status":"active","orderBy":"created_at","orderDir":"desc"}'

# Get a specific entity
amaster entity get default products 123 --app myapp

# Create from inline JSON
amaster entity create default products --app myapp \
  --data '{"name":"Mechanical Keyboard","price":399}'

# Create from @file
amaster entity create default products --app myapp \
  --data @./product-create.json

# Update from inline JSON
amaster entity update default products 123 --app myapp \
  --data '{"price":499}'

# Update from @file
amaster entity update default products 123 --app myapp \
  --data @./product-update.json

# Delete by ID
amaster entity delete default products 123 --app myapp

# Get select options with selected fields
amaster entity options default categories --app myapp --fields id,name

# Bulk update from inline JSON
amaster entity bulk-update default products --app myapp \
  --items '[{"id":1,"status":"active"},{"id":2,"status":"inactive"}]'

# Bulk update from @file
amaster entity bulk-update default products --app myapp \
  --items @./products-bulk-update.json

# Bulk delete by comma-separated IDs
amaster entity bulk-delete default products --app myapp --ids 1,2,3

# Bulk delete by JSON array
amaster entity bulk-delete default products --app myapp --ids '[1,2,3]'

# Discover runtime datasources and models
amaster model datasources --app myapp

# Fetch CREATE TABLE statements for one datasource
amaster model table-schema source-123 --app myapp

# Limit schema output to selected tables
amaster model table-schema source-123 --app myapp --tables products,categories

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

Output Formats

Most commands support:

--format json      # Full JSON response (default)
--format pretty    # Human-friendly output
--format table     # Readable table
--format ndjson    # Newline-delimited JSON
--format csv       # Comma-separated values

App Management

amaster apps                          # List all configured apps
amaster use <app-code>                # Set the default app

Initialization

amaster init                          # Initialize an app for OpenClaw
  --app-code <code>                   # Required: Application code (e.g., bleulig7o)
  --url <url>                         # Required: Base URL (e.g., https://app.helige.cn)
  --api-key <key>                     # Optional: API Key for OSS access
  --oss-endpoint <endpoint>           # Optional: OSS endpoint

Authentication

amaster login [options]               # Login with username/email and password
  --app <app-code>                    # App code (uses default if not specified)
  -u, --username <username>           # Username
  -e, --email <email>                 # Email address
  -p, --password <password>           # Password

amaster logout [options]              # Logout from an app
  --app <app-code>                    # App code (uses default if not specified)

amaster whoami [options]              # Show current user information
  --app <app-code>                    # App code (uses default if not specified)

Entity Management

amaster entity list <namespace> <entity> [options]
  --app <app-code>                    # App code (uses default if not specified)
  --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
  --keyword-fields <fields>           # Comma-separated fields for keyword search
  --order-by <field>                  # Field to sort by
  --order-dir <dir>                   # Sort direction: asc | desc
  --orders <orders>                   # Multi-order expression
  --filter <json>                     # Advanced __filter JSON or @file
  --limit <limit>                     # Limit number of records
  --offset <offset>                   # Offset number of records
  -q, --query <json>                  # Additional EntityQueryParams as JSON or @file
  --format <format>                   # json | pretty | table | ndjson | csv

amaster entity get <namespace> <entity> <id> [options]
  --app <app-code>                    # App code (uses default if not specified)

amaster entity create <namespace> <entity> [options]
  --app <app-code>                    # App code (uses default if not specified)
  -d, --data <json>                   # Entity data as JSON or @file

amaster entity update <namespace> <entity> <id> [options]
  --app <app-code>                    # App code (uses default if not specified)
  -d, --data <json>                   # Entity data as JSON or @file

amaster entity delete <namespace> <entity> <id> [options]
  --app <app-code>                    # App code (uses default if not specified)

amaster entity options <namespace> <entity> [options]
  --app <app-code>                    # App code (uses default if not specified)
  -f, --fields <fields>               # Comma-separated fields to return

amaster entity bulk-update <namespace> <entity> [options]
  --app <app-code>                    # App code (uses default if not specified)
  -i, --items <json>                  # Items array as JSON or @file

amaster entity bulk-delete <namespace> <entity> [options]
  --app <app-code>                    # App code (uses default if not specified)
  --ids <ids>                         # Comma-separated IDs, JSON array, or @file

Model Discovery

amaster model datasources [options]
  --app <app-code>                    # App code (uses default if not specified)

amaster model table-schema <source-id> [options]
  --app <app-code>                    # App code (uses default if not specified)
  --tables <tables>                   # Comma-separated table names, JSON array, or @file

Entity Parameter Examples

# --app
amaster entity list default products --app myapp

# --page
amaster entity list default products --app myapp --page 2

# --page-size
amaster entity list default products --app myapp --page-size 50

# --fields
amaster entity list default products --app myapp --fields id,name,price

# --relations
amaster entity list default products --app myapp --relations category,owner

# --keyword
amaster entity list default products --app myapp --keyword keyboard

# --keyword-fields
amaster entity list default products --app myapp \
  --keyword keyboard \
  --keyword-fields name,description

# --order-by
amaster entity list default products --app myapp --order-by created_at

# --order-dir
amaster entity list default products --app myapp \
  --order-by created_at \
  --order-dir desc

# --orders
amaster entity list default products --app myapp \
  --orders created_at:desc,name:asc

# --filter
amaster entity list default products --app myapp \
  --filter '{"conjunction":"and","children":[]}'

# --limit
amaster entity list default products --app myapp --limit 10

# --offset
amaster entity list default products --app myapp --offset 20

# --query
amaster entity list default products --app myapp \
  --query '{"status":"active","price[ge]":100}'

# create --data
amaster entity create default products --app myapp \
  --data '{"name":"Mechanical Keyboard","price":399}'

# update --data
amaster entity update default products 123 --app myapp \
  --data '{"price":499}'

# options --fields
amaster entity options default categories --app myapp --fields id,name

# bulk-update --items
amaster entity bulk-update default products --app myapp \
  --items '[{"id":1,"status":"active"}]'

# bulk-delete --ids
amaster entity bulk-delete default products --app myapp --ids 1,2,3

# model datasources
amaster model datasources --app bleulig7o

# model table-schema
amaster model table-schema source-ae0rbo4tg9a8 --app bleulig7o

# model table-schema --tables
amaster model table-schema source-ae0rbo4tg9a8 --app bleulig7o --tables products,categories

BPM (Business Process Management)

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 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 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)

BPM Parameter Examples

# 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

# 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

amaster workflow list [options]          # List workflow apps and runnable names
  --app <app-code>                    # App code (uses default if not specified)
  --page <n>                          # Page number
  --limit <n>                         # Page size
  --mode <mode>                       # workflow | chat | completion | agent-chat

amaster workflow get <id> [options]     # Get workflow details and input variables by workflow app ID
  --app <app-code>                    # App code (uses default if not specified)

amaster workflow run <name> [options]    # Run a workflow
  --app <app-code>                    # App code (uses default if not specified)
  -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

Use workflow list to discover workflow app IDs and runnable_name. Use the id with workflow get, and use the runnable_name or the name returned by workflow get with workflow run.

S3 Storage

amaster s3 upload <file> [options]    # Upload a file
  --app <app-code>                    # App code (uses default if not specified)

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)

Configuration

Configuration files are stored in ~/.amaster/:

File Locations

App Config: ~/.amaster/config.json

{
  "apps": {
    "myapp": {
      "baseURL": "https://myapp.helige.cn",
      "initializedAt": "2025-03-26T..."
    }
  },
  "currentApp": "myapp"
}

Auth Sessions: ~/.amaster/auth-{appCode}.json

{
  "accessToken": "...",
  "refreshToken": "...",
  "loggedInAt": "2025-03-26T...",
  "expiresIn": 86400
}

Multi-App Workflow

# Initialize multiple apps
amaster init --app-code app1 --url https://app1.helige.cn
amaster init --app-code app2 --url https://app2.helige.cn

# List all apps
amaster apps

# Work with app1 (explicit)
amaster entity list default products --app app1

# Set app2 as default
amaster use app2

# Now commands use app2 by default
amaster entity list default users        # Uses app2
amaster whoami                           # Uses app2

# Override default for single command
amaster whoami --app app1                # Uses app1

Development

# Install dependencies
pnpm install

# Build
pnpm run build

# Development mode
pnpm run dev

# Type check
pnpm run type-check

# Run tests
pnpm test

# Run tests with coverage
pnpm test:coverage

Testing Example

Using bleulig7o app as an example:

# Login
amaster login --app bleulig7o -e [email protected] -p Admin@123456

# View products
amaster entity list default products --app bleulig7o --page 1 --page-size 10

# Get specific product
amaster entity get default products 1 --app bleulig7o

Architecture

The CLI integrates all Amaster SDK clients:

@amaster.ai/client - Unified client for all services
@amaster.ai/auth-client - Authentication
@amaster.ai/entity-client - Entity CRUD
@amaster.ai/bpm-client - BPM processes
@amaster.ai/workflow-client - Workflow execution
@amaster.ai/s3-client - File storage

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@amaster.ai/runtime-cli

Features

Installation

Automatic Cleanup

Quick Start

1. Initialize an App

2. Set Default App (Optional)

3. Authenticate

4. Use SDK Features

Commands

Output Formats

App Management

Initialization

Authentication

Entity Management

Model Discovery

Entity Parameter Examples

BPM (Business Process Management)

BPM Parameter Examples

Workflow

S3 Storage

Configuration

File Locations

Multi-App Workflow

Development

Testing Example

Architecture

License