+++
title = "Getting a cluster's connection URL"
description = "Print a cluster's URL, or write it to a git-ignored env file without showing the password."
weight = 118
updated = 2026-11-11

[extra]
nav_title = "Connection URLs"
weight = 50
+++

A cluster's connection URL holds its host, username and password:

```
https://<username>:<password>@search-nozais.us-east-1.bonsaisearch.net
```

It's all an Elasticsearch or OpenSearch client needs. `bonsai cluster url` is the only cluster command that reveals the password. It needs a token with the `credentials:read` scope.

## Write it to an env file

```
$ bonsai cluster url search --write .env
✓ Added BONSAI_URL in .env
```

`--write` sets `BONSAI_URL` in the file without printing the URL. If the variable is already there, its line is replaced, and the rest of the file is left as it is. Use `--env` to name another variable:

```bash
bonsai cluster url search --write .env.local --env ELASTICSEARCH_URL
```

So that the password can't be committed or read by others, `--write`:

- Writes only inside the current folder.
- In a git repository, refuses a file that git doesn't ignore, or that is tracked. Add the file to `.gitignore` first.
- Leaves the file with mode `0600`, readable only by you.

A refusal exits with code 2 and writes nothing.

With `--json`, the answer has the URL with the password masked:

```json
{
  "path": ".env",
  "replaced": true,
  "url": "https://z2z5nzv6l4:****@search-nozais.us-east-1.bonsaisearch.net/",
  "variable": "BONSAI_URL"
}
```

## Print it

Without `--write`, the URL goes to stdout and nothing else does, so a shell can capture it:

```bash
export BONSAI_URL=$(bonsai cluster url search)
```

`--env NAME` prints `NAME=<url>` instead, for `eval` or to append to a file yourself:

```bash
bonsai cluster url search --env BONSAI_URL
```

With `--json`, the URL is the `url` field of an object, password included:

```bash
bonsai cluster url search --json | jq -r .url
```

Printing the URL prints the password. Keep it out of logs, CI output and source control.

## Choosing a credential

By default you get the URL of the cluster's default credential, the one the dashboard shows. To use another, such as a read-only credential, pass its ID:

```bash
bonsai cluster url search --credential scc-a8Kd
```

The CLI has no command for creating credentials yet. Create one in the dashboard, or with [`bonsai api`](@/docs/cli/scripting/index.md#bonsai-api):

```bash
bonsai api POST /clusters/search-nozais/credentials -d '{"name": "reader", "access_type": "ro"}'
```

That needs the `credentials:write` scope, and prints the new credential's password.