Metadata-Version: 2.4
Name: hap-cli
Version: 0.6.6
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, your organizations are fetched immediately, and the first org is stored as the current org.

**Option B: Manual token (headless / scripted)**

```bash
hap auth login https://your-mingdao-server.com --token YOUR_PERSONAL_ACCESS_TOKEN
```

If the browser flow is running but the callback never reaches the CLI (e.g. remote
server, restrictive firewall), interrupt the command (the usual shell interrupt
shortcut for your terminal) to fall back to an interactive paste prompt for the
token shown on the success page.

**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 (use `--token` for scripted login) |
| `auth logout` | Clear saved auth token |
| `auth whoami` | Show current logged-in user and current organization |
| `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 by keyword within an organization |
| `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 (`--topic-id` filters by topic tag) |
| `post search` | Search posts by keyword and date range (`--topic-id` filters by topic tag) |
| `post get` | Show a post with its comment thread |
| `post create` | Create a new post |
| `post update` | Edit a post's content |
| `post delete` | Delete a post |
| `post comment` | Add a comment to a post |
| `post comments` | List all comments on a post |
| `post comment-delete` | Delete a comment |
| `post like` | Like a post (`--remove` to unlike) |
| `post likes` | List users who liked a post |
| `post favorite` | Favorite a post (`--remove` to unfavorite) |
| `post pin` | Pin a post (`--hours` for duration) |
| `post unpin` | Unpin a post |
| `post pinned` | List pinned posts |
| `post topics` | List topic tags (autocomplete) |

### 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 files` | List files shared in a 1-on-1 or group chat |
| `chat messages` | Fetch 1-on-1, group, or inbox (system / app / workflow / ...) messages |
| `chat send` | Send a message to one or more users |
| `chat group-info` | Get information about a chat group |
| `chat card-detail` | Resolve card references embedded in chat messages |

## 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 login --token TOKEN` to supply a token
non-interactively (e.g. on a headless server).

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

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

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