@fluid-app/fluid-cli-genealogy

Fluid CLI plugin for genealogy trees: parents, children, legs, placements and moves, over the company genealogy API (v2026-10).

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-genealogy
fluid login
fluid genealogy trees
fluid genealogy show --member <member-id>            # seat in the placement tree, with counts
fluid genealogy ancestors <node> --as-of 2026-09-01T00:00:00Z
fluid genealogy children <node> --limit 50           # prints next_cursor if more remain
fluid genealogy grandchildren <node>
fluid genealogy legs <node>                          # legs ranked by headcount
fluid genealogy strong-leg <node>
fluid genealogy tree <node> --depth 3                # indented text downline
fluid genealogy move <node> --to <parent> --dry-run  # preview only
fluid genealogy move <node> --to <parent> --yes

A node is a member's seat in one tree. Commands take a node UUID, or --member <member-id> with --tree <key-or-id> (default placement) to use that member's seat. A member with no seat, or several, in the tree is an error.

Reads: show, counts, parent, root, ancestors, sponsor, enroller, children, siblings, frontline, personally-enrolled, grandchildren, level --depth N, descendants --depth N, subtree --depth N, level-counts --depth N, relation <node> <other> [--kind], placements, holding-tank, trees. Deeper reads take depths 1-7. Lists follow every page; --limit caps the total and the output's next_cursor resumes with --cursor.

Legs are measured by headcount only: each leg counts the child's seat plus its downline_count. The API has no leg volume. Counts include retained seats of discarded members. The API has no per-leg count endpoint, so legs, strong-leg and weak-leg read each direct child's counts with its own request. They refuse a node with more than 200 direct children; pass --limit <n> to count up to n. The children read leaves out a direct child whose member was discarded, while the node's own counts keep it. There is no single read of a node's children with their counts, so legs reads the node's counts, then the children and each child's counts twice, then the node's counts again, and uses them only when every read agrees; otherwise it reads again (up to three times). When the node has more children than were listed, the output carries unlisted (children, seats, ranked, unknown_empty_legs). A single unlisted child is ranked with its exact size and unlisted: true, in the named leg left free when there is only one. Empty named legs are not listed when they cannot be told from an unlisted child's leg. strong-leg and weak-leg name a leg only when the unlisted children cannot change it; a strong leg that has more seats than all of them together still holds. Otherwise they return leg: null with best_listed, the pick among the listed legs.

Reads need a company admin with members.view (or the legacy users.view); a company API token (C-...) with that permission works too. Naming a tree by key, including the default placement, looks it up with GET /api/company/v2026-10/genealogy/tree-keys, which lists only each tree's id, key and name and needs the same members.view; without it, the key is looked up in the tree definitions, which need developer.view. An API without the tree-keys endpoint (it answers 404) falls back the same way. Only fluid genealogy trees, which prints the full tree definitions, needs developer.view, because those definitions carry company configuration. legs reads a tree's leg names from those definitions too: without developer.view it still ranks the occupied legs but cannot list empty named legs, so weak-leg returns leg: null with best_listed (an unseen empty leg may be the weak one) and the report carries leg_names_known: false.

Writes: place, move, move-requests approve|reject. They need an admin user's login: run fluid login as a company admin with members.manage (for place and move) or team_moves.approve (for move-requests approve|reject). A company API token (C-...) is refused with 403 "A company admin identity is required ...". Writes change the live tree, so they ask for confirmation unless you pass --yes. move --validate (or --dry-run) previews without writing. move-requests list|show and move-jobs list|show read move receipts.

Tree definitions: trees create, trees update <tree> and trees delete <tree> (a key or UUID) write the company's tree registry. They need an admin login with developer.update (a company API token works only if its role grants it). Every writable field is a flag: --key, --name, --kind unilevel|binary|matrix, --role, --leg-names left,right, --placement-rule, --movement-approval immediate|require_approval, --holding-tank-days, --max-depth, --max-movement-levels, --movement-window-days, --volume-on-move, --volume-key, --allow-multiple-positions true|false, --authority authoritative|replica|unconfigured, --owning-company-integration-id, --upstream-tree-ref and --external-integration-market-id; none clears a nullable field. Create needs --key, --name, --kind and --authority; binary and matrix trees also need --volume-on-move. Binary and matrix trees accept the default rules exact, first_empty, left, right and defer; unilevel trees exact, under_enroller and mirror_enrollment (other rules are refused with a typed error). place --parent with neither --leg nor --rule uses the tree's default rule. Only an authoritative tree takes placements, and placing in a binary or matrix tree also needs the company's GENEALOGY_LEGGED_TREES flag. Update sends only the flags given, at the tree's current lock_version unless --lock-version pins one; an occupied tree can only be renamed. Delete fails with tree_has_nodes while the tree holds any seat, and the default enrollment and placement trees can't be deleted. Each write shows the request and asks first unless --yes; --dry-run prints it and sends nothing.

fluid genealogy trees create --key team-binary --name "Team Binary" --kind binary \
  --authority authoritative --volume-on-move follows_structure --dry-run
fluid genealogy trees update team-binary --movement-approval require_approval --yes
fluid genealogy trees delete team-binary --yes

trees mirror [tree] (default placement) backfills the placement tree from the enrollment tree for a company whose placement tree uses mirror_enrollment and has no legacy placement tree: every enrolled member without a placement seat is seated under their enroller's seat, roots first, and unpinned seats that no longer match are re-parented. Pinned seats stay. It is idempotent and needs an admin login with members.manage. Member writes keep the trees mirrored afterwards.

--dry-run reports the counts at once and writes nothing (up to 5,000 enrollment seats). A real run asks first unless --yes, then queues a background run with no seat limit and prints it (mirror_run, plus started: false when the company already had a run queued or running; there is one at a time). --wait follows the run, printing a progress line per reading on stderr (every --interval seconds, default 2), then prints the finished run and exits non-zero if it failed or halted. A halted run kept the batches it wrote; run the mirror again to finish.

fluid genealogy trees mirror --dry-run
fluid genealogy trees mirror --yes --wait
fluid genealogy trees mirror-runs list --status running
fluid genealogy trees mirror-runs show <run-id>

Every command except tree prints JSON. Failures print a JSON error (with the API's type when there is one) on stderr and exit non-zero.