> ## Documentation Index > Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt > Use this file to discover all available pages before exploring further. # orca pools > Create, inspect, and delete agent pools, and add or remove pool members. > **Last updated: 2026-09-06** `orca pools` manages [agent pools](/concepts/pools): named groups of agent profiles that share a filesystem workspace under `/pools/{pool}/**`. Each member carries a role (`lead`, `member`, or `observer`) that sets its built-in access to the pool paths, and a pool can layer its own read, write, delete, and deny globs on top of those role grants. Every subcommand accepts the [global flags](/cli/reference/overview#global-flags). All positionals on this page are required; there is no interactive picker. Destructive subcommands prompt for confirmation in a terminal; in a script `--yes` is required or the command refuses (exit code 2). ## orca pools list ```bash theme={"dark"} orca pools list [--limit ] [--offset ] [--all] ``` Lists the pools in the current tenant. | Flag | Type | Default | Description | | -------------- | ------- | ------- | ------------------------------------------------------------------ | | `--limit ` | integer | `10` | Page size | | `--offset ` | integer | `0` | Page offset | | `--all` | boolean | `false` | Fetch every page (cannot be combined with `--limit` or `--offset`) | ```bash theme={"dark"} orca pools list --all --json | jq -r '.[].name' ``` Plain (piped) output is one tab-separated row per pool: `name`, member count, the member list (each as `profile (role)` when a role is set), `description`. ## orca pools get ```bash theme={"dark"} orca pools get ``` Shows one pool. The API has no single-pool read, so the CLI pages through the whole pool list (in windows of 200, up to 10,000 rows) and picks the matching name; an unknown name exits 4. With `--json` the full pool object is printed (`id`, `name`, `description`, `members`, `fs`). The plain view prints key and value rows: `name`, `id`, `description`, `members`, `read`, `write`, `delete`, `deny`. ```bash theme={"dark"} orca pools get research --json | jq '.members' ``` ## orca pools create ```bash theme={"dark"} orca pools create [--description ] [--member ]... [--read ]... [--write ]... [--delete ]... [--deny ]... ``` Creates a pool. `--member` takes a profile name, optionally followed by a colon and a role. Roles are `lead`, `member`, or `observer` (matched case-insensitively; any other value exits 2). A member given without a role is sent without one and the server treats it as `member`. A pool can be created with no members and filled later with `orca pools members add`. The glob flags add paths to every member's effective filesystem policy on top of the role grants: `--read`, `--write`, and `--delete` grant access; `--deny` subtracts it and wins over any grant, built-in or custom. The tokens `{self}` (the member's profile name), `{pool}` (the pool name), and `{role}` (the member's role) inside a glob are substituted server-side when the policy is compiled. | Flag | Type | Default | Description | | --------------------------- | ------ | ------- | ------------------------------------------------------------ | | `--description ` | string | none | Human-readable description | | `--member ` | string | none | Add a member as `profile` or `profile:role`; repeatable | | `--read ` | string | none | Extra read glob added to every member's policy; repeatable | | `--write ` | string | none | Extra write glob added to every member's policy; repeatable | | `--delete ` | string | none | Extra delete glob added to every member's policy; repeatable | | `--deny ` | string | none | Deny glob; overrides any grant; repeatable | If a pool with that name already exists the command exits 2 and points you at `orca pools members add`. With `--json` the created pool record is printed. ```bash theme={"dark"} orca pools create research \ --description "Research team" \ --member researcher:lead --member reviewer --member auditor:observer \ --write "/pools/{pool}/sot/**" \ --deny "/pools/{pool}/archive/private/**" ``` ## orca pools delete ```bash theme={"dark"} orca pools delete [--yes] ``` Deletes a pool. Member profiles are not deleted; they lose their pool grants. | Flag | Type | Default | Description | | ------- | ------- | ------- | ---------------------------- | | `--yes` | boolean | `false` | Skip the confirmation prompt | ```bash theme={"dark"} orca pools delete research --yes --json ``` ```json theme={"dark"} { "name": "research", "deleted": true } ``` ## orca pools members Membership changes go through a dedicated endpoint per profile, so adding or removing one member never rewrites the rest of the pool. ### orca pools members add ```bash theme={"dark"} orca pools members add [--role ] ``` Adds a profile to a pool. The call is idempotent: adding a profile that is already a member succeeds. | Flag | Type | Default | Description | | --------------- | ------ | ------------------------- | ---------------------------------------------------------------- | | `--role ` | string | server default (`member`) | One of `lead`, `member`, `observer` (matched case-insensitively) | ```bash theme={"dark"} orca pools members add research analyst --role lead --json ``` ```json theme={"dark"} { "pool": "research", "profile": "analyst", "role": "lead", "added": true } ``` The `role` key is present only when `--role` was passed. ### orca pools members remove ```bash theme={"dark"} orca pools members remove [--yes] ``` Removes a profile from a pool. The call is idempotent: removing a profile that is not a member succeeds. | Flag | Type | Default | Description | | ------- | ------- | ------- | ---------------------------- | | `--yes` | boolean | `false` | Skip the confirmation prompt | ```bash theme={"dark"} orca pools members remove research analyst --yes --json ``` ```json theme={"dark"} { "pool": "research", "profile": "analyst", "removed": true } ``` Verified against orca-cli `cli-v0.5.0`.