> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# helix sync

> For the complete documentation index optimized for AI agents, see [llms.txt](/llms.txt).

Refresh Helix Cloud instance metadata in `helix.toml`. `helix sync` fetches the latest gateway URL, auth contract, and node-type info from Helix Cloud and writes it back to the local `[enterprise.<instance>]` block, so [`helix query`](/cli/command-reference/query), [`helix logs`](/cli/command-reference/logs), and other Cloud commands can target the instance.

Requires Helix Cloud authentication. Run [`helix auth login`](/cli/command-reference/auth) first.

## Usage

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
helix sync [INSTANCE] [OPTIONS]
```

## Arguments

| Argument   | Description                                                                                               |
| ---------- | --------------------------------------------------------------------------------------------------------- |
| `INSTANCE` | Helix Cloud instance name to sync. If omitted, every `[enterprise.*]` instance in `helix.toml` is synced. |

## Available flags

| Flag          | Type    | Description                                                                                                                      | Default |
| ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | ------- |
| `--dry-run`   | Boolean | Fetch the remote state and print the changes `helix sync` would make, without writing anything. Mutually exclusive with `--yes`. | `false` |
| `-y`, `--yes` | Boolean | Skip interactive conflict prompts and apply the reconciliation non-interactively (useful in CI).                                 | `false` |

## What gets updated

For each matched Helix Cloud instance, `helix sync` overwrites these fields in `helix.toml` from the cloud-side configuration:

* `gateway_url`
* `query_auth_header` (defaults to `Authorization`)
* `query_auth_env` (defaults to `HELIX_API_KEY`)
* `availability_mode`
* `gateway_node_type`
* `db_node_type`

If the cloud response does not include a `gateway_url`, the CLI prints:

```
Enterprise instance '<name>' is synced, but gateway_url is still missing.
Set it in helix.toml before using 'helix query <name>'.
```

## Examples

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
# Sync a single Helix Cloud instance
helix sync production

# Sync every Helix Cloud instance defined in helix.toml
helix sync

# Preview what would change without writing to helix.toml
helix sync production --dry-run

# Apply without interactive conflict prompts (CI)
helix sync production --yes
```

## Related

* [`helix auth`](/cli/command-reference/auth) — authenticate with Helix Cloud
* [`helix query`](/cli/command-reference/query) — uses the synced `gateway_url` and auth contract
* [`helix cluster`](/cli/command-reference/cluster) — list available clusters