Skip to main content
Last updated: 2026-09-06
orca pools manages agent 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. 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

Lists the pools in the current tenant.
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

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.

​
orca pools create

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. 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.

​
orca pools delete

Deletes a pool. Member profiles are not deleted; they lose their pool grants.

​
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

Adds a profile to a pool. The call is idempotent: adding a profile that is already a member succeeds.
The role key is present only when --role was passed.

​
orca pools members remove

Removes a profile from a pool. The call is idempotent: removing a profile that is not a member succeeds.
Verified against orca-cli cli-v0.5.0.