feat(cli): add --generate-queries flag to build, compile, and push

Adds a `-g`/`--generate-queries` flag that reads the schema and
auto-generates CRUD queries for every node, vector, and edge type:

  - Nodes: GetAll, Get (by index), Create, Delete, DeleteAll
  - Vectors: GetAll, Add, Search, DeleteAll
  - Edges: GetAll, Create, DeleteAll

Generated queries are written to `generated_queries.hx` so they're
visible, editable, and picked up by normal compilation.

Also simplifies the `helix init` queries template to point users at
`--generate-queries` instead of shipping hardcoded starter queries.

https://claude.ai/code/session_01WvDRFcS5r3kziMrg4ddKhm

Author: claude

helix-cli/src/commands/build.rs

@@ -7,7 +7,7 @@ use crate::project::{ProjectContext, get_helix_repo_cache};
 use crate::prompts;
 use crate::utils::{
     copy_dir_recursive_excluding, diagnostic_source,
-    helixc_utils::{collect_hx_contents, collect_hx_files},
+    helixc_utils::{collect_hx_contents, collect_hx_files, generate_default_queries},
     print_confirm, print_error, print_warning,
 };
 use eyre::{Result, eyre};
@@ -42,6 +42,7 @@ const CARGO_MANIFEST_DIR: &str = env!("CARGO_MANIFEST_DIR");
 pub async fn run(
     instance_name: Option<String>,
     bin: Option<String>,
+    generate_queries: bool,
     metrics_sender: &MetricsSender,
 ) -> Result<MetricsData> {
     // Load project context
@@ -82,6 +83,7 @@ pub async fn run(
         &project,
         &instance_name,
         bin.as_deref(),
+        generate_queries,
         metrics_sender,
     )
     .await;
@@ -100,6 +102,7 @@ pub async fn run_build_steps(
     project: &ProjectContext,
     instance_name: &str,
     bin: Option<&str>,
+    generate_queries: bool,
     metrics_sender: &MetricsSender,
 ) -> Result<MetricsData> {
     let start_time = Instant::now();
@@ -116,6 +119,15 @@ pub async fn run_build_steps(
     // Step 2: Prepare workspace (verbose only shows details)
     prepare_instance_workspace(project, instance_name).await?;
 
+    // Step 2.5: Generate CRUD queries from schema if requested
+    if generate_queries {
+        let mut gen_step =
+            Step::with_messages("Generating queries from schema", "Queries generated");
+        gen_step.start();
+        generate_default_queries(&project.root, &project.config.project.queries)?;
+        gen_step.done();
+    }
+
     // Step 3: Compile project queries
     let mut compile_step = Step::with_messages("Compiling queries", "Queries compiled");
     compile_step.start();

helix-cli/src/commands/compile.rs

@@ -6,11 +6,12 @@ use crate::{
     output::{Operation, Step},
     project::ProjectContext,
     utils::helixc_utils::{
-        analyze_source, collect_hx_files, generate_content, generate_rust_code, parse_content,
+        analyze_source, collect_hx_files, generate_content, generate_default_queries,
+        generate_rust_code, parse_content,
     },
 };
 
-pub async fn run(output_dir: Option<String>, path: Option<String>) -> Result<()> {
+pub async fn run(output_dir: Option<String>, path: Option<String>, generate_queries: bool) -> Result<()> {
     let op = Operation::new("Compiling", "queries");
 
     // Load project context from the specified path (helix.toml directory) or find it automatically
@@ -22,6 +23,15 @@ pub async fn run(output_dir: Option<String>, path: Option<String>) -> Result<()>
         None => ProjectContext::find_and_load(None)?,
     };
 
+    // Generate CRUD queries from schema if requested
+    if generate_queries {
+        let mut gen_step =
+            Step::with_messages("Generating queries from schema", "Queries generated");
+        gen_step.start();
+        generate_default_queries(&project.root, &project.config.project.queries)?;
+        gen_step.done();
+    }
+
     // Collect all .hx files for validation from the queries directory
     let mut parse_step = Step::with_messages("Parsing queries", "Queries parsed");
     parse_step.start();

helix-cli/src/commands/dashboard.rs

@@ -303,10 +303,10 @@ async fn check_dev_mode_requirement(
         config.save_to_file(&config_path)?;
 
         // Reload the project context and push
-        crate::commands::push::run(Some(instance_name.to_string()), false, &metrics_sender).await?;
+        crate::commands::push::run(Some(instance_name.to_string()), false, false, &metrics_sender).await?;
     } else {
         // For cloud instances, use the --dev flag
-        crate::commands::push::run(Some(instance_name.to_string()), true, &metrics_sender).await?;
+        crate::commands::push::run(Some(instance_name.to_string()), true, false, &metrics_sender).await?;
     }
 
     output::success(&format!(
@@ -369,7 +369,7 @@ async fn check_instance_running(project: &ProjectContext, instance_name: &str) -
         instance_name
     ));
     let metrics_sender = MetricsSender::new()?;
-    crate::commands::push::run(Some(instance_name.to_string()), false, &metrics_sender).await?;
+    crate::commands::push::run(Some(instance_name.to_string()), false, false, &metrics_sender).await?;
     output::success(&format!("Instance '{}' built and started", instance_name));
 
     Ok(())

helix-cli/src/commands/init.rs

@@ -258,8 +258,8 @@ async fn run_init_inner(
     print_instructions(
         "Next steps:",
         &[
-            &format!("Customize {queries_path_clean}/schema.hx with your data model"),
-            &format!("Edit {queries_path_clean}/queries.hx or add your own queries"),
+            &format!("Define your data model in {queries_path_clean}/schema.hx"),
+            "Run 'helix build --generate-queries' to generate CRUD queries from your schema",
             "Run 'helix push dev' to start your development instance",
         ],
     );
@@ -318,55 +318,15 @@ E::Authored {
     fs::write(&schema_path, default_schema)?;
     cleanup_tracker.track_file(schema_path);
 
-    // Create default queries.hx with starter queries matching the schema
-    let default_queries = r#"// ─── Node queries ──────────────────────────────────────────
-
-QUERY GetAllUsers() =>
-    users <- N<User>
-    RETURN users
-
-QUERY GetUser(name: String) =>
-    user <- N<User>({name: name})
-    RETURN user
-
-QUERY CreateUser(name: String, email: String, age: I32) =>
-    user <- AddN<User>({name: name, email: email, age: age})
-    RETURN user
-
-QUERY UpdateUser(name: String, email: String) =>
-    user <- N<User>({name: name})::UPDATE({email: email})
-    RETURN user
-
-QUERY DeleteUser(name: String) =>
-    DROP N<User>({name: name})
-    RETURN "success"
-
-// ─── Vector queries ────────────────────────────────────────
-
-QUERY AddDocument(title: String, content: String, source: String) =>
-    doc <- AddV<Document>(
-        Embed(content),
-        {title: title, content: content, source: source}
-    )
-    RETURN doc
-
-QUERY SearchDocuments(query: String, k: I32) =>
-    results <- SearchV<Document>(Embed(query), k)
-    RETURN results
-
-// ─── Edge queries ──────────────────────────────────────────
-
-QUERY LinkUserToDocument(name: String, doc_id: ID, role: String) =>
-    user <- N<User>({name: name})
-    doc <- V<Document>(doc_id)
-    edge <- AddE<Authored>({role: role})::From(user)::To(doc)
-    RETURN edge
-
-QUERY GetUserDocuments(name: String) =>
-    user <- N<User>({name: name})
-    docs <- user::Out<Authored>
-    RETURN docs
-
+    // Create default queries.hx with a minimal example
+    let default_queries = r#"// Write your queries here, or generate CRUD queries from your schema:
+//   helix build --generate-queries
+//
+// Example query:
+//   QUERY GetUser(name: String) =>
+//       user <- N<User>({name: name})
+//       RETURN user
+//
 // For more on HelixQL, see https://docs.helix-db.com
 // or visit https://github.com/HelixDB/helix-db
 "#;

helix-cli/src/commands/push.rs

@@ -16,6 +16,7 @@ use std::time::Instant;
 pub async fn run(
     instance_name: Option<String>,
     dev: bool,
+    generate_queries: bool,
     metrics_sender: &MetricsSender,
 ) -> Result<()> {
     let start_time = Instant::now();
@@ -58,13 +59,14 @@ pub async fn run(
     }
 
     let deploy_result = if instance_config.is_local() {
-        push_local_instance(&project, &instance_name, metrics_sender).await
+        push_local_instance(&project, &instance_name, generate_queries, metrics_sender).await
     } else {
         push_cloud_instance(
             &project,
             &instance_name,
             instance_config.clone(),
             dev,
+            generate_queries,
             metrics_sender,
         )
         .await
@@ -123,6 +125,7 @@ pub async fn run(
 async fn push_local_instance(
     project: &ProjectContext,
     instance_name: &str,
+    generate_queries: bool,
     metrics_sender: &MetricsSender,
 ) -> Result<MetricsData> {
     let op = Operation::new("Deploying", instance_name);
@@ -145,9 +148,15 @@ async fn push_local_instance(
     }
 
     // Build the instance first (this ensures it's up to date) and get metrics data
-    let metrics_data =
-        crate::commands::build::run_build_steps(&op, project, instance_name, None, metrics_sender)
-            .await?;
+    let metrics_data = crate::commands::build::run_build_steps(
+        &op,
+        project,
+        instance_name,
+        None,
+        generate_queries,
+        metrics_sender,
+    )
+    .await?;
 
     // If port changed, regenerate docker-compose with new port
     if port_changed {
@@ -191,6 +200,7 @@ async fn push_cloud_instance(
     instance_name: &str,
     instance_config: InstanceInfo<'_>,
     dev: bool,
+    generate_queries: bool,
     metrics_sender: &MetricsSender,
 ) -> Result<MetricsData> {
     let op = Operation::new("Deploying", instance_name);
@@ -209,7 +219,13 @@ async fn push_cloud_instance(
 
     let metrics_data = if instance_config.should_build_docker_image() {
         // Build happens, get metrics data from build
-        crate::commands::build::run(Some(instance_name.to_string()), None, metrics_sender).await?
+        crate::commands::build::run(
+            Some(instance_name.to_string()),
+            None,
+            generate_queries,
+            metrics_sender,
+        )
+        .await?
     } else {
         // No build, use lightweight parsing
         parse_queries_for_metrics(project)?

helix-cli/src/main.rs

@@ -84,6 +84,10 @@ enum Commands {
         /// Path to output compiled queries
         #[clap(short, long)]
         output: Option<String>,
+
+        /// Generate CRUD queries from schema before compiling
+        #[clap(short = 'g', long = "generate-queries")]
+        generate_queries: bool,
     },
 
     /// Build and compile project for an instance
@@ -94,6 +98,10 @@ enum Commands {
         /// Should build HelixDB into a binary at the specified directory location
         #[clap(long)]
         bin: Option<String>,
+
+        /// Generate CRUD queries from schema before building
+        #[clap(short = 'g', long = "generate-queries")]
+        generate_queries: bool,
     },
 
     /// Deploy/start an instance
@@ -103,6 +111,10 @@ enum Commands {
         /// Use development profile for faster builds (Helix Cloud only)
         #[clap(long)]
         dev: bool,
+
+        /// Generate CRUD queries from schema before deploying
+        #[clap(short = 'g', long = "generate-queries")]
+        generate_queries: bool,
     },
 
     /// Pull .hql files from instance back to local project
@@ -270,13 +282,23 @@ async fn main() -> Result<()> {
             commands::create_cluster::run(&instance, region).await
         }
         Commands::Check { instance } => commands::check::run(instance, &metrics_sender).await,
-        Commands::Compile { output, path } => commands::compile::run(output, path).await,
-        Commands::Build { instance, bin } => commands::build::run(instance, bin, &metrics_sender)
+        Commands::Compile {
+            output,
+            path,
+            generate_queries,
+        } => commands::compile::run(output, path, generate_queries).await,
+        Commands::Build {
+            instance,
+            bin,
+            generate_queries,
+        } => commands::build::run(instance, bin, generate_queries, &metrics_sender)
             .await
             .map(|_| ()),
-        Commands::Push { instance, dev } => {
-            commands::push::run(instance, dev, &metrics_sender).await
-        }
+        Commands::Push {
+            instance,
+            dev,
+            generate_queries,
+        } => commands::push::run(instance, dev, generate_queries, &metrics_sender).await,
         Commands::Pull { instance } => commands::pull::run(instance).await,
         Commands::Start { instance } => commands::start::run(instance).await,
         Commands::Stop { instance } => commands::stop::run(instance).await,