---
title: "trove team"
description: "Use when you run a team library from the terminal: invite and remove members, manage departments, and decide which books the team and each department can read."
url: https://docs.heytrove.ai/reference/cli/team
updated: 2026-10-01
---

# trove team

> Load this page when: you need to invite or remove team members, manage departments, or share books with a team

## For agents

- Pass --team with an id or name when you belong to more than one team.
- Pass --confirm to remove, delete and revoke, because they cut off access.
- Only OWNER and ADMIN roles can manage departments and scope a share. Members can share a book they own with the whole team, read only.

A team shares a library. Departments narrow who can read which book. See [Teams](https://docs.heytrove.ai/concepts/teams.md) for the idea.

## Quick reference

| Command | What it does |
| --- | --- |
| `trove team list` | List your teams |
| `trove team show` | Show members, departments and shared books |
| `trove team invite` | Invite a person by email |
| `trove team remove` | Remove a member |
| `trove team departments list` | List departments |
| `trove team departments create` | Create a department |
| `trove team departments rename` | Rename a department |
| `trove team departments delete` | Delete a department |
| `trove team departments add-member` | Add a member to a department |
| `trove team departments remove-member` | Remove a member from a department |
| `trove team access grant` | Share a book with the team |
| `trove team access revoke` | Stop sharing a book |
| `trove team access scope` | Share with chosen departments or the whole team |
| `trove team access level` | Switch between read and write |
| `trove team access list` | List shared books |
| `trove team access matrix` | Show the department by book matrix |

## Global flag: --team

Every `trove team` command takes `--team ID_OR_NAME`. The CLI picks the team for you when you own exactly one.

| Message | Fix |
| --- | --- |
| `You belong to multiple teams. Pass --team <id\|name>: {list}` | Add `--team`. |
| `No team '{name}'. Teams you belong to: {list}` | Use a name from the list. |
| `You're not a member of any team. Create one at {host}/team.` | Create a team in the web app. |

## trove team list

Lists the teams you belong to.

**Usage**

```bash
trove team list [--json]
```

With `--json` the output is the server response: `{ "teams": [...] }`.

REST equivalent: [Teams API](https://docs.heytrove.ai/reference/api/teams.md#list-teams).

## trove team show

Shows members, departments and shared books.

**Usage**

```bash
trove team show [--team TEAM] [--json]
```

With `--json` the output has `team`, `members`, `invites`, `departments` and `items`.

## trove team invite

Invites a person by email. They get an email with a join link and need no account yet.

**Usage**

```bash
trove team invite EMAIL [--role member|admin] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `EMAIL` | email | required | Person to invite. |
| `--role` | member or admin | member | Role of the new member. |

**Example**

```bash
trove team invite ada@example.com --role admin
```

**Errors**

| Message | Fix |
| --- | --- |
| `Only OWNER and ADMIN can manage team configuration — your role is MEMBER.` | Ask an owner or admin. |
| `Too many team changes in a short window — wait a minute and retry.` | Wait a minute. |

REST equivalent: [Teams API](https://docs.heytrove.ai/reference/api/teams.md#invite-a-member).

## trove team remove

Removes a member by email. It also revokes their access to shared books.

**Usage**

```bash
trove team remove EMAIL --confirm [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `EMAIL` | email | required | Member to remove. |
| `--confirm` | none | off | Required. |

**Errors**

| Message | Fix |
| --- | --- |
| `Removing {email} from {team} also revokes their access to its books. Re-run with --confirm to proceed.` | Add `--confirm`. |
| `You can't remove yourself. Delete the team instead, or transfer ownership first.` | Ask another owner. |

REST equivalent: [Teams API](https://docs.heytrove.ai/reference/api/teams.md#remove-a-member).

## trove team departments list

Lists departments.

**Usage**

```bash
trove team departments list [--json]
```

## trove team departments create

Creates a department. The slug comes from the name. Running it twice for the same name changes nothing.

**Usage**

```bash
trove team departments create NAME [--json]
```

**Example**

```bash
trove team departments create Engineering
```

## trove team departments rename

Renames a department.

**Usage**

```bash
trove team departments rename SLUG NEW_NAME [--json]
```

**Errors**

| Message | Fix |
| --- | --- |
| `A department with slug '{slug}' already exists in this team.` | Pick another name. |

## trove team departments delete

Deletes a department. Members lose the assignment, and books shared only with this department are unshared.

**Usage**

```bash
trove team departments delete SLUG --confirm [--json]
```

## trove team departments add-member

Adds a team member to a department by email. The person must already be on the team.

**Usage**

```bash
trove team departments add-member SLUG EMAIL [--json]
```

**Errors**

| Message | Fix |
| --- | --- |
| ``No team member with email '{email}' — run `trove team show` to see members, or invite them with `trove team invite {email}`.`` | Invite them first. |

## trove team departments remove-member

Removes a member from a department.

**Usage**

```bash
trove team departments remove-member SLUG EMAIL [--json]
```

REST equivalent for all department commands: [Teams API](https://docs.heytrove.ai/reference/api/teams.md#list-departments).

## trove team access grant

Shares a book you own with the team. Without `--dept` it goes to the whole team.

**Usage**

```bash
trove team access grant ITEM_ID [--dept SLUG]... [--access read|write] [--json]
```

**Arguments and flags**

| Argument or flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `ITEM_ID` | id | required | Book you own. |
| `--dept` | slug | whole team | Scope to a department. Repeat it for several. |
| `--access` | read or write | read | Access level. |

**Errors**

| Message | Fix |
| --- | --- |
| `Item '{id}' not found in your library (you can only share books you own).` | Share a book you own. |
| `An active team subscription is required to share books with the team.` | The team needs a paid plan. |
| `Only OWNER and ADMIN can scope a share to department(s) or grant write access. …` | Members can only share read-only with the whole team. |

REST equivalent: [Teams API](https://docs.heytrove.ai/reference/api/teams.md#share-a-book-with-the-team).

## trove team access revoke

Stops sharing a book with the team for all members.

**Usage**

```bash
trove team access revoke ITEM_ID --confirm [--json]
```

**Errors**

| Message | Fix |
| --- | --- |
| `Revoking {id} removes it from {team} for all members. Re-run with --confirm to proceed.` | Add `--confirm`. |

## trove team access scope

Changes who a shared book reaches.

**Usage**

```bash
trove team access scope ITEM_ID (--dept SLUG... | --team-wide) [--json]
```

**Arguments and flags**

| Flag | Value | Default | Meaning |
| --- | --- | --- | --- |
| `--dept` | slug | none | Share only with these departments. Replaces the current list. Repeat it for several. |
| `--team-wide` | none | off | Share with the whole team. |

**Errors**

| Message | Fix |
| --- | --- |
| `Pass --dept <slug> (repeatable) to scope to department(s), or --team-wide to share with everyone.` | Pass one of the two. |
| `Pass either --dept <slug> or --team-wide, not both.` | Pass only one. |

## trove team access level

Changes a shared book's access level.

**Usage**

```bash
trove team access level ITEM_ID --access read|write [--json]
```

**Errors**

| Message | Fix |
| --- | --- |
| ``Item '{id}' is not shared with this team — grant it first with `trove team access grant {id}`.`` | Grant it first. |

## trove team access list

Lists the books shared with the team.

**Usage**

```bash
trove team access list [--json]
```

## trove team access matrix

Shows which department can read which book. OWNER and ADMIN only.

**Usage**

```bash
trove team access matrix [--json]
```

REST equivalent for the access commands: [Teams API](https://docs.heytrove.ai/reference/api/teams.md#show-the-access-matrix).