Organisation

CLI

Organisation

The org command group manages organisation-level settings — creating sub-organisations and managing member seat assignments and who-pays-what.

org create

Create a sub-organisation (an office or an individual seat) under the current org. There are three input modes:

# Interactive (the default in a TTY)
hutly org create

# From a YAML file
hutly org create ./sub-orgs/sydney.yaml

# From flags
hutly org create --kind office --name "Sydney Office" \
  --parent-org "$HUTLY_ORG_ID" \
  --payer seat:auto-top-up,event=5000,month=50000 \
  --payer credit:event=2000,month=20000 \
  --json --pretty

# Preview the resolved payload without calling the API
hutly org create --kind office --name "Sydney Office" --dry-run

Kinds

office — a child business sitting under a brand (the current org). The API key must belong to an owner of the parent org.
individual — a per-seat workspace activated for the caller. The API key must belong to the seat-holder themselves, not the brand owner.

YAML format

kind: office                   # required: office | individual
organizationId: …              # written back on first deploy; absent on first run
name: Sydney Office            # required for both kinds
parentOrgId: …                 # defaults to $HUTLY_ORG_ID
abn: "12345678901"             # office only
contractedTokens: 1000000      # office only
allowExternalEmailSend: false  # office only
payers:                        # office only
  - chargeType: seat           # seat | credit
    autoTopUpAuthorised: true
    maxCentsPerEvent: 5000
    maxCentsPerMonth: 50000
seatPayer: parent              # individual only; 'parent' | 'self'; default 'parent'
creditPayer: parent            # individual only; same

Re-running and idempotency

Re-running a YAML file that already contains an organizationId prints a friendly “already deployed” notice and exits 0 — no second org is created. If the create succeeds server-side but the CLI cannot write the organizationId back to the file (read-only mount, file moved), it prints the new organizationId and the line to add, then exits non-zero so automation does not blindly retry into a duplicate.

There is currently no CLI command to change settings on an existing org after creation.

Agent mode

Under HUTLY_AGENT_INVOCATION=1, interactive mode is refused (exit code 8) — supply input via flags or a YAML file instead. See Configuration.

org seats update

Update an existing member’s seat type and who pays for their subscription and credits. The caller must be an admin or owner of the current org, and at least one of the three flags must be provided.

hutly org seats update member@example.com \
  --individual-seat \
  --subscription-payer parent \
  --credits-payer self

Flag	Purpose
`--individual-seat`	Assign the member an individual seat
`--subscription-payer <parent\|self>`	Who pays the member’s subscription
`--credits-payer <parent\|self>`	Who pays for the member’s credits

org users

Manage org users. There is no invitation/acceptance flow — add creates the user’s account and org membership immediately.

hutly org users list --query "acme" --role admin
hutly org users add jane@acme.com --name "Jane Smith" --role chat
hutly org users get <userId>
hutly org users set-role <userId> --role admin
hutly org users update-metadata <userId> --metadata '{"department":"sales"}'
hutly org users remove <userId> [--yes]

Command	Purpose
`list`	List users; filter with `--query` and `--role admin\|chat`
`add <email>`	Add a user — creates the account and membership in one step
`get <userId>`	Fetch a single user
`set-role <userId>`	Change role. Cannot set `owner` — use the Owner Transfer flow instead
`update-metadata <userId>`	Replace a user’s org membership metadata
`remove <userId>`	Remove org membership

org groups

Manage user groups — the only mechanism for granting access to agents, apps, app sites, and site pages. Access can never be granted to an individual user directly.

hutly org groups list
hutly org groups create --name "Sales" --description "Sales team access"
hutly org groups get <groupId>
hutly org groups update <groupId> --full-access-apps true
hutly org groups delete <groupId> [--yes]

hutly org groups members add <groupId> <userId>
hutly org groups members list <groupId>

hutly org groups agents list <groupId>
hutly org groups agents add <groupId> <agentId>
hutly org groups agents remove <groupId> <agentId>

hutly org groups access list <groupId> --type apps
hutly org groups access grant <groupId> --type app-sites --resource-id <siteId>
hutly org groups access revoke <groupId> --type app-site-apps --resource-id <pageId>

update is a partial patch — pass only the fields you’re changing. A group has 4 independent “allow all” flags (--full-access-agents, --full-access-apps, --full-access-app-sites, --full-access-app-site-apps); --full-access <true|false> is shorthand for setting all 4 at once, and any explicit granular flag passed in the same command overrides that one family. --type on the access subcommands is one of apps (pinned HTML artifacts), app-sites (whole sites), or app-site-apps (individual site pages).

groups delete cascades: it removes every membership, agent grant, and app/app-site/site-page grant the group holds before removing the group itself.

Feed Channels Secrets