Metadata-Version: 2.4
Name: hap-cli
Version: 0.6.0
Summary: CLI harness for MingDAO HAP - Enterprise no-code platform
Author: hap-cli
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Provides-Extra: crypto
Requires-Dist: pycryptodome>=3.15; extra == "crypto"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# hap-cli

CLI harness for **MingDAO HAP** (明道云) - an enterprise no-code platform (hap).

## Installation

```bash
pip install hap-cli
```

## Quick Start

### 1. Login

**Option A: Browser login (recommended)**

```bash
# MingDAO SaaS (default)
hap auth login

# Specify server
hap auth login mingdao    # MingDAO
hap auth login nocoly     # Nocoly
hap auth login https://hap.example.com   # Self-hosted
```

Opens your browser to the MingDAO login page. After login, the token is saved automatically, your organizations are fetched immediately, and the first org is stored as the current org.

**Option B: Manual token**

```bash
hap auth set \
  --server https://your-mingdao-server.com \
  --token YOUR_MD_PSS_ID_TOKEN
```

**Other auth commands**

```bash
hap auth whoami    # Show current user info
hap auth logout    # Clear saved token
```

### 2. Find your org and app IDs

```bash
hap auth list-my-orgs                 # list orgs, current one is marked with *
hap auth switch-org ORG_ID            # switch the saved current org
hap app list                          # uses the saved current org by default
hap app list --org-id ORG_ID          # or override it explicitly
hap app list-managed                  # also uses the saved current org
hap app list-managed --org-id ORG_ID  # explicit org override
```

### 3. List worksheets

```bash
hap app worksheets APP_ID
```

### 4. Query records

```bash
hap worksheet record list WORKSHEET_ID --page-size 10
```

### 5. JSON output (for automation)

```bash
hap --json worksheet record list WORKSHEET_ID
```

## Commands

### auth — Authentication & Session

| Command | Description |
|---|---|
| `auth login` | Login via browser |
| `auth logout` | Clear saved auth token |
| `auth set` | Set server address and auth token |
| `auth show` | Show current configuration |
| `auth whoami` | Show current logged-in user info |
| `auth list-my-orgs` | List all organizations for current user |
| `auth switch-org` | Switch saved current organization |

### app — Application Management

| Command | Description |
|---|---|
| `app list` | List applications in organization |
| `app list-managed` | List apps where current user is admin |
| `app info` | Get application info |
| `app worksheets` | List worksheets in an application |
| `app create` | Create a new application |
| `app update` | Update application info |
| `app delete` | Delete an application |
| `app add-section` | Add a section to an application |
| `app edit-section` | Edit section name |
| `app delete-section` | Delete an application section |
| `app backup` | Backup an application |
| `app restore` | Restore application from backup |
| `app export` | Batch export applications |
| `app exports` | List export records for an application |
| `app backup-logs` | Get backup/restore operation logs |
| `app usage` | Get application usage statistics |
| `app logs` | Get application operation logs (org-level; pass APP_ID to filter) |

#### app optionset — Option Set Management

| Command | Description |
|---|---|
| `app optionset list` | List option sets for an application |
| `app optionset get` | Get option set details |
| `app optionset save` | Create or update an option set |
| `app optionset delete` | Delete (or disable) an option set |
| `app optionset move` | Move an option set to another application |

#### app role — Role Management

| Command | Description |
|---|---|
| `app role list` | List roles for an application |
| `app role permissions` | Get role details and permissions |
| `app role create` | Create a new role |
| `app role rename` | Rename a role |
| `app role delete` | Delete a role |
| `app role set-permissions` | Edit role permissions |
| `app role add-member` | Add member to a role |
| `app role remove-member` | Remove member from a role |
| `app role apply` | Apply to join a role |
| `app role approve` | Approve role application |
| `app role reject` | Reject role application |
| `app role pending` | Get pending role applications |

### worksheet — Worksheet Operations

| Command | Description |
|---|---|
| `worksheet info` | Get worksheet information |
| `worksheet fields` | List worksheet fields/controls |
| `worksheet views` | List worksheet views |
| `worksheet view-detail` | Get detailed configuration of a single view |
| `worksheet create` | Create a new worksheet |
| `worksheet update` | Update worksheet alias and/or description |
| `worksheet copy` | Copy a worksheet |
| `worksheet add-view` | Create a new view |
| `worksheet delete-view` | Delete a view |
| `worksheet copy-view` | Copy a view |
| `worksheet sort-views` | Reorder views |
| `worksheet buttons` | Get custom action buttons for a worksheet |
| `worksheet save-button` | Create or update a custom action button |
| `worksheet delete-button` | Delete a custom action button |
| `worksheet rules` | Get business rules for a worksheet |
| `worksheet save-rule` | Save a single business rule |
| `worksheet switches` | Get feature switches for a worksheet |
| `worksheet edit-switch` | Edit a single feature switch |
| `worksheet form-settings` | Get worksheet form submission/advanced settings |
| `worksheet save-form-settings` | Update worksheet form submission/advanced settings |
| `worksheet save-fields` | Save the complete fields/controls list for a worksheet |
| `worksheet field-types` | Show field type constants reference table |

#### worksheet record — Record CRUD

| Command | Description |
|---|---|
| `worksheet record list` | Query records (with filtering and pagination) |
| `worksheet record get` | Get a single record by ID |
| `worksheet record create` | Create a new record |
| `worksheet record update` | Update a record |
| `worksheet record delete` | Delete record(s) by ID |
| `worksheet record discussions` | Get discussions/comments for a record |
| `worksheet record add-discussion` | Add a discussion/comment to a record |
| `worksheet record delete-discussion` | Delete a discussion/comment |
| `worksheet record logs` | Get operation logs for a record |
| `worksheet record pivot` | Get pivot table data via statistics service |
| `worksheet record bottom-stats` | Get worksheet bottom summary statistics |

### workflow — Workflow Management

| Command | Description |
|---|---|
| `workflow list` | List workflows in an application |
| `workflow get` | Get workflow details |
| `workflow create` | Create a new workflow |
| `workflow update` | Update workflow info |
| `workflow copy` | Copy/clone a workflow |
| `workflow move` | Move a workflow to another application |
| `workflow delete` | Delete a workflow |
| `workflow publish` | Publish (enable) or disable a workflow |
| `workflow rollback` | Rollback to previous version |
| `workflow history` | Get workflow version history |
| `workflow config-get` | Get workflow global configuration |
| `workflow config-set` | Save workflow global configuration (JSON string) |
| `workflow trigger` | Trigger/start a workflow by process ID |
| `workflow trigger-pbp` | Trigger a PBP (packaged business process) workflow |
| `workflow stats` | Get workflow usage statistics |
| `workflow groups` | List workflow groups |

#### workflow node — Workflow Node Management

| Command | Description |
|---|---|
| `workflow node list` | List all nodes in a workflow |
| `workflow node get` | Get node details/configuration |
| `workflow node add` | Add a node to a workflow |
| `workflow node delete` | Delete a node from a workflow |
| `workflow node rename` | Rename a node |
| `workflow node desc` | Update node description/alias |
| `workflow node save` | Save full node configuration (JSON string) |
| `workflow node save-action` | Configure data operation node (add/edit/delete records) |
| `workflow node save-search` | Configure search node (get single record) |
| `workflow node save-get-more` | Configure get-more-records node |
| `workflow node controls` | Get worksheet fields/controls available for node config |
| `workflow node form-property` | Get node form property |
| `workflow node sub-processes` | List available sub-processes |
| `workflow node test-code` | Test a code block node |
| `workflow node test-webhook` | Test a WebHook node |
| `workflow node test-ai` | Test an AI text generation node |
| `workflow node json-to-controls` | Convert JSON to workflow controls |
| `workflow node code-templates` | List code templates |
| `workflow node create-code-template` | Create a code template |
| `workflow node types` | Show all available node types and action IDs |
| `workflow node list-types` | List NODE_TYPE enum as a table |

### approval — Approval Management

| Command | Description |
|---|---|
| `approval todo` | List pending tasks |
| `approval todo-count` | Get pending workflow task count |
| `approval todo-filters` | Advanced pending list (full RequestTodo filters) |
| `approval archived` | List archived processes |
| `approval history` | Get workflow execution history |
| `approval history-detail` | Get execution history detail (with node info) |
| `approval get` | Get process instance details |
| `approval work-item` | Get work items for a process instance |
| `approval operations` | Get available operations for a task |
| `approval op-history` | Get operation history for a process instance |
| `approval approve` | Approve a workflow task |
| `approval reject` | Reject a workflow task |
| `approval submit` | Submit a fill-in task |
| `approval sign` | Add a co-signer to a task |
| `approval forward` | Forward a task to another user |
| `approval urge` | Send a reminder for a pending task |
| `approval revoke` | Revoke a submitted process instance |
| `approval terminate` | Terminate a running process instance |
| `approval restart` | Restart a completed/rejected process |
| `approval retry` | Retry a failed process instance |
| `approval batch` | Batch approve or reject tasks |
| `approval retry-batch` | Batch retry failed process instances |
| `approval end-batch` | Batch terminate process instances |
| `approval list-types` | Show approval-related enum values (operationType etc.) |

#### approval delegation — Approval Delegation

| Command | Description |
|---|---|
| `approval delegation create` | Create a delegation |
| `approval delegation list` | List current user's delegations |
| `approval delegation list-by-company` | List all delegations in organization |
| `approval delegation list-by-principals` | List delegations for specified principals |
| `approval delegation update` | Edit delegation; pass `--status 0` to end |

### custom-page — Custom Page Management

| Command | Description |
|---|---|
| `custom-page info` | Get saved custom page layout |
| `custom-page create` | Create a new custom page |
| `custom-page rename` | Edit custom page meta info |
| `custom-page copy` | Copy a custom page |
| `custom-page delete` | Delete a custom page |
| `custom-page save` | Save complete custom page layout |
| `custom-page update-config` | Update custom page metadata (description/config) |
| `custom-page component-types` | Show available custom page component types (reference) |

### contact — Contacts & Address Book

| Command | Description |
|---|---|
| `contact search` | Search contacts and departments |
| `contact resolve` | Resolve accountId by name/email/phone |
| `contact friends` | List contacts in address book |
| `contact friend-requests` | List pending friend requests |
| `contact add-friend` | Send a friend request |
| `contact accept-friend` | Accept a friend request |
| `contact reject-friend` | Reject a friend request (notifies requester) |
| `contact ignore-friend` | Silently ignore a pending friend request |
| `contact remove-friend` | Remove a friend from address book |

### department — Department Queries

| Command | Description |
|---|---|
| `department list` | List sub-departments |
| `department tree` | Get full department tree |
| `department info` | Get department details |
| `department members` | Get department members |
| `department search` | Search departments and users |

### post — Feed Posts

| Command | Description |
|---|---|
| `post list` | List feed posts |
| `post get` | Get post details |
| `post create` | Create a new post |
| `post update` | Update a post |
| `post delete` | Delete a post |
| `post search` | Search posts by keyword and date range |
| `post pinned` | List pinned posts |
| `post top` | Pin or unpin a post |
| `post like` | Like or unlike a post |
| `post favorite` | Favorite or unfavorite a post |
| `post comments` | List comments on a post |
| `post comment` | Add a comment to a post |

### calendar — Calendar Management

| Command | Description |
|---|---|
| `calendar list` | List calendar events within a date range (filterable) |
| `calendar get` | Get calendar event details |
| `calendar create` | Create a new calendar event |
| `calendar update` | Update a calendar event |
| `calendar delete` | Delete a calendar event |
| `calendar categories` | List calendar categories |
| `calendar add-member` | Add member to a calendar event |
| `calendar remove-member` | Remove member from a calendar event |

### chat — Chat & Messaging

| Command | Description |
|---|---|
| `chat list` | List recent chat sessions |
| `chat history` | Get 1-on-1 or group chat history |
| `chat send` | Send a message to one or more users |
| `chat send-file` | Send a file to a chat (supports both 1-on-1 and group) |
| `chat send-card` | Send a card to a chat (supports both 1-on-1 and group) |
| `chat card-detail` | Resolve card references embedded in chat messages |
| `chat start` | Start a 1-on-1 chat with another user |

#### chat group — Group Management

| Command | Description |
|---|---|
| `chat group list` | List groups |
| `chat group info` | Get group information |
| `chat group create` | Create a group chat (supports keyword member resolution, at least 2 members) |
| `chat group update` | Update group name and/or announcement |
| `chat group delete` | Disband a group |
| `chat group members` | List group members |
| `chat group remove-member` | Remove member from a group |
| `chat group files` | List files in a group |

## Workflow Management

```bash
# Create a workflow
hap workflow create --company-id CID --name "My Flow" --app-id APP_ID

# Add an approval node
hap workflow node add PROCESS_ID --type 4 --name "Manager Approval"

# Configure the node
hap workflow node save PROCESS_ID NODE_ID --type 4 --config '{"accounts":[...]}'

# Test a code node
hap workflow node test-code PROCESS_ID NODE_ID --code "return 1+1"

# Test a webhook node
hap workflow node test-webhook PROCESS_ID NODE_ID --url https://api.example.com

# Publish the workflow
hap workflow publish PROCESS_ID

# Trigger it
hap workflow trigger PROCESS_ID --source-id ROW_ID

# Check version history
hap workflow history PROCESS_ID

# Rollback to previous version
hap workflow rollback PROCESS_ID

# Get/set global config
hap workflow config-get PROCESS_ID
hap workflow config-set PROCESS_ID --config '{"allowRevoke":true}'
```

## Approval & Todo

```bash
# Check pending task count
hap approval todo-count

# List pending approval tasks
hap approval todo --type 4

# View instance detail
hap approval get INSTANCE_ID

# Approve
hap approval approve INSTANCE_ID --opinion "Looks good"

# Reject with reason
hap approval reject INSTANCE_ID --opinion "Need revision"

# Forward to another user
hap approval forward INSTANCE_ID --to USER_ID

# Add co-signer
hap approval sign INSTANCE_ID --to USER_ID --before

# Batch approve
hap approval batch --action 4 -s ID1 -s ID2

# View execution history
hap approval history --process-id PROCESS_ID --status 2
```

## REPL Mode

```bash
hap repl
hap> worksheet record list WORKSHEET_ID
hap> --json workflow list APP_ID
hap> approval todo-count
hap> quit
```

## API Authentication

The CLI uses MingDAO's `md_pss_id` session token. Use `hap auth login` for
browser-based login, or `hap auth set --token TOKEN` to set the token manually.

Commands that expose `--org-id` will use the saved current org when you omit the option.

For private deployments with encrypted API responses, install crypto support:

```bash
pip install hap-cli[crypto]
```

## More Examples

```bash
# List orgs, then apps
hap auth list-my-orgs
hap app list
hap auth switch-org ORG_ID
hap app list-managed

# Get worksheet fields
hap worksheet fields WORKSHEET_ID

# Create a record
hap worksheet record create WORKSHEET_ID -f "c001=value1" -f "c002=value2"

# Copy a workflow
hap workflow copy PROCESS_ID --name "Copy of Flow"

# Move workflow to another app
hap workflow move PROCESS_ID TARGET_APP_ID

# List code templates
hap workflow node code-templates --keyword "email"

# Test AI node
hap workflow node test-ai PROCESS_ID NODE_ID --prompt "Summarize this" --model gpt-4

# Manage app roles
hap app role list APP_ID
hap app role add-member APP_ID ROLE_ID -u USER_ID

# Manage option sets
hap app optionset list APP_ID

# Manage chat groups
hap chat group list

# Terminate a stuck instance
hap approval terminate INSTANCE_ID --yes

# Retry a failed instance
hap approval retry INSTANCE_ID
```
