Genealogy CLI

A genealogy tree records who sits under whom in your company: each member holds a seat (a node) in a tree, under a parent seat. The fluid genealogy commands read and change those trees through the company genealogy API, /api/company/v2026-10/genealogy/.... They are for company admins and integrators who manage a company’s trees. To build a member’s own view of their team, use the member API instead. Install the Fluid CLI and its genealogy plugin from npm, then sign in:

npm install -g @fluid-app/fluid-cli @fluid-app/fluid-cli-genealogy
fluid login

What you can run depends on who is signed in:

Commands	Who can run them
Reads, legs, and move receipts	A company admin with `members.view` (or the older `users.view`), or a company API token with that permission
`trees` (list the full tree definitions)	Also needs `developer.view`, because the definitions carry company configuration
`place` and `move`	A company admin signed in with `fluid login`, with `members.manage`
`move-requests approve` and `reject`	A company admin signed in with `fluid login`, with `team_moves.approve`
`trees create`, `update`, and `delete`	A company admin with `developer.update`. A company API token works only if its role grants it.

Placements, moves, and move decisions need an admin’s own sign-in. A company API token is refused for them. Every command except tree prints JSON. A failure prints a JSON error on stderr, with the API’s type and status when there are any, and exits with a non-zero code.

Choose a seat

Most commands take the seat to start from in one of two ways:

A node ID, such as 3f6a1c2e-8b4d-4e7a-9c1f-2d5b8e0a7c34.
--member <member-id> with --tree <key-or-id>, which uses that member’s seat in the tree. --tree takes a tree key or UUID and defaults to placement.

A member with no seat in the tree, or with more than one, is an error. When a member holds several seats, the error lists them so you can pass the node ID. fluid genealogy show reads one seat with its children_count and downline_count, and fluid genealogy trees lists your company’s tree definitions and their keys.

fluid genealogy show --member 8c2e4f71-5a9d-4b3e-a6c0-71d9e2f4b58a --tree placement

Read trees

Command	What it reads
`parent`, `root`	The seat’s parent (`null` for a root), or the root of its tree
`sponsor`, `enroller`	The parent in your sponsor-role or enrollment-role tree
`ancestors`	The upline, root first
`children`, `siblings`	Direct children, or the seat’s siblings
`frontline`, `personally-enrolled`	Direct children in the sponsor-role or enrollment-role tree
`grandchildren`, `level --depth N`	Seats exactly two, or `N`, levels down
`descendants --depth N`, `subtree --depth N`	The downline to `N` levels, without or with the seat itself
`level-counts --depth N`	Seat counts at each level
`counts`	`children_count` and `downline_count`
`relation <node> <other>`	How two seats relate. Pass `--kind`, such as `ancestor_of` or `within_downline`, to ask about one relation only.
`placements`	The seat’s recorded placements, newest first
`holding-tank --tree <key>`	Seats waiting to be placed, soonest due first
`tree --depth N`	The downline as an indented text tree, 3 levels by default

Depths run from 1 to 7. show, parent, root, ancestors, grandchildren, level, descendants, and subtree take --as-of <time> to read the tree as it was recorded at that time. Lists follow every cursor and return the whole list. To read in smaller batches, pass --limit: the output’s next_cursor is set when more rows remain, and you pass it back with --cursor to continue. List reads of seats also take --ids-only to return node IDs alone.

fluid genealogy children 3f6a1c2e-8b4d-4e7a-9c1f-2d5b8e0a7c34 --limit 50
fluid genealogy ancestors --member 8c2e4f71-5a9d-4b3e-a6c0-71d9e2f4b58a --as-of 2026-09-01T00:00:00Z
fluid genealogy tree 3f6a1c2e-8b4d-4e7a-9c1f-2d5b8e0a7c34 --depth 2

The tree view prints each seat’s member and node:

member 8c2e4f71-5a9d-4b3e-a6c0-71d9e2f4b58a  (node 3f6a1c2e-8b4d-4e7a-9c1f-2d5b8e0a7c34)
├── member 1b7d93e0-4c2f-4a85-b9e6-0f3a5c8d2e17 [left]  (node 9e4b2d70-6f1a-4c3e-8d5b-a2c7f0e19b46)
│   └── member e5a0c3f8-9b14-4d6e-a7c2-58f1d0b3e9a4 [left]  (node 70c8e2a5-3d9f-4b1e-96a4-e1f5b7c20d83)
└── member 4d2f8a16-7e3b-4c90-b5d1-c9a6e0f2b734 [right]  (node c1f5a9e3-2b7d-4e68-a0c4-8d3e6b1f9a52)

For each read’s fields and selectors, see the API reference:

Read a seat, its parent, its root, its sponsor, and its enroller
Ancestors, children, siblings, frontline, and personally enrolled members
Descendants, subtree, one level, and seat counts by level
Two-seat relations, recorded placements, and the holding tank

Rank legs by headcount

A leg is one direct child of a seat and everything under it. legs lists the seat’s legs, largest first. strong-leg returns the largest and weak-leg the smallest.

fluid genealogy legs --member 8c2e4f71-5a9d-4b3e-a6c0-71d9e2f4b58a --tree team-binary
fluid genealogy weak-leg 3f6a1c2e-8b4d-4e7a-9c1f-2d5b8e0a7c34

{
  "measure": "headcount",
  "counted": "seats: child plus downline_count",
  "node_id": "3f6a1c2e-8b4d-4e7a-9c1f-2d5b8e0a7c34",
  "tree_id": "b8d1e3f5-0a2c-4e79-8b6d-f4a7c9e21d30",
  "legs": [
    {
      "leg": "left",
      "node_id": "9e4b2d70-6f1a-4c3e-8d5b-a2c7f0e19b46",
      "member_id": "1b7d93e0-4c2f-4a85-b9e6-0f3a5c8d2e17",
      "downline_count": 41,
      "seats": 42,
      "counts_as_of": "2026-10-09T14:20:11Z"
    },
    {
      "leg": "right",
      "node_id": "c1f5a9e3-2b7d-4e68-a0c4-8d3e6b1f9a52",
      "member_id": "4d2f8a16-7e3b-4c90-b5d1-c9a6e0f2b734",
      "downline_count": 17,
      "seats": 18,
      "counts_as_of": "2026-10-09T14:20:11Z"
    }
  ],
  "leg_names_known": true,
  "note": "Headcount only; the genealogy API has no leg volume. Counts include retained seats of discarded members."
}

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 seats kept for removed members. So a leg’s count can be larger than what children or descendants lists.
A named leg with no child is listed with 0 seats, in binary and matrix trees.
Each child is one request. The API has no per-leg count, so the CLI reads each direct child’s counts separately. A seat with more than 200 direct children is refused; pass --limit <n> to count up to n.
Empty legs need developer.view. Leg names come from the tree definitions. Without that permission, legs still ranks the occupied legs, sets leg_names_known to false, and leaves out empty legs.
A pick can be withheld. When some children can’t be listed or empty legs aren’t known, and that could change the answer, strong-leg or weak-leg returns leg: null with best_listed, the pick among the legs it could list.

The counts come from reading a seat and its children.

Change placements

These commands change the live tree. Each one asks you to confirm in an interactive terminal. In a script, or when an agent runs it, pass --yes; without it and without a terminal, nothing changes.

Place a seat

place gives a member a new seat with --member, or places a seat waiting in the holding tank when you pass its node ID. Give --parent <node>, or --root to place a root seat. Under a parent in a binary or matrix tree:

--leg names the leg, such as left or right.
--rule lets a placement rule choose, such as first_empty.
With neither, the tree’s default placement rule applies.

To hold a new seat in the holding tank instead, pass --rule defer with no --parent, --leg, or --reason; give the reason when you place it later. --position applies only to a new seat in a matrix tree that allows several seats per member, and a held seat keeps the position it was held at.

fluid genealogy place --member 6a9e1d47-2c8b-4f35-90d7-b3e5a1c8f062 --tree team-binary \
  --parent 9e4b2d70-6f1a-4c3e-8d5b-a2c7f0e19b46 --rule first_empty \
  --reason "Enrolled at the October launch event" --yes

Only an authoritative tree takes placements. See Place a member in a binary or matrix tree and Place a seat waiting in the holding tank.

Move a seat

move puts a seat under a new parent. Pass exactly one of --to <node>, --to-member <member-id> (that member’s seat in --tree), or --to-root. Add --leg for a binary or matrix tree, and --reason to record why. Preview first with --validate (--dry-run does the same). It changes nothing and reports whether the move would be allowed:

fluid genealogy move --member e5a0c3f8-9b14-4d6e-a7c2-58f1d0b3e9a4 --tree placement \
  --to-member 4d2f8a16-7e3b-4c90-b5d1-c9a6e0f2b734 --validate

Then run it with --yes:

fluid genealogy move --member e5a0c3f8-9b14-4d6e-a7c2-58f1d0b3e9a4 --tree placement \
  --to-member 4d2f8a16-7e3b-4c90-b5d1-c9a6e0f2b734 \
  --reason "Sponsor transfer approved by compliance" --yes

A move applies at once, or returns a receipt: a move request waiting for approval, or a move job that runs later. To retry a move safely, pass the same --idempotency-key each time. Moves have to be enabled for your company. Until they are, moves are refused, and so is a --validate preview. See Preview a company genealogy move and Request a company genealogy move.

Approve or reject move requests

A move that needs a person’s approval waits as a move request until an admin decides. move-requests list shows a tree’s requests; filter with --status, such as pending. show <id> reads one. approve and reject change the live tree, so they ask first unless you pass --yes. reject needs --reason; on approve it’s optional. Approving a large move can return a move job instead of applying it at once.

fluid genealogy move-requests list --tree placement --status pending
fluid genealogy move-requests approve 2d8f4b61-9a3e-4c07-b5e2-6f1a8d3c9e70 --yes
fluid genealogy move-requests reject 7b3e9c52-1f6d-4a28-8e04-c5a2d7f1b936 \
  --reason "The new sponsor is outside the member's market" --yes

See List company move requests, Read a company move request, Approve a move request, and Reject a move request.

Follow move jobs

A move that runs later is a move job. move-jobs list shows a tree’s jobs, and --status filters them, for example pending, running, applied, or failed. move-jobs show <id> reads one job’s progress. Both only read.

fluid genealogy move-jobs list --tree placement --status running
fluid genealogy move-jobs show 5c1a7e93-4d2b-4f86-a9e0-3b8d6f2c1e45

See List tree move jobs and Read a move job.

Manage trees

fluid genealogy trees lists your company’s tree definitions. trees create, trees update <tree>, and trees delete <tree> change them; <tree> is a key or UUID. Every writable field is a flag, such as --name, --kind, --leg-names, --placement-rule, and --movement-approval; run fluid genealogy trees create --help for the full list. Pass none to clear a field that can be empty. Each write shows the request it will send and asks first, unless you pass --yes. --dry-run prints the request 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

Create needs --key, --name, --kind, and --authority. A binary or matrix tree also needs --volume-on-move.
Update sends only the flags you give. It writes at the tree’s current version, so it fails if someone changed the tree since; pin a version with --lock-version. Once a tree holds seats, only its name can change.
Delete fails while the tree holds any seat. The default enrollment and placement trees can’t be deleted.

See List tree definitions, Add a tree definition, Modify a tree definition, and Remove a custom tree definition.

Member APIs: which API to use for member data, including a member’s own team.
Authentication: company tokens and permissions.
Genealogy API reference: every company genealogy operation, in the People section.

Overview

Storefront

Commerce

Checkout

Member API

Messaging

People

Payments

DAM

Website

Portal

Mobile app

Content and tools

Analytics

Sales channels

Settings

FairShare SDK

Droplets

Developers

Portal & Widgets

Genealogy CLI

Choose a seat

Read trees

Rank legs by headcount

Change placements

Place a seat

Move a seat

Approve or reject move requests

Follow move jobs

Manage trees

​Install and sign in

​Choose a seat

​Read trees

​Rank legs by headcount

​Change placements

​Place a seat

​Move a seat

​Approve or reject move requests

​Follow move jobs

​Manage trees

​Related

Install and sign in

Choose a seat

Read trees

Rank legs by headcount

Change placements

Place a seat

Move a seat

Approve or reject move requests

Follow move jobs

Manage trees

Related