CLI Usage Guide

HAP CLI wraps HAP backend capabilities into a command-line interface, enabling automation and AI-driven operations across the platform.

It covers three major scenarios:

Collaboration & Communication
- Access contacts and departments
- Send and receive direct messages and group chats
- Publish posts
- Manage calendars
Application Data
- Read and write worksheet records (CRUD, filtering, pivot analysis)
- Execute workflows
- Handle approval to-dos
- Manage custom pages and roles/permissions
- Upload files
Application Modification
- Perform precise updates to existing applications
- Add fields, modify views, adjust workflows, etc.

When used with AI, CLI enables natural-language-driven control of the entire HAP platform.

Installation

pip install hap-cli

Prerequisite: Enable CLI Access

CLI access must be enabled at the organization level before hap can access data.

Organization administrators can enable it in:

Organization Admin Console > Security > Data & Access > CLI Access Policy

If disabled, CLI commands will be blocked.

You can check status via:

hap auth list-my-orgs

(CLI:on/off indicates whether CLI access is enabled.)

# Default HAP SaaS environment
hap auth login

# Explicit environment selection
hap auth login mingdao                       # Production
hap auth login nocoly                        # Nocoly SaaS
hap auth login https://hap.example.com       # HAP Server

Non-interactive login (scripts / headless servers)

hap auth login https://your-server.com --token YOUR_TOKEN

The browser flow will open for authentication and token retrieval.

If CLI cannot receive callback (e.g., no GUI or restricted network), cancel the command and manually paste the token shown in the browser.

```bash
hap auth whoami        # Current user, org, and environment
hap auth logout        # Log out current account

Multi-Environment / Multi-Account Support

HAP CLI supports multiple environments (Mingdao SaaS, Nocoly, HAP Server) and multiple accounts.

Each session can be saved as a named profile for reuse.

hap auth login mingdao --profile work-prod        # Log in and save as a named profile
hap auth login https://hap.example.com --profile onprem
# If --profile is omitted, a profile name is auto-generated from the server URL.
# New logins do not overwrite existing profiles.

hap auth accounts                  # List all environments/accounts (current one marked with *)
hap auth use work-prod             # Switch current active environment/account
hap --profile onprem app list      # Use a specific environment/account for this single command only
HAP_PROFILE=onprem hap app list    # Set default environment/account for the entire terminal session

hap auth logout -p onprem          # Log out of a specified account
hap auth logout --all              # Log out of all accounts

Profile priority order:

--profile > HAP_PROFILE environment variable > current active profile

Organization and Application Selection

hap auth list-my-orgs                     # Active organization marked with *
hap auth set-current-org ORG_ID           # Set default organization

hap app list                              # Use default organization
hap app list --org-id ORG_ID              # Override organization

# Set default application --app-id can be omitted in subsequent commands
hap app select APP_ID
hap app unselect                          # Clear default application

Switching default organization (hap auth set-current-org) will clear the default application, since applications belong to organizations. Use hap app select to set a new default app.

Browse Worksheets & Records

hap app info APP_ID                          # App structure overview (groups, worksheets and custom pages)
hap worksheet list                           # Worksheets in default app
hap worksheet info WORKSHEET_ID              # Full worksheet schema (fields + settings)
hap worksheet field-types                    # Field type reference
hap worksheet record list WORKSHEET_ID --page-size 10

JSON Output Mode

hap --json worksheet record list WORKSHEET_ID

All commands support --json for machine-readable output (useful for scripting and automation).

Default App and Organization Resolution

For any command requiring --app-id, resolution follows:

Explicit --app-id in command
Default app selected via hap app select APP_ID
Error if still not resolved (prompting user to set default app)

REPL Mode

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

hap prefix can be omitted
Prefix with --json to switch output format

Command Reference

You can use hap <group> --help at any level to view full subcommands.

auth — Authentication & Sessions

Command	Description
`auth login [SERVER]`	Browser-based login (`--token` for non-interactive mode; `--profile NAME` saves a named profile; `--force` reassigns an existing profile)
`auth accounts`	List all environments/accounts (current marked with `*`)
`auth use NAME`	Switch active environment/account
`auth logout`	Log out current account (`-p NAME` for specific one, `-a/--all` for all accounts)
`auth whoami`	Show current user, environment/account, and organization
`auth list-my-orgs`	List organizations under the current account (current marked with `*`, includes `CLI:on/off` status)
`auth set-current-org ORG_ID`	Set default organization (switching default org clears default app)

app — Application Management

Command	Description
`app list`	List applications in the organization (default app marked with `*`)
`app list-managed`	List applications where the user is an administrator
`app info APP_ID`	View application details (groups, worksheets, custom pages)
`app create / update / delete`	Application lifecycle operations
`app select APP_ID / unselect`	Set or clear default application
`app create-section / edit-section / delete-section`	Group management
`app sort-sections / sort-worksheets`	Reorder groups or worksheets
`app create-item`	Create empty worksheets or custom pages in batch
`app backup / export / exports / backup-logs`	Backup and export
`app usage / logs`	Usage statistics and operation logs
`app role …`	Role CRUD, permissions, members, leave-all, and requests
`app optionset …`	Option set CRUD and cross-app migration
`app knowledge list / search`	Application knowledge base

worksheet — Worksheets, Views, Custom Actions & Charts

Command	Description
`worksheet list / info / fields / field-types`	View worksheet structure
`worksheet create / update / copy / delete`	Worksheet lifecycle management
`worksheet rules / save-rule`	Business rules
`worksheet switches / edit-switch`	Function switch
`worksheet form-settings / save-form-settings`	Form submission and advanced settings
`worksheet custom-actions / create-custom-action / delete-custom-action`	Custom actions
`worksheet create-chart`	Create chart
`worksheet view list / info / create / copy / delete / sort`	View management

worksheet record — Record CRUD

Command	Description
`worksheet record list / get`	Query or retrieve records
`worksheet record create / update / delete`	Single record CRUD
`worksheet record batch-create / batch-update`	Batch operations (including subform and related records)
`worksheet record relations / share-link`	Related records and share links
`worksheet record discussions / add-discussion / delete-discussion`	Record comments
`worksheet record logs`	Single record change logs
`worksheet record pivot / bottom-stats`	Pivot analysis and summary statistics

workflow — Workflows & Nodes

Command	Description
`workflow list / get / structure / history / groups / stats`	View workflows
`workflow create / update / copy / move / delete`	Workflow lifecycle
`workflow publish / rollback`	Version management
`workflow trigger / trigger-pbp`	Manual trigger execution
`workflow config-get / config-set`	Global configuration
`workflow create-approval / update-approval / delete-approval`	Approval containers
`workflow node …`	Node CRUD, batch operations, testing (code/webhook/AI), controls, types, and code templates

approval — Approvals & To-dos

Command	Description
`approval todo / todo-count / todo-filters / archived`	To-dos and archived items
`approval get / get-by-row / list-by-row / work-item / operations / op-history / history / history-detail`	Instance status
`approval approve / reject / submit / sign / forward / urge`	Approval actions
`approval revoke / terminate / restart / retry`	Instance lifecycle operations
`approval batch / retry-batch / end-batch`	Batch operations
`approval list-types`	Enumeration reference
`approval delegation create / list / list-by-company / list-by-principals / update`	Approval delegation

custom-page — Custom Pages

Command	Description
`custom-page info / save / update-config`	View and update layout
`custom-page create / rename / copy / delete`	Lifecycle operations
`custom-page component-types`	Component reference

contact — Contacts

Command	Description
`contact search / resolve`	Search contacts / resolve accountId
`contact friends / friend-requests`	Contacts
`contact add-friend / accept-friend / reject-friend / ignore-friend / remove-friend`	Friend management

department — Departments

Command	Description
`department list / tree / info / members / search`	Department queries

post — Posts

Command	Description
`post list / search / get`	View posts
`post create / update / delete`	Create, edit, delete posts
`post comment / comments / comment-delete`	Comment operations
`post like / likes / favorite`	Like and favorite actions
`post pin / unpin / pinned`	Pin management
`post topics`	Topics

calendar — Calendar

Command	Description
`calendar list / get / create / update / delete`	Calendar lifecycle management
`calendar categories`	Built-in categories
`calendar add-member / remove-member`	Participant management

chat — Chat & Messaging

Command	Description
`chat list`	Recent chats
`chat messages`	Direct/group/system messages (including workflow and app messages)
`chat files`	Files shared in chats
`chat send`	Send plain text messages
`chat group-info`	Group information
`chat card-detail`	Parse embedded card references in messages

region — Regions

Command	Description
`region get`	Lookup by `--id` or fuzzy search using `--search`

icon — Icon Library

Command	Description
`icon search`	Search icons by English and Chinese keywords (union match; ranked by relevance; auto-supplement to 10 results if needed)
`icon list [-n SIZE] [-p PAGE]`	Paginated icon list (default 50 per page)

upload — File Upload

Command	Description
`upload [SOURCES...]`	Upload local file paths or HTTP(S) URLs to storage and return a structured file descriptor object (fileID, key, url, serverName, filePath, fileName, fileExt, originalFileName, fileSize).

config — CLI Configuration

Command	Description
`config show`	Show CLI configuration summary
`config completion [bash\|zsh\|fish] [--install]`	Enable shell command completion for `<Tab>` (bash, zsh, or fish).
`config language [LANG]`	Switch CLI language (`en`, `zh-Hans`, `zh-Hant`, `ja`)
`config log on / off / status`	Logging control
`config log level LEVEL`	Set logging level
`config log view [--lines N] [--no-follow]`	View log output

update — CLI Update

Command	Description
`update`	Check PyPI for the latest version and upgrade via pip/pipx/uv
`update --check`	Check for updates without installing

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

# Approvals
hap approval todo --type 4
hap approval approve INSTANCE_ID --opinion "OK"
hap approval reject INSTANCE_ID --opinion "Needs 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 "new employee onboarding" --mode hybrid

Was this document helpful?

Installation​

Prerequisite: Enable CLI Access​

Login​

Non-interactive login (scripts / headless servers)

Multi-Environment / Multi-Account Support​

Organization and Application Selection​

Browse Worksheets & Records​

JSON Output Mode​

Default App and Organization Resolution​

REPL Mode​

Command Reference​

auth — Authentication & Sessions​

app — Application Management​

worksheet — Worksheets, Views, Custom Actions & Charts​

worksheet record — Record CRUD​

workflow — Workflows & Nodes​

approval — Approvals & To-dos​

custom-page — Custom Pages​

contact — Contacts​

department — Departments​

post — Posts​

calendar — Calendar​

chat — Chat & Messaging​

region — Regions​

icon — Icon Library​

upload — File Upload​

config — CLI Configuration​

update — CLI Update​

Examples​