> For the complete documentation index, see [llms.txt](https://docs.carto.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.carto.com/carto-for-agents/cli/command-reference/users.md). # users Manage users and invitations in your CARTO organization. User management commands require admin or superadmin permissions. Regular users may not have access to view all organization users; invitation commands require permission to invite users to the organization. ## Identifying a user Commands that act on a specific user take `--user-id` for a user ID or `--user-email` for an email address. SSO user IDs often contain an `@`, so say which kind you are passing. ```bash carto users get --user-email jane@carto.com carto users get --user-id "samlp|my-sso|jane@carto.com" ``` Quote values containing `|` so your shell does not read it as a pipe. ## `carto users list` List every user in the organization. The command returns the full roster in one call; filter the output when you need a subset. ```bash carto users list carto users list --json | jq '[.[] | select(.role == "Builder")]' carto users list --json | jq '[.[] | select(.email | contains("john"))]' ``` {% hint style="info" %} `--all`, `--page`, `--page-size`, `--role` and `--search` were removed in v0.12.0. The API never applied them, and `--all` did not finish for organizations of 100 or more users. A plain `carto users list` returns everyone. {% endhint %} ## `carto users get` Get detailed information for a user. See [Identifying a user](#identifying-a-user). ```bash carto users get --user-email jatorre@carto.com carto users get --user-id "google-oauth2|123456789" carto users get --user-id "samlp|my-sso|jane@carto.com" --json ``` **Options:** | Option | Description | | ---------------------- | ---------------------------------- | | `--user-id ` | Look the user up by user ID. | | `--user-email ` | Look the user up by email address. | Output includes the user profile, roles, organization, identities, and groups. ## `carto users invite [email...]` Invite one or more users to the organization. Both comma-separated and multi-argument forms are accepted. ```bash # Single user carto users invite user@example.com --role Builder # Default role is Viewer carto users invite user@example.com # Comma-separated carto users invite user1@example.com,user2@example.com,user3@example.com --role Builder # Multiple arguments carto users invite user1@example.com user2@example.com --role Viewer ``` **Options:** | Option | Description | | --------------------------------- | ---------------------------------- | | `--role ` | Role to assign. Default: `Viewer`. | **Available roles:** * **Builder** — full access to create and edit maps, workflows, and connections. * **Viewer** — read-only access to view maps and data. * **Guest** — limited access, typically for external collaborators. ## `carto users invitations` List pending invitations. ```bash carto users invitations carto users invitations --json ``` ## `carto users resendInvitation ` Resend a pending invitation. ## `carto users cancelInvitation ` Cancel a pending invitation. ## `carto users delete` Remove a user from the organization and transfer everything they own to another user. Requires Admin permissions. Both users must be identified, the one being removed and the one receiving their content. See [Identifying a user](#identifying-a-user). ```bash # Remove a user, hand their content to a colleague carto users delete --user-email jane@carto.com --receiver-email bob@carto.com # An SSO user ID that contains an "@" carto users delete --user-id "samlp|my-sso|jane@carto.com" --receiver-email bob@carto.com # The two can be identified differently carto users delete --user-email jane@carto.com --receiver-id "auth0|68c97d3137451d6dabeb86c4" ``` **Options:** | Option | Description | | -------------------------- | -------------------------------------------------- | | `--user-id ` | User to remove, by user ID. | | `--user-email ` | User to remove, by email address. | | `--receiver-id ` | User who receives their content, by user ID. | | `--receiver-email ` | User who receives their content, by email address. | **What transfers.** Maps, workflows, connections, API access tokens, assets, named sources, hosted apps, folders, and shortcuts all move to the receiving user, along with any SPA OAuth applications. **What does not.** The removed user's machine-to-machine OAuth applications are deleted rather than transferred, so any integration authenticating as that user stops working. Their recent activity, job history, group memberships, and per-user quota settings are also discarded. {% hint style="warning" %} Deleting a user cannot be undone. If the user being removed is a Builder or an Admin, the receiving user needs Builder privileges or higher, otherwise the command is rejected. You cannot delete your own account this way. {% endhint %} The content transfer runs asynchronously, so the receiving user's maps and workflows may take a moment to appear after the command returns. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.carto.com/carto-for-agents/cli/command-reference/users.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.