hap-cli 0.8.7

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.

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

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 *; each row shows whether the org allows CLI access, CLI:on/off, checked live; omitted where the environment has no such switch)
auth set-current-org ORG_ID	Switch the saved current organization (clears the default app when the org changes)

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 / 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); fewer than 10 matches get random suggestions appended; no keyword lists all
icon list [-n SIZE] [-p PAGE]	List icons page by page with keywords (50 per page by default)

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.

update — keep the CLI current

Command	Description
update	Check PyPI for a newer release and upgrade in place, using the same tool the CLI was installed with (pip / pipx / uv)
update --check	Only report whether a newer version exists, without installing

---

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.