---
title: "Teams and departments"
description: "Use when you are inviting people, grouping them into departments, or controlling which team members can read or edit a shared book."
url: https://docs.heytrove.ai/concepts/teams
updated: 2026-10-06
---

# Teams and departments

> Load this page when: you manage a Trove team or share books across people

## For agents

- Only a team OWNER or ADMIN can manage the team. A role error is final.
- Destructive commands need `--confirm`. Repeating a command is safe.
- `trove team departments add-member` fails until the invite is accepted.

A team shares [books](https://docs.heytrove.ai/concepts/library-and-books.md) across people. Inside a team, departments are named groups of members, and you scope each shared book to the departments that should see it.

## Departments and access

Members are referenced by email, departments by slug, and books by item id. Joining a team upgrades the member to the Professional plan. Manage the team in the web app at [Team](https://heytrove.ai/team), or ask your agent.

## Ask your agent

If you belong to more than one team, name the team in your request.

| Task | What to tell your agent |
| --- | --- |
| List your teams | "List my Trove teams." |
| Show the team | "Show my Trove team." |
| Invite someone | "Invite sam@example.com to my Trove team as an admin." |
| Remove a member | "Remove sam@example.com from my Trove team." |
| List departments | "List the departments in my Trove team." |
| Create a department | "Create a Platform department in my Trove team." |
| Add a member | "Add sam@example.com to the Platform department." |
| Share a book with a department | "Give the Platform department read access to our API guide." |
| Revoke access | "Revoke all department access to our API guide." |
| Make a book team-wide | "Make our API guide visible to the whole team." |
| Who can see what | "Show who can see which books in my Trove team." |

## Safe by design

Destructive actions print a consequence summary and need confirmation, so your agent shows you what will change before it acts. Repeating an action is safe: if the state already matches, you see `already exists (no change made)`. Role errors are final, so ask an owner or admin instead of retrying.

## Worked example

1. Ask your agent: "Invite sam@example.com to my Trove team."
2. Ask your agent: "Create a Platform department in my Trove team."
3. After Sam accepts the invite, ask: "Add sam@example.com to the Platform department."
4. Ask: "Give the Platform department read access to our API guide."

The invite stays pending until it is accepted, and adding Sam to the department fails until then. If it fails, ask Sam to accept. Then ask your agent again.

## Best practice

Let members read their own department and the departments near it. Give write access only to people with authority over the topic. See [Run Trove for a team](https://docs.heytrove.ai/best-practices/run-trove-for-a-team.md) and [Share a library](https://docs.heytrove.ai/usage/share-a-library.md).

## Direct CLI

Your agent runs these through the `trove` command. You can run them yourself in a terminal, but asking your agent is the recommended way: it picks the right flags, waits for processing and checks the result. Add `--team <id|name>` to any `trove team` command when you belong to more than one team. Destructive commands need `--confirm`.

| Task | Command |
| --- | --- |
| List your teams | `trove team list` |
| Show the team | `trove team show` |
| Invite someone | `trove team invite <email> --role admin` |
| Remove a member | `trove team remove <email> --confirm` |
| List departments | `trove team departments list` |
| Create a department | `trove team departments create "<name>"` |
| Add a member | `trove team departments add-member <slug> <email>` |
| Share a book with a department | `trove team access grant <item> --dept <slug> --access read` |
| Revoke access | `trove team access revoke <item> --confirm` |
| Make a book team-wide | `trove team access scope <item> --team-wide` |
| Who can see what | `trove team access matrix` |

See the [CLI reference](https://docs.heytrove.ai/reference/cli.md) for every flag.

## Related

- [Library and books](https://docs.heytrove.ai/concepts/library-and-books.md) covers team-shared books in your library.
- [Plans and limits](https://docs.heytrove.ai/reference/plans-and-limits.md) lists what a team plan includes.