> 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/connections.md).

# connections

Manage data warehouse connections (BigQuery, Snowflake, Redshift, PostgreSQL, Databricks, …).

## `carto connections list`

List all connections.

```bash
carto connections list
```

## `carto connections get <connection-id>`

Get details for a specific connection. The output includes a `Shared with:` line listing the organization, users and groups that can use it.

```bash
carto connections get conn_xyz789
```

## `carto connections create <json-body>`

Create a new connection. The body's shape depends on the provider.

```bash
carto connections create '{
  "name": "my-snowflake",
  "type": "snowflake",
  "parameters": {
    "account": "myaccount",
    "warehouse": "compute_wh"
  }
}'
```

## `carto connections update <connection-id> <json-body>`

Update a connection.

```bash
carto connections update conn_xyz789 '{ "parameters": { "warehouse": "new_wh" } }'
```

## `carto connections delete <connection-id>`

Delete a connection.

```bash
carto connections delete conn_xyz789
```

## `carto connections share` / `carto connections unshare`

Control who can use a connection: the whole organization, specific users, or groups. Identify users by email with `--with` and groups by name or id with `--group`. The CLI resolves both before changing anything, so a typo fails loudly instead of sharing with the wrong person. New grants are added to the access the connection already has; use `unshare` to take access back. The connection can be given by id or by name.

```bash
# Share with the whole organization
carto connections share my-conn --org

# Share with specific users, and with a group
carto connections share my-conn --with a@example.com,b@example.com --group Analysts

# See who has access today, without changing anything
carto connections share my-conn --list

# Remove one person's access, or revert to owner-only
carto connections unshare my-conn --with a@example.com
carto connections unshare my-conn
```

**Options:**

| Option           | Description                                                                                                        |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `--org`          | Share with the entire organization (`unshare` drops organization-wide access and keeps specific users and groups). |
| `--with <email>` | Share with a user by email. Repeatable, or comma-separated.                                                        |
| `--group <name>` | Share with a group by its name or id. Repeatable, or comma-separated.                                              |
| `--list`         | Show the current sharing state without changing it (`share` only).                                                 |

People you share with use the connection under its owner's credentials, unless the connection requires viewer credentials. Organization Admins can turn connection sharing off for the whole organization, in which case `share` is refused. See [Sharing a connection](/carto-user-manual/connections/sharing-a-connection.md) in the user manual for how sharing behaves in CARTO.

{% hint style="info" %}
Sharing a connection with specific users or groups needs a CARTO platform that supports connection access policies. On an older Self-hosted deployment the command stops with an upgrade message before changing anything.
{% endhint %}

## `carto connections browse <name> [path]`

Browse the resource tree exposed by a connection (databases, schemas, tables, tilesets). Useful for picking source paths when authoring maps or workflows without leaving the terminal.

```bash
# Top-level tree for a connection
carto connections browse carto_dw

# Drill into a specific subtree
carto connections browse carto_dw "carto-demo-data"
```

**Options:**

| Option               | Description                                                |
| -------------------- | ---------------------------------------------------------- |
| `--depth <n>`        | Max tree depth to expand (default: server default).        |
| `--max-items <n>`    | Max total items to return (default: server default of 30). |
| `--max-children <n>` | Max children per node (default: server default).           |

## `carto connections describe <name> <table-path>`

Get the schema and details for a single table on a connection (column names, types, partitioning, row count when available).

```bash
carto connections describe carto_dw "carto-demo-data.demo_tables.nyc_collisions"
```

## `carto connections search <name> <query>`

Free-text search across the tables and views reachable through a connection.

```bash
carto connections search my-conn "customers"
carto connections search my-conn "orders" --scope "mydb.public" --type table
```

**Options:**

| Option          | Description                                            |
| --------------- | ------------------------------------------------------ |
| `--type <kind>` | Filter by resource type: `table` or `view`.            |
| `--limit <n>`   | Max results, 1–100 (default: 20).                      |
| `--scope <fqn>` | Narrow the search to a subtree (e.g. `"mydb.public"`). |


---

# 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/connections.md?ask=<question>&goal=<user_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.