Metadata-Version: 2.4
Name: hap-cli
Version: 0.8.3
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
Requires-Dist: pycryptodome>=3.15
Requires-Dist: python-socketio[client]>=5.10
Requires-Dist: PyYAML>=6.0
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# hap-cli

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

## Installation

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

The package ships with the v3 tool schemas it needs, so no extra setup is
required after `pip install`.

## Quick start

### 1. Login

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

# Specific environment
hap auth login mingdao                       # production
hap auth login nocoly                        # Nocoly SaaS
hap auth login https://hap.example.com       # self-hosted

# Non-interactive (scripts / headless servers)
hap auth login https://your-server.com --token YOUR_TOKEN
```

The browser flow opens the MingDAO login page and captures the token. If the
callback can't reach the CLI (no GUI, restricted network), interrupt the
command — it falls back to a paste prompt for the token shown on the success
page.

```bash
hap auth whoami        # current user + current environment/account + org
hap auth logout        # log out the current account
```

#### Multiple environments / accounts

You can stay logged in to several environments (MingDAO SaaS, Nocoly, self-hosted) and
several accounts at once. Each is saved under a name and you switch between them:

```bash
hap auth login mingdao --profile work-prod        # log in and save under a name
hap auth login https://hap.example.com --profile onprem
# Omit --profile and the name is derived from the login address, so logging
# into a new environment never overwrites one you already saved.

hap auth accounts                  # list saved environments/accounts (current marked *)
hap auth use work-prod             # switch the environment/account used next
hap --profile onprem app list      # use one environment/account for a single command
HAP_PROFILE=onprem hap app list    # default a whole shell session to one

hap auth logout -p onprem          # log out a specific account
hap auth logout --all              # log out every account
```

Profile resolution order: `--profile` > the `HAP_PROFILE` env var > the current profile.

### 2. Pick an organization and app

```bash
hap auth list-my-orgs                # current org marked with *
hap auth set-current-org ORG_ID           # switch the saved current org
hap app list                         # uses the saved current org
hap app list --org-id ORG_ID         # explicit override

# Save a default app so every --app-id can be omitted
hap app select APP_ID
hap app unselect                     # clear it
```

`hap auth set-current-org` only changes the default organization. The default app
is managed independently with `hap app select` / `hap app unselect`.

### 3. Explore worksheets and records

```bash
hap app info APP_ID                          # sections, worksheets, custom pages
hap worksheet list                           # uses the default app
hap worksheet info WORKSHEET_ID              # full structure (settings + fields)
hap worksheet field-types                    # reference for field type IDs
hap worksheet record list WORKSHEET_ID --page-size 10
```

### 4. JSON output

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

Every command supports `--json` for machine-readable output.

---

## Commands

The full authoritative list lives in [hap-cli-command.md](../hap-cli-command.md).
The summary below covers the top-level groups; run `hap <group> --help` to
discover every subcommand.

### auth — authentication & session

| Command | Description |
|---|---|
| `auth login [SERVER]` | Browser login (`--token` for scripted login; `--profile NAME` saves under a name, auto-named if omitted; `--force` repoints an existing name) |
| `auth accounts` | List saved environments/accounts (current marked `*`) |
| `auth use NAME` | Switch the environment/account used next |
| `auth logout` | Log out the current account (`-p NAME` for a specific one, `-a/--all` for every one) |
| `auth whoami` | Show current user, current environment/account, and current organization |
| `auth list-my-orgs` | List every org for the current account (current marked `*`) |
| `auth set-current-org ORG_ID` | Switch the saved current organization |

### app — application management

| Command | Description |
|---|---|
| `app list` | List apps in the org (default app marked `*`) |
| `app list-managed` | Apps where the current user is admin |
| `app info APP_ID` | App detail with sections, worksheets, custom pages |
| `app create / update / delete` | App lifecycle |
| `app select APP_ID` / `app unselect` | Manage the default app used when `--app-id` is omitted |
| `app create-section / edit-section / delete-section` | Section management |
| `app sort-sections / sort-worksheets` | Reorder sections / a section's worksheets |
| `app create-item` | Batch-create empty worksheets / custom pages |
| `app backup / restore / export / exports / backup-logs` | Backup & export |
| `app usage / logs` | Statistics and operation logs |
| `app role …` | Role CRUD, permissions, members, leave-all, applications |
| `app optionset …` | Option set CRUD and cross-app moves |
| `app knowledge list / search` | Vector knowledge bases |

### worksheet — worksheets, views, custom actions, charts

| Command | Description |
|---|---|
| `worksheet list / info / fields / field-types` | Discover structure |
| `worksheet create / update / copy / delete` | Worksheet lifecycle |
| `worksheet rules / save-rule` | Business rules |
| `worksheet switches / edit-switch` | Feature switches |
| `worksheet form-settings / save-form-settings` | Form submission settings |
| `worksheet custom-actions / create-custom-action / delete-custom-action` | Custom action buttons |
| `worksheet create-chart` | Build a statistics chart on a worksheet |
| `worksheet view list / info / create / copy / delete / sort` | View management |

### worksheet record — record CRUD

| Command | Description |
|---|---|
| `worksheet record list / get` | Query and read |
| `worksheet record create / update / delete` | Single-row CRUD |
| `worksheet record batch-create / batch-update` | Bulk operations (main-site path; relation/sub-table cells persist) |
| `worksheet record relations / share-link` | Linked records and share URLs |
| `worksheet record discussions / add-discussion / delete-discussion` | Discussion threads |
| `worksheet record logs` | Per-record change log |
| `worksheet record pivot / bottom-stats` | Aggregations and summary rows |

### workflow — process & node management

| Command | Description |
|---|---|
| `workflow list / get / structure / history / groups / stats` | Inspect |
| `workflow create / update / copy / move / delete` | Lifecycle |
| `workflow publish / rollback` | Versioning |
| `workflow trigger / trigger-pbp` | Manual trigger |
| `workflow config-get / config-set` | Global config |
| `workflow create-approval / update-approval / delete-approval` | Approval blocks |
| `workflow node …` | Node CRUD, batch-add / batch-update / batch-delete (and `*-approval` variants), test-code / test-webhook / test-ai, controls, types, code templates |

> Always run `hap workflow structure PROCESS_ID` before computing insertion
> points, branch IDs, or approval block IDs. Don't fabricate node / block /
> branch IDs.

### approval — approvals & todos

| Command | Description |
|---|---|
| `approval todo / todo-count / todo-filters / archived` | Pending and archived |
| `approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail` | Read instance state |
| `approval approve / reject / submit / sign / forward / urge` | Act on a task |
| `approval revoke / terminate / restart / retry` | Lifecycle |
| `approval batch / retry-batch / end-batch` | Bulk variants |
| `approval list-types` | Enum reference |
| `approval delegation create / list / list-by-company / list-by-principals / update` | Delegation CRUD |

### custom-page — custom pages

| Command | Description |
|---|---|
| `custom-page info / save / update-config` | Read and write the layout |
| `custom-page create / rename / copy / delete` | Lifecycle |
| `custom-page component-types` | Component reference |

### contact — contacts & address book

| Command | Description |
|---|---|
| `contact search / resolve` | Find members by keyword / name / email / phone |
| `contact friends / friend-requests` | Address book |
| `contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend` | Friend management |

### department — directory

| Command | Description |
|---|---|
| `department list / tree / info / members / search` | Organization directory queries |

### post — feed posts

| Command | Description |
|---|---|
| `post list / search / get` | Read |
| `post create / update / delete` | Author |
| `post comment / comments / comment-delete` | Comments |
| `post like / likes / favorite` | Reactions |
| `post pin / unpin / pinned` | Pinning |
| `post topics` | Topic-tag autocomplete |

### calendar — calendar & events

| Command | Description |
|---|---|
| `calendar list / get / create / update / delete` | Event lifecycle |
| `calendar categories` | Built-in categories |
| `calendar add-member / remove-member` | Membership |

### chat — chat & messaging

| Command | Description |
|---|---|
| `chat list` | Recent sessions |
| `chat messages` | 1-on-1 / group / inbox messages |
| `chat files` | Files shared in a chat |
| `chat send-to-one` | Send a plain-text message to one or more users (1-on-1) |
| `chat send-to-group` | Send a plain-text message to a group chat |
| `chat card-detail` | Resolve embedded card references |

### group — chat group lifecycle

| Command | Description |
|---|---|
| `group info GROUP_ID` | Group metadata |
| `group create` | Create a new group (`--name`, `--org-id`, optional `--member`) |
| `group add-member` | Add one or more members (`--group-id`, `--account-id`) |
| `group remove-member` | Remove a single member (`--group-id`, `--account-id`) |

### region — administrative regions

| Command | Description |
|---|---|
| `region get` | Look up regions by `--id` or `--search` keyword |

### icon — built-in icon catalogue

| Command | Description |
|---|---|
| `icon search` | Search icons by Chinese/English keyword (OR across terms, more matches rank higher); no keyword lists all |
| `icon list` | List every icon with its keywords |

### upload — file upload

| Command | Description |
|---|---|
| `upload [SOURCES...]` | Upload local paths or http(s) URLs to the file store; prints neutral uploaded-file descriptors (fileID/key/url/serverName/filePath/fileName/fileExt/originalFileName/fileSize) |

> A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a chat message, a post, a calendar event, or a comment. Use `--files '[{"name":"cover.png","url":"https://..."}]'` to set display names; `--worksheet-id` / `--app-id` refine upload-token routing.

### config — local CLI settings

| Command | Description |
|---|---|
| `config show` | Display the current configuration summary |
| `config completion [bash\|zsh\|fish] [--install]` | Enable `<Tab>` completion |
| `config language [LANG]` | Switch UI language (`en` / `zh-Hans` / `zh-Hant` / `ja`) |
| `config log on / off / status` | Toggle and inspect API logging |
| `config log level LEVEL` | `DEBUG / INFO / WARNING / ERROR / CRITICAL` |
| `config log view [--lines N] [--no-follow]` | Tail the log file |

Logs land in `~/.hap-cli/hap-cli.log` (10 MB × 3, rotating). When enabled,
every HAP API call is logged at `INFO` with URL, request body, response
body, and a redacted `Authorization` header (first 16 chars). `password`
and other sensitive keys are masked. `HAP_LOG_LEVEL=DEBUG` temporarily
overrides the persisted level.

---

## Default app & organization

Every command that needs an `--app-id` resolves it in this order:

1. The explicit `--app-id` you passed;
2. The default app saved by `hap app select`;
3. Otherwise the command exits with an error suggesting `hap app select APP_ID`.

`hap auth set-current-org` changes the default *organization* only — it does not
touch the default app.

## REPL mode

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

Drop the leading `hap`. Prefix `--json` to switch to JSON output for one
command.

## Examples

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

# Build a workflow
hap workflow create --name "My Flow" --app-id APP_ID
hap workflow node add PROCESS_ID --type 4 --name "Manager Approval"
hap workflow node save PROCESS_ID NODE_ID --config '{"accounts":[...]}'
hap workflow publish PROCESS_ID
hap workflow trigger PROCESS_ID --source-id ROW_ID

# Approve / reject
hap approval todo --type 4
hap approval approve INSTANCE_ID --opinion "Looks good"
hap approval reject INSTANCE_ID --opinion "Need revision"
hap approval batch --action 4 -s ID1 -s ID2

# Roles
hap app role list
hap app role add-member ROLE_ID -u USER_ID

# Knowledge base search
hap app knowledge search --keyword "onboarding" --mode hybrid
```

## Project layout

```
hap_cli/
  commands/   thin Click layer — argument parsing & output formatting only
  core/       business logic (transport, payload assembly, parsing)
  core/v3/    v3 dispatcher — builds Click commands from sources/v3-api-schema/*.yaml
  locale/     translation catalog (English-only at the moment)
sources/v3-api-schema/
              OpenAPI v3 specs (apifox stable list) + INDEX.json,
              copied into the wheel at build time
docs/         end-user documentation
```

## License

Apache 2.0.
