@amaster.ai/runtime-cli 1.1.0-beta.73 → 1.1.0-beta.75

package/README.md

@@ -1,15 +1,17 @@
 # @amaster.ai/runtime-cli
 
-Unified CLI for Amaster SDK and OpenClaw integration. Manage entities, BPM processes, workflows, S3 files, authentication, and OpenClaw skills 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 files from a single command-line interface.
 
 ## Features
 
-- **Authentication**: Login, logout, register users, manage sessions
-- **Entity Management**: CRUD operations on entities with type-safe API
+- **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**: Execute and monitor workflows
 - **S3 Storage**: Upload, download, list, and manage files
-- **OpenClaw Integration**: Initialize app-specific skills and MCP servers for AI assistants
+- **OpenClaw Integration**: Initialize app-specific skills and MCP servers
 
 ## Installation
 
@@ -25,11 +27,11 @@ npx @amaster.ai/runtime-cli
 
 ### Automatic Cleanup
 
-When you uninstall `@amaster.ai/runtime-cli`, it will automatically clean up the OpenClaw integration for the configured app:
+When you uninstall `@amaster.ai/runtime-cli`, it will automatically clean up:
 
 ```bash
 npm uninstall -g @amaster.ai/runtime-cli
-# Automatically removes skills and MCP servers
+# Automatically removes auth sessions
 ```
 
 To skip automatic cleanup:
@@ -40,206 +42,394 @@ npm_config_ignore_scripts=1 npm uninstall -g @amaster.ai/runtime-cli
 
 ## Quick Start
 
-### 1. Configure the CLI
+### 1. Initialize an App
 
 ```bash
-# Set your API key
-amaster config set apiKey YOUR_API_KEY
+# Initialize a new app
+amaster init --app-code myapp --url https://myapp.helige.cn
 
-# Set base URL (optional, defaults to https://api.amaster.ai)
-amaster config set baseURL https://api.amaster.ai
+# 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)
 
-# View configuration
-amaster config list
+```bash
+# Set default app for subsequent commands
+amaster use myapp
+
+# List all configured apps
+amaster apps
 ```
 
-### 2. Authenticate
+### 3. Authenticate
 
 ```bash
-# Login
-amaster login
+# Login (interactive - will prompt for username/email and password)
+amaster login --app myapp
 
-# Or with options
-amaster login --email user@example.com --password secret
+# Login with email
+amaster login --app myapp -e user@example.com -p secret
 
-# Check who you are
-amaster whoami
+# Login with username
+amaster login --app myapp -u admin -p secret
+
+# Check current user
+amaster whoami --app myapp
+
+# Logout
+amaster logout --app myapp
 ```
 
-### 3. Use SDK Features
+### 4. Use SDK Features
 
 ```bash
-# List entities
-amaster entity list myapp users
+# List entities - full JSON output (default)
+amaster entity list default products --app myapp
 
-# Get a specific entity
-amaster entity get myapp users 123
+# Human-friendly output
+amaster entity list default products --app myapp --format pretty
 
-# Create an entity
-amaster entity create myapp users --data '{"name":"John","email":"john@example.com"}'
+# Table output
+amaster entity list default products --app myapp --format table
 
-# List BPM processes
-amaster bpm processes
+# Newline-delimited JSON
+amaster entity list default products --app myapp --format ndjson
 
-# Start a process
-amaster bpm start my-process --variables '{"key":"value"}'
+# CSV output
+amaster entity list default products --app myapp --format csv
 
-# List workflows
-amaster workflow list
+# List entities with pagination
+amaster entity list default products --app myapp --page 1 --page-size 10
 
-# Execute a workflow
-amaster workflow execute my-workflow --input '{"data":"value"}'
+# 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
 
-# List S3 files
-amaster s3 list
+# Multi-order sorting
+amaster entity list default products --app myapp \
+  --orders created_at:desc,name:asc
 
-# Upload a file
-amaster s3 upload ./myfile.pdf --bucket mybucket --key documents/myfile.pdf
-```
+# Keyword search in specific fields
+amaster entity list default products --app myapp \
+  --keyword keyboard \
+  --keyword-fields name,description
 
-### 4. Setup OpenClaw Integration
+# Advanced filter via JSON or @file
+amaster entity list default products --app myapp \
+  --filter '{"conjunction":"and","children":[]}'
 
-Initialize OpenClaw integration for a specific app (downloads app-specific skills and MCP servers):
+# Offset/limit pagination
+amaster entity list default products --app myapp --limit 20 --offset 40
 
-```bash
-# Initialize for an app
-amaster init --app-code myapp
+# Raw query escape hatch for any remaining EntityQueryParams
+amaster entity list default products --app myapp \
+  --query '{"status":"active","orderBy":"created_at","orderDir":"desc"}'
 
-# With API key
-amaster init --app-code myapp --api-key YOUR_API_KEY
+# Get a specific entity
+amaster entity get default products 123 --app myapp
 
-# Force reinitialize
-amaster init --app-code myapp --force
-```
+# Create from inline JSON
+amaster entity create default products --app myapp \
+  --data '{"name":"Mechanical Keyboard","price":399}'
 
-Check integration status:
+# Create from @file
+amaster entity create default products --app myapp \
+  --data @./product-create.json
 
-```bash
-amaster doctor
-```
+# Update from inline JSON
+amaster entity update default products 123 --app myapp \
+  --data '{"price":499}'
 
-List installed components:
+# Update from @file
+amaster entity update default products 123 --app myapp \
+  --data @./product-update.json
 
-```bash
-amaster list
+# 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]'
 ```
 
-Switch to a different app:
+For `amaster entity list`, explicit options such as `--fields`, `--relations`, and `--order-by` override the same keys inside `--query`.
+
+## Commands
+
+### Output Formats
+
+Most commands support:
 
 ```bash
-amaster switch another-app
+--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
 ```
 
-Remove integration for current app:
+### App Management
 
 ```bash
-amaster uninstall --yes
+amaster apps                          # List all configured apps
+amaster use <app-code>                # Set the default app
 ```
 
-## Commands
-
-### Configuration
+### Initialization
 
 ```bash
-amaster config set <key> <value>    # Set config value
-amaster config get <key>            # Get config value
-amaster config list                 # List all config
+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
 
 ```bash
-amaster login [options]             # Login with email/password
-amaster logout                      # Logout
-amaster whoami                      # Show current user
-amaster register [options]          # Register new user
-amaster users [options]             # List users
+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
 
 ```bash
-amaster entity list <app> <entity> [options]
-amaster entity get <app> <entity> <id>
-amaster entity create <app> <entity> [options]
-amaster entity update <app> <entity> <id> [options]
-amaster entity delete <app> <entity> <id>
-amaster entity types <app>
+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)
+  -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
 ```
 
-### BPM
+#### Entity Parameter Examples
 
 ```bash
-amaster bpm processes               # List process definitions
-amaster bpm start <key> [options]   # Start process instance
-amaster bpm tasks [options]         # List tasks
-amaster bpm complete <id> [options] # Complete task
-amaster bpm claim <id> [options]    # Claim task
-amaster bpm instances               # List process instances
-amaster bpm instance <id>           # Get instance details
+# --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
 ```
 
-### Workflow
+### BPM (Business Process Management)
 
 ```bash
-amaster workflow list               # List workflows
-amaster workflow get <id>           # Get workflow details
-amaster workflow execute <id> [options]
-amaster workflow executions [options]
-amaster workflow execution <id>
+amaster bpm processes [options]       # List process definitions
+  --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
+
+amaster bpm tasks [options]           # List tasks
+  --app <app-code>                    # App code (uses default if not specified)
+  -a, --assignee <assignee>           # Filter by assignee
+
+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
 ```
 
-### S3 Storage
+### Workflow
 
 ```bash
-amaster s3 list [options]           # List files
-amaster s3 upload <file> [options]  # Upload file
-amaster s3 download <key> [options] # Download file
-amaster s3 delete <key> [options]   # Delete file
-amaster s3 url <key> [options]      # Get file URL
+amaster workflow list [options]       # List workflows
+  --app <app-code>                    # App code (uses default if not specified)
+
+amaster workflow execute <id> [options]  # Execute a workflow
+  --app <app-code>                    # App code (uses default if not specified)
+  -i, --input <json>                  # Workflow input as JSON
 ```
 
-### OpenClaw Integration
+### S3 Storage
 
 ```bash
-amaster init [options]              # Initialize integration for an app
-amaster doctor                      # Check integration status
-amaster list                        # List installed skills and MCP servers
-amaster switch <app-code> [options] # Switch to a different app
-amaster uninstall [options]         # Remove integration for current app
+amaster s3 list [options]             # List files
+  --app <app-code>                    # App code (uses default if not specified)
+  -b, --bucket <bucket>               # Bucket name
+
+amaster s3 upload <file> [options]    # Upload a file
+  --app <app-code>                    # App code (uses default if not specified)
+  -b, --bucket <bucket>               # Bucket name
+  -k, --key <key>                     # Object key
 ```
 
 ## Configuration
 
-Configuration is stored in `~/.amaster/cli-config.json`.
+Configuration files are stored in `~/.amaster/`:
 
-### Environment Variables
+### File Locations
 
-- `AMASTER_API_KEY` - Your Amaster API key
-- `AMASTER_BASE_URL` - Base URL for API (default: https://api.amaster.ai)
+- **App Config**: `~/.amaster/config.json`
+  ```json
+  {
+    "apps": {
+      "myapp": {
+        "baseURL": "https://myapp.helige.cn",
+        "initializedAt": "2025-03-26T..."
+      }
+    },
+    "currentApp": "myapp"
+  }
+  ```
+
+- **Auth Sessions**: `~/.amaster/auth-{appCode}.json`
+  ```json
+  {
+    "accessToken": "...",
+    "refreshToken": "...",
+    "loggedInAt": "2025-03-26T...",
+    "expiresIn": 86400
+  }
+  ```
+
+## Multi-App Workflow
 
-### File Locations
+```bash
+# Initialize multiple apps
+amaster init --app-code app1 --url https://app1.helige.cn
+amaster init --app-code app2 --url https://app2.helige.cn
 
-- CLI Config: `~/.amaster/cli-config.json`
-- OpenClaw Config: `~/.openclaw/config.json`
-- Installed Skills: `~/.openclaw/skills/{appCode}/`
-- Amaster Config: `~/.amaster/openclaw-config.json`
+# List all apps
+amaster apps
 
-## OSS Structure
+# Work with app1 (explicit)
+amaster entity list default products --app app1
 
-The CLI expects skills and MCP configurations to be organized by app code in OSS:
+# Set app2 as default
+amaster use app2
 
-```
-/openclaw/
-├── apps/
-│   ├── {appCode1}/
-│   │   ├── skills/
-│   │   │   ├── manifest.json       # Skills manifest for this app
-│   │   │   └── {skill-id}.zip      # Skill packages
-│   │   └── mcp-config.yaml         # MCP server config for this app
-│   └── {appCode2}/
-│       ├── skills/
-│       └── mcp-config.yaml
+# 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
@@ -256,6 +446,27 @@ 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:
+
+```bash
+# Login
+amaster login --app bleulig7o -e admin@example.com -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