hap-cli

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

Installation

pip install hap-cli

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

Prerequisite: enable CLI access for your organization

hap can only access an organization's data after the organization has enabled CLI access. Ask an organization administrator to turn on the switch under Organization Admin → Security → Data & Access → CLI access policy. Commands are blocked until it is enabled; once an administrator turns it on, just re-run the command. Use hap auth list-my-orgs to see each organization's status (CLI:on/off).

Quick start

1. Login

# 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.

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:

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

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 switches the default organization; moving to a different organization also clears the default app (apps belong to an organization). Pick a new one with hap app select.

3. Explore worksheets and records

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

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. The summary below covers the top-level groups; run hap <group> --help to discover every subcommand.

auth — authentication & session

app — application management

worksheet — worksheets, views, custom actions, charts

worksheet record — record CRUD

workflow — process & node management

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

custom-page — custom pages

contact — contacts & address book

department — directory

post — feed posts

calendar — calendar & events

chat — chat & messaging

group — chat group lifecycle

region — administrative regions

icon — built-in icon catalogue

attachment — stored files

ADDRESS is the file's link — one that has already stopped working is fine, paste it as-is — or just the path part of it. The file itself does not expire, only the link does, so a dead link can always be revived.

guide — built-in usage guide

upload — file upload

A cross-feature capability — the same descriptors can be attached to a worksheet Attachment field, a post, a calendar event, or a comment. The returned url is a temporary address for your own immediate use and stops working at urlExpiresAt; never send it to anyone. To share a file, attach it where it belongs — e.g. hap chat send-to-one --file <path>. Use --files '[{"name":"cover.png","url":"https://..."}]' to set display names; --worksheet-id / --app-id refine upload-token routing.

config — local CLI settings

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.

update — keep the CLI current

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 switches the default organization; switching to a different organization also clears the default app.

REPL mode

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

# 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.