v3.0.5

Cli dx improvements (#933)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR makes two DX improvements to the Helix CLI: it allows `helix
add` to run inside a project that currently has zero instances (so users
can re-add an instance after deleting the last one), and it adds a new
`helix cluster indexes` subcommand that lists vector, equality, and
range indexes for an Enterprise cluster.

- **Zero-instance tolerance for `helix add`**: `HelixConfig::from_file`
and `ProjectContext::find_and_load` are each split into a strict and a
lenient variant; `helix add` now uses the lenient path, with new unit
tests covering both paths.
- **`helix cluster indexes` command**: A new `Indexes` subcommand
(aliased `indices`) is added under `ClusterConfigAction`; it
auto-resolves the cluster ID from the current project's Enterprise
instance when `--cluster-id` is omitted, and supports `--format json`.
- **Improved error hint**: The `MissingInstances` error now surfaces a
concrete `helix add` command as a hint.

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| helix-cli/src/commands/config.rs | Adds `list_indexes_for_cluster`
handler and `resolve_cluster_id_for_indexes` fallback; error from
`find_and_load` is silently swallowed, which can hide config-parse
failures behind a generic hint message. |
| helix-cli/src/enterprise_cloud.rs | Adds
`CliClusterIndex`/`CliClusterIndexes` structs and
`fetch_indexes_for_cluster`; alias-only rename means `--format json`
serializes to `index_name`/`index_type` instead of the API's
`name`/`type`. |
| helix-cli/src/config.rs | Cleanly refactors `from_file` into a
`from_file_inner(require_instances)` gate; new tests cover both strict
and lenient validation paths. |
| helix-cli/src/project.rs | Adds `find_and_load_allow_no_instances` by
delegating to a shared `load_with(require_instances)` helper; logic is
straightforward. |
| helix-cli/src/commands/add.rs | Switches to
`find_and_load_allow_no_instances` so `helix add` can re-add an instance
when the last one was deleted. |
| helix-cli/src/lib.rs | Adds `Indexes` subcommand under
`ClusterConfigAction` with `--cluster-id`/`--format` args and `indices`
alias; clean. |
| helix-cli/src/errors.rs | Adds actionable `with_hint` to
`MissingInstances` error message; no logic changes. |
| helix-cli/src/main.rs | Adds a parser test for `cluster indexes
--cluster-id ent_123`; straightforward test coverage. |

</details>

</details>

<details><summary><h3>Flowchart</h3></summary>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[helix cluster indexes] --> B{--cluster-id provided?}
    B -- yes --> C[trim & validate non-empty]
    C --> D[Use provided cluster_id]
    B -- no --> E[ProjectContext::find_and_load\nrequire_instances=true]
    E -- error --> F[Return: Provide --cluster-id hint]
    E -- ok --> G{enterprise instances count}
    G -- 0 --> H[Error: No Enterprise instances\nin helix.toml]
    G -- 1 --> I[Use sole instance cluster_id]
    G -- many & interactive --> J[prompts::select_instance]
    G -- many & non-interactive --> K[Error: list available instances]
    J --> L[Lookup cluster_id from config]
    I --> L
    D --> M[require_auth + fetch_indexes_for_cluster]
    L --> M
    M --> N{--format json?}
    N -- yes --> O[print_json]
    N -- no --> P[print_cluster_indexes\nvector / equality / range]
```
</details>

<sub>Reviews (1): Last reviewed commit: ["Implement lenient
configuration loading
..."](https://github.com/helixdb/helix-db/commit/68e79ed16eaca0c0096908ac1ad30417fda42cb3)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=35920797)</sub>

> Greptile also left **2 inline comments** on this PR.

<!-- /greptile_comment -->

v3.0.4

Cli dx improvements (#932)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR delivers a set of CLI developer-experience improvements: renames
`helix run` to `helix start` (keeping `run` as a backward-compatible
alias), removes the Dashboard command, adds a new `helix skills`
subcommand for managing agent skills, makes `helix chef` work without
Cloud auth in non-interactive / headless environments, and adds branded
help styling and a 24 h skills-update-check alongside the existing
binary update check.

- **`helix run` → `helix start`**: All internal call sites updated;
`#[command(alias = "run")]` preserves backward compatibility with
scripts and agent muscle memory.
- **`helix skills` command**: New install / update / list subcommands
wrapping `npx skills`; `helix update` and `helix init` / `chef`
automatically refresh skills after install, with a 24 h GitHub-SHA–based
staleness check surfaced on the welcome screen.
- **Go SDK conflict handling**: `ErrConflict` sentinel, `StatusCode` on
`HelixError`, and `IsConflict` helper added; empty `Returning()` now
serializes as `[]` instead of `null` (bug fix in `returningVars`).
- **Rust SDK**: Comprehensive rustdoc coverage added to all public types
and methods with no logic changes.

<details><summary><h3>Important Files Changed</h3></summary>




| Filename | Overview |
|----------|----------|
| helix-cli/src/main.rs | Major CLI DX overhaul: renames `run` to
`start` (with backward alias), removes Dashboard, adds Skills command,
adds branded help styling, adds hidden removed-command stubs with
friendly errors, and parallelizes update checks sequentially (minor
latency concern). |
| helix-cli/src/update.rs | New skills-update-check subsystem: GitHub
commits API polling with 24h cache, `HELIX_NO_UPDATE_CHECK` opt-out,
`skills_installed()` lockfile probe, and `record_skills_refreshed()`
cache reset — all mirroring the existing binary update-check pattern. |
| helix-cli/src/commands/chef.rs | Cloud auth is now optional in
non-interactive / `HELIX_SKIP_CLOUD_AUTH` environments; snapshot upload
is skipped gracefully when credentials are absent, unblocking headless
agent runs. |
| helix-cli/src/commands/skills.rs | New `helix skills` subcommand
(install / update / list) delegating to `npx skills`; checks for `npx`
presence and returns a helpful error when Node.js is absent. |
| sdks/go/client.go | Adds `ErrConflict` sentinel, `StatusCode` field on
`HelixError`, and `IsConflict` helper; operator precedence in
`IsConflict` is correct but explicit parentheses would improve
readability. |
| sdks/go/dsl.go | Extracts `returningVars` helper to ensure empty
`Returning()` calls serialize as `[]` instead of `null` — bug fix
confirmed by new test. |
| sdks/go/README.md | Adds conflict-retry guidance and parameter
documentation; the `ExecWithConflictRetry` example has a dead `return
nil` after the loop that is unreachable and potentially misleading. |
| sdks/rust/src/lib.rs | Comprehensive rustdoc coverage added to all
public types and methods; no logic changes. |
| helix-cli/src/lib.rs | Adds `SkillsAction` enum and
`--skills`/`--no-skills` flags to both `InitTarget` variants, with
`skills_override()` to resolve subcommand-level flags over parent-level
flags. |
| helix-cli/src/setup.rs | Adds `list_skills` / `skills_list_args` and
updates warning messages to reference `helix start`; well-tested with
new unit tests. |

</details>


</details>


<details><summary><h3>Flowchart</h3></summary>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[helix CLI invoked] --> B{top-level help?}
    B -- yes --> C[print_help / exit]
    B -- no --> D[check_for_updates]
    D --> E[check_skills_update]
    E --> F[Cli::parse]
    F --> G{command?}
    G -- none --> H[display_welcome\nupdate + skills notices]
    G -- start / run alias --> I[commands::start::run]
    G -- skills install/update/list --> J[commands::skills::run\nnpx skills ...]
    G -- init local/cloud --> K[commands::init::run\nmaybe_install_tooling]
    G -- chef --> L[commands::chef::run\nskip auth if non-interactive]
    G -- update --> M[commands::update::run\nrefresh_skills_if_installed]
    G -- compile/check/deploy --> N[friendly removed-command error]
    J --> O[crate::setup::install_skills\nor list_skills]
    O --> P[record_skills_refreshed\ndelete skills_cache.toml]
```
</details>


<!-- greptile_failed_comments -->
<details><summary><h3>Comments Outside Diff (1)</h3></summary>

1. `helix-cli/src/main.rs`, line 659-661
([link](https://github.com/helixdb/helix-db/blob/d4960a8a5fb471c2e2256cc099781336e728aed8/helix-cli/src/main.rs#L659-L661))

<a href="#"><img alt="P2"
src="https://greptile-static-assets.s3.amazonaws.com/badges/p2.svg?v=9"
align="top"></a> **Sequential network calls add latency to every
command**

`check_for_updates` and `check_skills_update` are awaited sequentially
before `Cli::parse()`. On a cache-miss day each can block up to 10 s
(the `reqwest` timeout), meaning any command — not just the welcome
screen — could stall for up to 20 s once every 24 h. These two
independent futures could be parallelized with `tokio::join!` to cap the
overhead at one network round-trip instead of two.

Note: If this suggestion doesn't match your team's coding style, reply
to this and let me know. I'll remember it for next time!

</details>

<!-- /greptile_failed_comments -->

<sub>Reviews (1): Last reviewed commit: ["Enhance Go SDK error handling
and query
..."](https://github.com/helixdb/helix-db/commit/d4960a8a5fb471c2e2256cc099781336e728aed8)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=35682745)</sub>

> Greptile also left **1 inline comment** on this PR.

<!-- /greptile_comment -->

v3.0.3

Dev (#929)

v3.0.2

Helix chef + sdks (#919)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR introduces `helix chef`, a new CLI command that bootstraps a
full HelixDB app by orchestrating skill/MCP installation, project init,
DB startup, and launching a coding agent (Claude Code, Codex, or
OpenCode) with a structured prompt. It also adds new Rust and TypeScript
SDKs with type-safe DSL query builders and a cross-SDK parity test
suite.

- **`helix chef`** (`helix-cli/src/commands/chef.rs`, 2182 lines):
interactive/automatic setup flow, streaming Claude Code output via
`stream-json`, and a `run_quietly` helper that temporarily sets
verbosity to `Silent` while orchestrating sub-commands.
- **Rust SDK** (`sdks/rust/`): full DSL builder API plus an async HTTP
client; the `#[register]` macro generates typed query functions.
- **TypeScript SDK** (`sdks/typescript/src/index.ts`): parallel DSL
builder with a custom bigint-safe JSON serializer/parser and query
bundle generation.
- **Parity test suite** (`.github/workflows/parity_tests.yml`,
`sdks/tests/`, `sdks/typescript/scripts/parity/`): generates fixtures
from both SDKs, runs them against a live Helix instance, and diffs the
results.

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| helix-cli/src/commands/chef.rs | New `helix chef` onboarding command:
installs skills/MCP, initializes a project, starts DB, seeds data, and
launches a coding agent. Contains the process-global
`env::set_current_dir` concern and the unimplemented `--auto`/`--agent`
flags referenced in install.sh. |
| helix-cli/install.sh | Updated post-install instructions document
`helix chef --agent` and `helix chef --auto` flags that are not
implemented in the CLI, causing clap errors when users follow these
instructions. |
| .github/workflows/parity_tests.yml | New CI workflow for SDK DSL
parity tests. Installs the helix CLI from `main` branch rather than
building from the PR's source, which may produce false results when CLI
behavior is also changing. |
| sdks/typescript/src/index.ts | New TypeScript SDK: full query-builder
DSL mirroring the Rust SDK, with custom bigint-safe JSON
serializer/parser, property value types, and query bundle generation.
Implementation looks correct and well-structured. |
| sdks/rust/src/lib.rs | New Rust SDK HTTP client with builder pattern
for stored and dynamic queries. The known URL-joining behavior for
path-prefixed base URLs is already noted in a prior review thread. |
| helix-cli/src/output.rs | Adds a new `Silent` verbosity level
(shifting existing numeric values by 1) and a `show_quiet()` helper. The
default VERBOSITY value is updated correctly from 1 to 2 to maintain
Normal as default. |
| helix-cli/src/commands/query.rs | Query output is now gated on
`show_normal()` so chef's internal seed query doesn't print to stdout.
Correct behavior; default verbosity (Normal) preserves the existing
user-facing output. |
| sdks/typescript/scripts/parity/run-helix.ts | Parity test runner that
spins up Helix instances for both Rust and TypeScript SDK fixtures and
compares their outputs. The previously-flagged `spawnSync` OS-error
surfacing issue is tracked in an existing thread. |
| sdks/rust/src/dsl.rs | Large new Rust DSL module (5370 lines)
providing type-safe query-builder API for HelixDB. Comprehensive
coverage of all query constructs; no significant issues found. |

</details>

</details>

<details><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant User
    participant Chef as helix chef
    participant NPX as npx (skills/MCP)
    participant Init as helix init
    participant DB as helix run dev
    participant Query as helix query
    participant Agent as Coding Agent (Claude/Codex)
    participant Browser

    User->>Chef: helix chef
    Chef->>User: Prompts (intent, mode, dir)
    Chef->>NPX: npx skills add HelixDB/skills
    Chef->>NPX: npx add-mcp helixdb-docs
    Chef->>Init: init local (run_quietly)
    Chef->>Chef: write HELIX_CHEF_PROMPT.md + examples/
    Chef->>DB: helix run dev (run_quietly)
    Chef->>Query: helix query dev --file seed.json (run_quietly)
    Chef->>User: Prompt: Give agent full autonomy?
    Chef->>Agent: launch with --append-system-prompt-file
    loop stream-json events
        Agent-->>Chef: tool use events (Edit/Bash/Read...)
        Chef->>User: spinner update
    end
    Agent-->>Chef: ResultEvent (cost, duration, summary)
    Chef->>Browser: try_open_frontend (http://localhost:3000)
    Chef->>User: Final summary
```
</details>

<sub>Reviews (2): Last reviewed commit: ["updating
cli"](https://github.com/helixdb/helix-db/commit/49d3e42466a31f52679e760d19e94182b489c375)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=33039363)</sub>

> Greptile also left **1 inline comment** on this PR.

<!-- /greptile_comment -->

v3.0.1

Helix chef + sdks (#919)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR introduces `helix chef`, a new CLI command that bootstraps a
full HelixDB app by orchestrating skill/MCP installation, project init,
DB startup, and launching a coding agent (Claude Code, Codex, or
OpenCode) with a structured prompt. It also adds new Rust and TypeScript
SDKs with type-safe DSL query builders and a cross-SDK parity test
suite.

- **`helix chef`** (`helix-cli/src/commands/chef.rs`, 2182 lines):
interactive/automatic setup flow, streaming Claude Code output via
`stream-json`, and a `run_quietly` helper that temporarily sets
verbosity to `Silent` while orchestrating sub-commands.
- **Rust SDK** (`sdks/rust/`): full DSL builder API plus an async HTTP
client; the `#[register]` macro generates typed query functions.
- **TypeScript SDK** (`sdks/typescript/src/index.ts`): parallel DSL
builder with a custom bigint-safe JSON serializer/parser and query
bundle generation.
- **Parity test suite** (`.github/workflows/parity_tests.yml`,
`sdks/tests/`, `sdks/typescript/scripts/parity/`): generates fixtures
from both SDKs, runs them against a live Helix instance, and diffs the
results.

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| helix-cli/src/commands/chef.rs | New `helix chef` onboarding command:
installs skills/MCP, initializes a project, starts DB, seeds data, and
launches a coding agent. Contains the process-global
`env::set_current_dir` concern and the unimplemented `--auto`/`--agent`
flags referenced in install.sh. |
| helix-cli/install.sh | Updated post-install instructions document
`helix chef --agent` and `helix chef --auto` flags that are not
implemented in the CLI, causing clap errors when users follow these
instructions. |
| .github/workflows/parity_tests.yml | New CI workflow for SDK DSL
parity tests. Installs the helix CLI from `main` branch rather than
building from the PR's source, which may produce false results when CLI
behavior is also changing. |
| sdks/typescript/src/index.ts | New TypeScript SDK: full query-builder
DSL mirroring the Rust SDK, with custom bigint-safe JSON
serializer/parser, property value types, and query bundle generation.
Implementation looks correct and well-structured. |
| sdks/rust/src/lib.rs | New Rust SDK HTTP client with builder pattern
for stored and dynamic queries. The known URL-joining behavior for
path-prefixed base URLs is already noted in a prior review thread. |
| helix-cli/src/output.rs | Adds a new `Silent` verbosity level
(shifting existing numeric values by 1) and a `show_quiet()` helper. The
default VERBOSITY value is updated correctly from 1 to 2 to maintain
Normal as default. |
| helix-cli/src/commands/query.rs | Query output is now gated on
`show_normal()` so chef's internal seed query doesn't print to stdout.
Correct behavior; default verbosity (Normal) preserves the existing
user-facing output. |
| sdks/typescript/scripts/parity/run-helix.ts | Parity test runner that
spins up Helix instances for both Rust and TypeScript SDK fixtures and
compares their outputs. The previously-flagged `spawnSync` OS-error
surfacing issue is tracked in an existing thread. |
| sdks/rust/src/dsl.rs | Large new Rust DSL module (5370 lines)
providing type-safe query-builder API for HelixDB. Comprehensive
coverage of all query constructs; no significant issues found. |

</details>

</details>

<details><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant User
    participant Chef as helix chef
    participant NPX as npx (skills/MCP)
    participant Init as helix init
    participant DB as helix run dev
    participant Query as helix query
    participant Agent as Coding Agent (Claude/Codex)
    participant Browser

    User->>Chef: helix chef
    Chef->>User: Prompts (intent, mode, dir)
    Chef->>NPX: npx skills add HelixDB/skills
    Chef->>NPX: npx add-mcp helixdb-docs
    Chef->>Init: init local (run_quietly)
    Chef->>Chef: write HELIX_CHEF_PROMPT.md + examples/
    Chef->>DB: helix run dev (run_quietly)
    Chef->>Query: helix query dev --file seed.json (run_quietly)
    Chef->>User: Prompt: Give agent full autonomy?
    Chef->>Agent: launch with --append-system-prompt-file
    loop stream-json events
        Agent-->>Chef: tool use events (Edit/Bash/Read...)
        Chef->>User: spinner update
    end
    Agent-->>Chef: ResultEvent (cost, duration, summary)
    Chef->>Browser: try_open_frontend (http://localhost:3000)
    Chef->>User: Final summary
```
</details>

<sub>Reviews (2): Last reviewed commit: ["updating
cli"](https://github.com/helixdb/helix-db/commit/49d3e42466a31f52679e760d19e94182b489c375)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=33039363)</sub>

> Greptile also left **1 inline comment** on this PR.

<!-- /greptile_comment -->

v3.0.0

Update helix-cli version to 3.0.0 in Cargo.toml and Cargo.lock (#917)

v2.3.5

CLI Pinning (#911)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR introduces **CLI version pinning**: the CLI now clones and
checks out the exact git tag matching `CARGO_PKG_VERSION` when caching
the Helix repository for builds, ensuring the compiled database binary
always matches the CLI version. It also adds a new `helix config`
command for inspecting and switching workspace/project/cluster defaults,
and consolidates previously duplicated cloud-API types from `sync.rs`
and `workspace_flow.rs` into a shared `cloud_api.rs` module.

- **Version-pinned repo cache** (`build.rs`): `git clone --branch vX.Y.Z
--depth 1` and `git fetch/checkout refs/tags/vX.Y.Z` replace the old
`main`-branch clone; a test hardcodes `"v2.3.5"` which will break on
every future version bump.
- **New `helix config` command** (`config.rs`, `lib.rs`, `main.rs`):
sub-commands for listing, showing, and switching workspaces, projects,
and clusters with `--format json/human` support.
- **`cloud_api.rs` extraction**: ~300 lines of duplicated API types and
HTTP helpers are unified into a single module; the Clippy CI workflow
(`clippy_check.yml`) is deleted without a visible replacement.

<details><summary><h3>Important Files Changed</h3></summary>




| Filename | Overview |
|----------|----------|
| helix-cli/src/commands/build.rs | Adds version-pinned git
clone/fetch/checkout helpers; introduces a brittle test that hardcodes
"v2.3.5" and an OnceLock missing the required const-block wrapper. |
| helix-cli/src/commands/cloud_api.rs | New module centralising all
cloud API types and HTTP helpers previously scattered across sync.rs and
workspace_flow.rs; contains a pre-existing inconsistency in min/max
fallback logic for enterprise cluster count helpers. |
| helix-cli/src/commands/config.rs | New config command implementing
workspace/project/cluster list, show and switch sub-commands with JSON
and human output formats. |
| helix-cli/src/commands/workspace_flow.rs | Refactored to use shared
cloud_api helpers; new project_id_hint path for workspace inference
introduces a duplicate fetch_workspaces call on the fallback path. |
| helix-cli/src/commands/update.rs | Adds v3 upgrade warning before the
self-update proceeds; warning message wording is ambiguous about which
DB format will be unavailable after upgrade. |
| .github/workflows/clippy_check.yml | Deleted — removes the only
automated Clippy CI gate across macOS/Linux/Windows with no apparent
replacement. |

</details>


</details>


<details><summary><h3>Flowchart</h3></summary>

```mermaid
%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[helix build / helix sync / helix push] --> B[ensure_helix_repo_cached]
    B --> C{cache exists?}
    C -- no --> D[create_git_cache\ngit clone --branch vX.Y.Z --depth 1]
    C -- yes stale --> E[recreate_helix_cache\nremove + create_git_cache]
    C -- yes current --> F[update_git_cache\ngit fetch refs/tags/vX.Y.Z\ngit checkout --detach refs/tags/vX.Y.Z]
    D --> G[repo cache pinned to CARGO_PKG_VERSION]
    E --> G
    F --> G
    H[helix config workspace/project/cluster] --> I[cloud_api helpers]
    J[helix sync / helix push] --> K[workspace_flow::select_or_load_workspace]
    K --> L{project_id_hint?}
    L -- yes --> M[fetch_project_details → resolve workspace]
    L -- no/unresolved --> N[resolve_current_workspace]
```
</details>


<!-- greptile_failed_comments -->
<details><summary><h3>Comments Outside Diff (1)</h3></summary>

1. `.github/workflows/clippy_check.yml` 

<a href="#"><img alt="P2"
src="https://greptile-static-assets.s3.amazonaws.com/badges/p2.svg?v=7"
align="top"></a> **Clippy CI workflow removed without a replacement**

The `clippy_check.yml` workflow was the only automated enforcement of
Clippy lints across macOS, Linux, and Windows. Removing it means future
PRs can introduce `OnceLock::new()` without `const { }` blocks, `docker
compose` invocations via `Command::new("docker compose")`, and other
patterns caught by the custom rules without any CI gate. If the workflow
is intentionally replaced by a different pipeline, please confirm it
covers the same matrix.

</details>

<!-- /greptile_failed_comments -->

<sub>Reviews (1): Last reviewed commit: ["Remove deprecated Clippy check
workflow
..."](https://github.com/helixdb/helix-db/commit/58488f397795eb7803755cdf9b29d27966c72f84)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=31971960)</sub>

> Greptile also left **3 inline comments** on this PR.

<!-- /greptile_comment -->

v2.3.4

feat(cli) : enterprise cli (#898)

<!-- greptile_comment -->

<h3>Greptile Summary</h3>

This PR adds enterprise cluster support to the Helix CLI (`v2.3.3 →
v2.3.4`), introducing a new push/sync flow for Rust-based enterprise
query projects (powered by the new `helix-enterprise-ql` crate). The key
changes are:

- **Enterprise deploy** (`helix push`): replaces the old SSE-streaming
`.rs` file upload with a single JSON POST containing a base64-encoded
`queries.json` (generated by `cargo run`) plus a sanitized source
snapshot with allowlist filtering and 20 MB / 2 000-file limits.
- **Enterprise sync** (`helix sync`): rewrites the sync flow to use
manifest-based reconciliation (sha256 + timestamps) against a new
`source_files`/`file_metadata` API response shape, with
pull/push/tie-break prompts and automatic `queries.json` regeneration
after a pull.
- **Cluster creation** (`helix add`, `helix init`): enterprise cluster
creation is locked to HA mode with role-based `min/max_gateway_count` +
`min/max_hyperscale_count` fields; non-interactive defaults are added.
- **`helix compile`**: detects an enterprise queries project by the
presence of `Cargo.toml` and runs `cargo run` to produce `queries.json`.
- **`helix init`**: now accepts `--name` for all deployment types,
preserves existing scaffold files in non-interactive mode, and improves
next-step instructions.

**Notable issues found:**
- The `CLOUD_AUTHORITY` debug-mode default was changed from
`\"localhost:8080\"` to a live staging AWS ALB URL. This will route all
debug builds to staging infrastructure instead of localhost, breaking
local development for all contributors.
- The enterprise source file count check in
`collect_enterprise_source_files` triggers at `files.len() > 2000` after
insertion, effectively allowing 2 001 files before erroring.
- The `else { (1, 1) }` branch in `create_enterprise_cluster_flow` is
dead code since `availability_mode` is unconditionally
`AvailabilityMode::Ha`.

<details><summary><h3>Important Files Changed</h3></summary>

| Filename | Overview |
|----------|----------|
| helix-cli/src/commands/integrations/helix.rs | Core enterprise deploy:
rewrites deploy from SSE-streaming to a single JSON POST with base64
queries.json + source snapshot; adds source file collection with
allowlist + size/count limits. Critical issue: debug CLOUD_AUTHORITY was
changed from localhost:8080 to a live staging AWS ALB URL. Minor
off-by-one in file count check (allows 2001, not 2000). |
| helix-cli/src/commands/sync.rs | Large refactor of enterprise sync:
response schema changed from rs_files to source_files+file_metadata,
adds manifest-based diff/pull/push reconciliation with sha256+timestamp
comparison, safe path sanitization, and local cargo regeneration after
pull. Well tested. |
| helix-cli/src/commands/workspace_flow.rs | Adds enterprise cluster
creation with role-based min/max_gateway_count +
min/max_hyperscale_count fields, non-interactive defaults, and
preferred_cluster_name propagation. Contains unreachable else { (1, 1) }
branch since availability_mode is hardcoded to Ha. |
| helix-cli/src/commands/compile.rs | Adds enterprise compile path:
detects Cargo.toml in queries dir and runs cargo run to generate
queries.json, with optional output path resolution. Clean implementation
with good error messages. |
| helix-cli/src/commands/init.rs | Extended init to accept --name for
all deployment types, adds non-interactive defaults, smarter project
structure creation (preserves existing files in non-interactive mode),
and dynamic next-step instructions. |

</details>

</details>

<details><summary><h3>Sequence Diagram</h3></summary>

```mermaid
sequenceDiagram
    participant CLI as helix CLI
    participant Cargo as cargo run
    participant FS as Local Filesystem
    participant API as Helix Cloud API

    Note over CLI,API: helix push (enterprise)
    CLI->>FS: Read queries_project_dir/Cargo.toml
    CLI->>Cargo: cargo run --manifest-path Cargo.toml
    Cargo-->>FS: writes queries.json
    Cargo-->>CLI: exit status
    CLI->>FS: Read queries.json → base64 encode
    CLI->>FS: Walk source files (allowlist filter, ≤2000 files, ≤20MB)
    CLI->>API: POST /api/cli/enterprise-clusters/{id}/deploy
    API-->>CLI: 200 {s3_key, size}
    CLI->>CLI: output success

    Note over CLI,API: helix sync (enterprise)
    CLI->>API: GET /api/cli/enterprise-clusters/{id}/sync
    API-->>CLI: {source_files, file_metadata, helix_toml}
    CLI->>FS: collect_local_enterprise_manifest
    CLI->>CLI: compare_manifests (sha256 + timestamps)
    alt Remote newer / RemoteOnly
        CLI->>FS: pull_remote_enterprise_snapshot_into_local
        CLI->>Cargo: cargo run (regenerate queries.json)
        Cargo-->>FS: writes queries.json
    else Local newer / LocalOnly
        CLI->>API: push_local_enterprise_snapshot_to_cluster
    else In sync / BothEmpty
        CLI->>CLI: no-op
    end
```
</details>

<sub>Reviews (1): Last reviewed commit: ["Update helix-cli version to
2.3.4 in
Car..."](https://github.com/helixdb/helix-db/commit/dae5d71de66eecd224dadd652c800731cdd6145b)
| [Re-trigger
Greptile](https://app.greptile.com/api/retrigger?id=26929311)</sub>

> Greptile also left **3 inline comments** on this PR.

<!-- /greptile_comment -->

v2.3.3

fix (core): perf improvements + brute force fix (#885)

v2.3.2

impr (cli + hql): fixing upserts, updates, and unique edges + improvi…