hap-cli 0.7.1

CLI harness for MingDAO HAP - Enterprise no-code platform

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.

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 organization
hap auth logout        # clear the saved token

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 only changes the default organization. The default app is managed independently with hap app select / hap app unselect.

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

Command	Description
auth login [SERVER]	Browser login (use --token for scripted login)
auth logout	Clear the saved auth token
auth whoami	Show current user 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

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.