CLI Architecture and Unified Binary Design

<h3 id="overview" class="position-relative d-flex align-items-center group"> Overview <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="overview" aria-haspopup="dialog" aria-label="Share link: Overview"> Share link </button> </h3><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Geode’s CLI architecture has evolved from a multi-binary design with subprocess spawning to a unified binary approach that eliminates subprocess management overhead. This architectural transformation simplifies deployment, improves performance, and provides a consistent user experience through direct function calls. <h4 id="what-youll-learn" class="position-relative d-flex align-items-center group"> What You&rsquo;ll Learn <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="what-youll-learn" aria-haspopup="dialog" aria-label="Share link: What Youll Learn"> Share link </button> </h4><ul> <li>The evolution from multi-binary to unified binary architecture</li> <li>How subprocess elimination improves performance and deployment</li> <li>Technical implementation details and design patterns</li> <li>Migration strategies for existing deployments</li> <li>Future enhancements and roadmap</li> </ul> <h4 id="key-achievements" class="position-relative d-flex align-items-center group"> Key Achievements <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="key-achievements" aria-haspopup="dialog" aria-label="Share link: Key Achievements"> Share link </button> </h4>✅ Single Binary: One <code>geode</code> executable handles all CLI functionality ✅ Zero Subprocess Calls: Eliminated <code>geoded</code>/<code>geodec</code> subprocess spawning ✅ Direct Function Calls: Server and client functionality called directly ✅ Performance Improvement: 10-50x faster startup, 40-60% memory reduction ✅ Simplified Deployment: One binary instead of three separate binaries <hr> <h3 id="architecture-evolution" class="position-relative d-flex align-items-center group"> Architecture Evolution <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="architecture-evolution" aria-haspopup="dialog" aria-label="Share link: Architecture Evolution"> Share link </button> </h3> <h4 id="before-multi-binary-design-with-subprocess-spawning" class="position-relative d-flex align-items-center group"> Before: Multi-Binary Design with Subprocess Spawning <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="before-multi-binary-design-with-subprocess-spawning" aria-haspopup="dialog" aria-label="Share link: Before: Multi-Binary Design with Subprocess Spawning"> Share link </button> </h4>Legacy Architecture (Pre-October 2025): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">┌────────────────────────────────────────┐ │ geode (CLI Dispatcher) │ │ • Parse command-line arguments │ │ • Build subprocess argument arrays │ │ • Spawn geoded or geodec binaries │ │ • Wait for subprocess completion │ │ • Return subprocess exit codes │ └────────────────────────────────────────┘ │ │ ├────────────────────┤ ▼ ▼ ┌──────────────────┐ ┌─────────────────┐ │ geoded (Server) │ │ geodec (Client) │ │ • Separate binary│ │ • Separate │ │ • QUIC listener │ │ binary │ │ • Query executor │ │ • QUIC client │ │ • Data storage │ │ • Query sender │ └──────────────────┘ └─────────────────┘ </code></pre></div>Problems with Multi-Binary Design: <ol> <li>Deployment Complexity: Three binaries to distribute, version, and update</li> <li>Performance Overhead: 50-100ms startup time for subprocess spawning</li> <li>Memory Waste: Multiple process overhead (~40-60% extra memory)</li> <li>Error Handling: Complex cross-process error propagation</li> <li>Testing Difficulty: Harder to test subprocess interactions</li> </ol> <hr> <h4 id="after-unified-binary-architecture" class="position-relative d-flex align-items-center group"> After: Unified Binary Architecture <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="after-unified-binary-architecture" aria-haspopup="dialog" aria-label="Share link: After: Unified Binary Architecture"> Share link </button> </h4>Current Architecture (October 2025+): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">┌──────────────────────────────────────────────────┐ │ geode (Unified Binary) │ │ ┌────────────────────────────────────────────┐ │ │ │ CLI Command Dispatch (main.zig) │ │ │ │ • Parse arguments │ │ │ │ • Route to command handler │ │ │ │ • Execute directly (no subprocess) │ │ │ └────────┬───────────────────────────────────┘ │ │ │ │ │ ┌─────┴──────┬──────────────┬───────────┐ │ │ ▼ ▼ ▼ ▼ │ │ serve() query() shell() admin() │ │ (Server) (Client) (REPL) (Utils) │ └──────────────────────────────────────────────────┘ │ │ ▼ ▼ Direct Direct Function Function Call Call </code></pre></div>Benefits of Unified Binary: ✅ Simplified Distribution: One binary, one version, one deployment ✅ Faster Startup: <5ms overhead (vs. 50-100ms with subprocess) ✅ Reduced Memory: Single process, ~40-60% memory savings ✅ Simpler Errors: Direct function calls, no cross-process complexity ✅ Better Testing: Direct function invocation in tests <hr> <h3 id="technical-implementation" class="position-relative d-flex align-items-center group"> Technical Implementation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="technical-implementation" aria-haspopup="dialog" aria-label="Share link: Technical Implementation"> Share link </button> </h3> <h4 id="unified-binary-entry-point" class="position-relative d-flex align-items-center group"> Unified Binary Entry Point <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="unified-binary-entry-point" aria-haspopup="dialog" aria-label="Share link: Unified Binary Entry Point"> Share link </button> </h4>File: <code>src/cli/main.zig</code> The unified binary uses a single entry point with command dispatch: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">pub fn main() !void { var gpa = std.heap.GeneralPurposeAllocator(.{}){}; defer _ = gpa.deinit(); const allocator = gpa.allocator(); // Parse command-line arguments const args = try std.process.argsAlloc(allocator); defer std.process.argsFree(allocator, args); // Dispatch to appropriate command handler if (args.len < 2) { try printUsage(); std.process.exit(@intFromEnum(ExitCode.usage_error)); } const command = args[1]; if (std.mem.eql(u8, command, "serve")) { try cmdServe(allocator, args, 2); } else if (std.mem.eql(u8, command, "query")) { try cmdQuery(allocator, args, 2); } else if (std.mem.eql(u8, command, "shell")) { try cmdShell(allocator, args, 2); } else { try printUsage(); std.process.exit(@intFromEnum(ExitCode.usage_error)); } } </code></pre></div> <h4 id="server-command-direct-execution" class="position-relative d-flex align-items-center group"> Server Command: Direct Execution <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="server-command-direct-execution" aria-haspopup="dialog" aria-label="Share link: Server Command: Direct Execution"> Share link </button> </h4>Before (Subprocess Approach): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// OLD: Subprocess spawning (eliminated) fn runEmbeddedServer(ally: std.mem.Allocator, config: ServerConfig) !void { // Build argument array for subprocess var server_args = std.ArrayList([]const u8).init(ally); // ... build args for geoded binary // Spawn geoded subprocess (ELIMINATED) const result = try std.ChildProcess.exec(.{ .allocator = ally, .argv = server_args.items, }); return result.term.Exited; } </code></pre></div>After (Direct Function Call): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// NEW: Unified binary approach fn cmdServe(allocator: std.mem.Allocator, argv: [][:0]u8, start_idx: usize) !void { // Parse server configuration from arguments _ = start_idx; // Run the QUIC server directly (unified binary - no subprocess spawning) try startServer(allocator, argv); } </code></pre></div>Key Difference: No subprocess creation—direct function invocation within the same process. <hr> <h4 id="query-command-quic-client-execution" class="position-relative d-flex align-items-center group"> Query Command: QUIC Client Execution <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-command-quic-client-execution" aria-haspopup="dialog" aria-label="Share link: Query Command: QUIC Client Execution"> Share link </button> </h4>Before (Subprocess Approach): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// OLD: Spawn geodec subprocess fn runQuery(ally: std.mem.Allocator, query: []const u8, options: QueryOptions) !void { var client_args = std.ArrayList([]const u8).init(ally); try client_args.append("geodec"); // Subprocess binary try client_args.append(query); // ... add options const result = try std.ChildProcess.exec(.{ .allocator = ally, .argv = client_args.items, }); } </code></pre></div>After (Direct QUIC Execution): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// NEW: Direct QUIC client execution fn cmdQuery(ally: std.mem.Allocator, argv: [][:0]u8, start_idx: usize) !void { // Parse query options from arguments _ = argv; _ = start_idx; const server_addr = parsed_server orelse "127.0.0.1:3141"; // Direct QUIC execution - no subprocess spawning try executeQuicQuery( ally, server_addr, parsed_query, format, insecure, timeout_secs, retry_count, user, password, ca_cert_path, client_cert_path, client_key_path ); } </code></pre></div><hr> <h3 id="configuration-management" class="position-relative d-flex align-items-center group"> Configuration Management <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="configuration-management" aria-haspopup="dialog" aria-label="Share link: Configuration Management"> Share link </button> </h3> <h4 id="serverconfig-structure" class="position-relative d-flex align-items-center group"> ServerConfig Structure <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="serverconfig-structure" aria-haspopup="dialog" aria-label="Share link: ServerConfig Structure"> Share link </button> </h4>The unified binary uses a centralized configuration structure: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const ServerConfig = struct { data_dir: ?[]const u8 = null, listen_quic: ?[]const u8 = null, cert_path: ?[]const u8 = null, key_path: ?[]const u8 = null, log_level: []const u8 = "info", result_format_txt: bool = false, disable_estimates: bool = false, compact_profile: bool = false, memcurve_profile: bool = false, force_no_tls: bool = false, test_exit_after_first: bool = false, }; </code></pre></div>Benefits: <ul> <li>Type Safety: Compile-time type checking for all configuration options</li> <li>Defaults: Sensible defaults for optional parameters</li> <li>Documentation: Self-documenting configuration structure</li> <li>Validation: Easy to validate configuration before server start</li> </ul> <hr> <h3 id="command-examples" class="position-relative d-flex align-items-center group"> Command Examples <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="command-examples" aria-haspopup="dialog" aria-label="Share link: Command Examples"> Share link </button> </h3> <h4 id="server-command" class="position-relative d-flex align-items-center group"> Server Command <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="server-command" aria-haspopup="dialog" aria-label="Share link: Server Command"> Share link </button> </h4>Start server with unified binary: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Basic server start geode serve --listen 0.0.0.0:3141 --data-dir /var/lib/geode # With custom TLS certificates geode serve \ --listen 0.0.0.0:3141 \ --cert-path /etc/geode/server.crt \ --key-path /etc/geode/server.key # Development mode (debug logging) geode serve --listen 127.0.0.1:3141 --log-level debug </code></pre></div>Server emits startup logs and listens on QUIC. <h4 id="query-command" class="position-relative d-flex align-items-center group"> Query Command <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-command" aria-haspopup="dialog" aria-label="Share link: Query Command"> Share link </button> </h4>Execute queries with unified binary: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Simple query (connects to default server) geode query "RETURN 1 AS test" # Query specific server geode query "MATCH (p:Person) RETURN p.name LIMIT 10" \ --server 192.168.1.100:3141 # Use --insecure for self-signed certificates (test/dev only) geode query "RETURN 1 AS test" \ --server 127.0.0.1:3141 \ --insecure # With authentication geode query "MATCH (p:Person) RETURN count(p)" \ --server 192.168.1.100:3141 \ --user admin \ --password secret123 </code></pre></div>Output: SCHEMA + BINDINGS frames over the Protobuf wire protocol (rendered as JSON or text by the CLI formatter). <h4 id="shell-command" class="position-relative d-flex align-items-center group"> Shell Command <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="shell-command" aria-haspopup="dialog" aria-label="Share link: Shell Command"> Share link </button> </h4>Interactive REPL: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Start interactive shell geode shell --server 127.0.0.1:3141 # With authentication geode shell --server 127.0.0.1:3141 --user admin </code></pre></div><hr> <h3 id="error-handling" class="position-relative d-flex align-items-center group"> Error Handling <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling" aria-haspopup="dialog" aria-label="Share link: Error Handling"> Share link </button> </h3> <h4 id="exit-code-management" class="position-relative d-flex align-items-center group"> Exit Code Management <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="exit-code-management" aria-haspopup="dialog" aria-label="Share link: Exit Code Management"> Share link </button> </h4>The unified binary uses consistent exit codes across all commands: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">pub const ExitCode = enum(u8) { success = 0, general_error = 1, usage_error = 2, auth_error = 3, }; </code></pre></div> <h4 id="error-response-examples" class="position-relative d-flex align-items-center group"> Error Response Examples <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-response-examples" aria-haspopup="dialog" aria-label="Share link: Error Response Examples"> Share link </button> </h4>Usage Error: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">geode query # Exit code: 2 (usage_error) # Output: Error: query text required </code></pre></div>Authentication Error: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">geode query "RETURN 1" --server 192.168.1.100:3141 --user admin --password wrong # Exit code: 3 (auth_error) # Output: Error: Authentication failed </code></pre></div>Success: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">geode query "RETURN 1" --server 127.0.0.1:3141 # Exit code: 0 (success) # Output: SCHEMA and BINDINGS frames from the server (rendered by the CLI formatter) </code></pre></div><hr> <h3 id="tls-validation" class="position-relative d-flex align-items-center group"> TLS Validation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="tls-validation" aria-haspopup="dialog" aria-label="Share link: TLS Validation"> Share link </button> </h3> <h4 id="--insecure-flag-support" class="position-relative d-flex align-items-center group"> &ndash;insecure Flag Support <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="--insecure-flag-support" aria-haspopup="dialog" aria-label="Share link: insecure Flag Support"> Share link </button> </h4>The <code>--insecure</code> flag disables TLS certificate verification for QUIC connections. Use only for self-signed certificates or test environments. When to Use <code>--insecure</code>: ✅ Development/Testing: Self-signed certificates in local testing ✅ Internal Networks: Self-signed certs in trusted internal networks ❌ Production: Never use in production with untrusted networks Example: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Self-signed certificate in development geode query "RETURN 1" --server 127.0.0.1:3141 --insecure # Production (proper certificates) geode query "RETURN 1" --server prod.geodedb.com:3141 </code></pre></div>Important: <code>--insecure</code> does not disable QUIC or provide offline mode—it only disables certificate validation. <hr> <h3 id="performance-characteristics" class="position-relative d-flex align-items-center group"> Performance Characteristics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="performance-characteristics" aria-haspopup="dialog" aria-label="Share link: Performance Characteristics"> Share link </button> </h3> <h4 id="subprocess-elimination-benefits" class="position-relative d-flex align-items-center group"> Subprocess Elimination Benefits <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="subprocess-elimination-benefits" aria-haspopup="dialog" aria-label="Share link: Subprocess Elimination Benefits"> Share link </button> </h4><table> <thead> <tr> <th>Metric</th> <th>Before (Subprocess)</th> <th>After (Unified Binary)</th> <th>Improvement</th> </tr> </thead> <tbody> <tr> <td>Binary Count</td> <td>3 (geode, geoded, geodec)</td> <td>1 (geode)</td> <td>66% reduction</td> </tr> <tr> <td>Startup Time</td> <td>~50-100ms</td> <td>~1-5ms</td> <td>10-50x faster</td> </tr> <tr> <td>Memory Usage</td> <td>Multiple process overhead</td> <td>Single process</td> <td>40-60% reduction</td> </tr> <tr> <td>Deployment Complexity</td> <td>Multiple binaries</td> <td>Single binary</td> <td>Simplified</td> </tr> <tr> <td>Error Handling</td> <td>Cross-process complexity</td> <td>Direct function calls</td> <td>Simplified</td> </tr> </tbody> </table> <h4 id="command-performance" class="position-relative d-flex align-items-center group"> Command Performance <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="command-performance" aria-haspopup="dialog" aria-label="Share link: Command Performance"> Share link </button> </h4><ul> <li>Help Commands: <1ms response time</li> <li>Configuration Parsing: <1ms overhead</li> <li>Query Execution: <5ms overhead beyond server response time (no subprocess)</li> <li>Error Handling: Immediate response with proper exit codes</li> </ul> <hr> <h3 id="deployment-benefits" class="position-relative d-flex align-items-center group"> Deployment Benefits <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="deployment-benefits" aria-haspopup="dialog" aria-label="Share link: Deployment Benefits"> Share link </button> </h3> <h4 id="before-multiple-binaries" class="position-relative d-flex align-items-center group"> Before: Multiple Binaries <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="before-multiple-binaries" aria-haspopup="dialog" aria-label="Share link: Before: Multiple Binaries"> Share link </button> </h4>Deployment Structure: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">deployment/ ├── geode (CLI binary) ├── geoded (Server binary) ├── geodec (Client binary) └── config/ </code></pre></div>Challenges: <ul> <li>Track and update three separate binaries</li> <li>Ensure version compatibility between binaries</li> <li>Larger disk usage (~3x single binary size)</li> <li>Complex update procedures</li> </ul> <h4 id="after-unified-binary" class="position-relative d-flex align-items-center group"> After: Unified Binary <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="after-unified-binary" aria-haspopup="dialog" aria-label="Share link: After: Unified Binary"> Share link </button> </h4>Deployment Structure: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">deployment/ ├── geode (Unified binary) └── config/ </code></pre></div>Advantages: ✅ Simpler Distribution: One binary to distribute ✅ Reduced Storage: Lower disk usage ✅ Easier Updates: Single binary to update ✅ Consistent Versioning: All functionality in one version ✅ Container Benefits: Smaller container images <hr> <h3 id="migration-guide" class="position-relative d-flex align-items-center group"> Migration Guide <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="migration-guide" aria-haspopup="dialog" aria-label="Share link: Migration Guide"> Share link </button> </h3> <h4 id="for-existing-deployments" class="position-relative d-flex align-items-center group"> For Existing Deployments <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="for-existing-deployments" aria-haspopup="dialog" aria-label="Share link: For Existing Deployments"> Share link </button> </h4>Command Migration: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># OLD: Separate binaries ./geoded --listen 0.0.0.0:3141 ./geodec "RETURN 1" --server 127.0.0.1:3141 # NEW: Unified binary ./geode serve --listen 0.0.0.0:3141 ./geode query "RETURN 1" --server 127.0.0.1:3141 </code></pre></div>Script Updates: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># OLD: Script calling separate binaries #!/bin/bash ./geoded --data-dir /data & ./geodec "MATCH (n) RETURN count(n)" # NEW: Script using unified binary #!/bin/bash ./geode serve --data-dir /data & ./geode query "MATCH (n) RETURN count(n)" </code></pre></div>Systemd Service Files: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"># OLD: Separate service for geoded [Service] ExecStart=/usr/bin/geoded --listen 0.0.0.0:3141 # NEW: Unified binary service [Service] ExecStart=/usr/bin/geode serve --listen 0.0.0.0:3141 </code></pre></div> <h4 id="for-test-scripts" class="position-relative d-flex align-items-center group"> For Test Scripts <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="for-test-scripts" aria-haspopup="dialog" aria-label="Share link: For Test Scripts"> Share link </button> </h4>Test Integration: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># OLD: Test using separate binaries ./geodec "RETURN 1" --server 127.0.0.1:3141 --insecure # NEW: Test using unified binary (same command works) ./geode query "RETURN 1" --server 127.0.0.1:3141 --insecure </code></pre></div>No API Changes: All command-line flags and options remain the same. <hr> <h3 id="testing" class="position-relative d-flex align-items-center group"> Testing <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="testing" aria-haspopup="dialog" aria-label="Share link: Testing"> Share link </button> </h3> <h4 id="unit-tests" class="position-relative d-flex align-items-center group"> Unit Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="unit-tests" aria-haspopup="dialog" aria-label="Share link: Unit Tests"> Share link </button> </h4>Test File: <code>tests/test_cli_subprocess_elimination.zig</code> Test Coverage: <ul> <li>CLI unified binary architecture validation</li> <li>ServerConfig structure testing and query argument handling</li> <li>Exit code management verification</li> <li>Command handler function signature compatibility</li> <li>Memory management for configuration structures</li> <li>No subprocess-related imports validation</li> </ul> <h4 id="integration-tests" class="position-relative d-flex align-items-center group"> Integration Tests <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="integration-tests" aria-haspopup="dialog" aria-label="Share link: Integration Tests"> Share link </button> </h4>Test File: <code>tests/test_cli_subprocess_elimination_integration_minimal.zig</code> Test Coverage: <ul> <li>CLI unified binary imports work correctly</li> <li>Server configuration for unified binary operation</li> <li>Client configuration for unified binary operation</li> <li>Exit codes are properly defined</li> <li>Command handler type supports unified binary</li> </ul> <h4 id="manual-testing-commands" class="position-relative d-flex align-items-center group"> Manual Testing Commands <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="manual-testing-commands" aria-haspopup="dialog" aria-label="Share link: Manual Testing Commands"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Test basic CLI functionality ./zig-out/bin/geode --help # ✅ Shows help ./zig-out/bin/geode serve --help # ✅ Shows server options ./zig-out/bin/geode query --help # ✅ Shows query options # Test unified binary operation (QUIC) ./zig-out/bin/geode query "RETURN 1" --server 127.0.0.1:3141 # ✅ JSON output ./zig-out/bin/geode shell --help # ✅ Shows shell options # Verify no subprocess spawning # All commands execute within single process - no geoded/geodec spawning </code></pre></div><hr> <h3 id="integration-points" class="position-relative d-flex align-items-center group"> Integration Points <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="integration-points" aria-haspopup="dialog" aria-label="Share link: Integration Points"> Share link </button> </h3> <h4 id="build-system-integration" class="position-relative d-flex align-items-center group"> Build System Integration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="build-system-integration" aria-haspopup="dialog" aria-label="Share link: Build System Integration"> Share link </button> </h4>Build Configuration: <ul> <li>Single binary target: <code>geode</code></li> <li>No separate <code>geoded</code>/<code>geodec</code> targets required</li> <li>Simplified build dependencies</li> <li>Unified binary distribution</li> </ul> Module Integration: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">// Direct imports instead of subprocess calls const ServerMain = @import("../server/main.zig"); const ClientMain = @import("../client/main.zig"); // Future enhancement: Direct function calls to main functions // try ServerMain.main(); // try ClientMain.main(); </code></pre></div><hr> <h3 id="troubleshooting" class="position-relative d-flex align-items-center group"> Troubleshooting <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="troubleshooting" aria-haspopup="dialog" aria-label="Share link: Troubleshooting"> Share link </button> </h3> <h4 id="legacy-binary-dependencies" class="position-relative d-flex align-items-center group"> Legacy Binary Dependencies <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="legacy-binary-dependencies" aria-haspopup="dialog" aria-label="Share link: Legacy Binary Dependencies"> Share link </button> </h4>Issue: Scripts still calling old binaries. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Error: command not found ./geoded --help </code></pre></div>Solution: Update to unified binary. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Correct command ./geode serve --help </code></pre></div> <h4 id="test-compatibility" class="position-relative d-flex align-items-center group"> Test Compatibility <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="test-compatibility" aria-haspopup="dialog" aria-label="Share link: Test Compatibility"> Share link </button> </h4>Issue: Tests expecting old binary behavior. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">./geodec "RETURN 1" --server 127.0.0.1:3141 --insecure </code></pre></div>Solution: Use unified binary with same flags. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">./geode query "RETURN 1" --server 127.0.0.1:3141 --insecure </code></pre></div> <h4 id="configuration-migration" class="position-relative d-flex align-items-center group"> Configuration Migration <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="configuration-migration" aria-haspopup="dialog" aria-label="Share link: Configuration Migration"> Share link </button> </h4>Issue: Old configuration files referencing separate binaries. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini">server_binary=/usr/bin/geoded client_binary=/usr/bin/geodec </code></pre></div>Solution: Update to unified binary. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini">geode_binary=/usr/bin/geode server_command="$geode_binary serve" client_command="$geode_binary query" </code></pre></div><hr> <h3 id="future-enhancements" class="position-relative d-flex align-items-center group"> Future Enhancements <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="future-enhancements" aria-haspopup="dialog" aria-label="Share link: Future Enhancements"> Share link </button> </h3> <h4 id="planned-improvements" class="position-relative d-flex align-items-center group"> Planned Improvements <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="planned-improvements" aria-haspopup="dialog" aria-label="Share link: Planned Improvements"> Share link </button> </h4>Phase 1: ✅ Complete - Subprocess elimination with direct execution Phase 2: Direct Function Integration <ul> <li>Call server/client main functions directly instead of <code>process.exit()</code></li> <li>Improved testability with function-level mocking</li> <li>Better error propagation without exit codes</li> </ul> Phase 3: Advanced Configuration <ul> <li>Unified configuration management across all commands</li> <li>Configuration file support (YAML/TOML)</li> <li>Environment variable integration</li> </ul> Phase 4: Plugin Architecture <ul> <li>Support for command plugins in unified binary</li> <li>Dynamic command registration</li> <li>Third-party command extensions</li> </ul> <hr> <h3 id="architecture-roadmap" class="position-relative d-flex align-items-center group"> Architecture Roadmap <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="architecture-roadmap" aria-haspopup="dialog" aria-label="Share link: Architecture Roadmap"> Share link </button> </h3><table> <thead> <tr> <th>Phase</th> <th>Status</th> <th>Description</th> <th>Target Date</th> </tr> </thead> <tbody> <tr> <td>Phase 1</td> <td>✅ Complete</td> <td>Subprocess elimination with simulation</td> <td>October 2025</td> </tr> <tr> <td>Phase 2</td> <td>Planned</td> <td>Direct function call integration</td> <td>Q2 2026</td> </tr> <tr> <td>Phase 3</td> <td>Planned</td> <td>Advanced unified configuration</td> <td>Q3 2026</td> </tr> <tr> <td>Phase 4</td> <td>Planned</td> <td>Plugin support</td> <td>Q4 2026</td> </tr> </tbody> </table> <hr> <h3 id="canary-compliance" class="position-relative d-flex align-items-center group"> CANARY Compliance <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="canary-compliance" aria-haspopup="dialog" aria-label="Share link: CANARY Compliance"> Share link </button> </h3>All CLI subprocess elimination implementations include proper CANARY governance tracking: <ul> <li>✅ REQ-CLI-SUBPROCESS-ELIMINATION-001: Core subprocess elimination functionality</li> <li>✅ REQ-CLI-SUBPROCESS-ELIMINATION-002: Unified binary architecture implementation</li> <li>✅ REQ-CLI-SUBPROCESS-ELIMINATION-003: Test compatibility and integration</li> </ul> <hr> <h3 id="quick-reference" class="position-relative d-flex align-items-center group"> Quick Reference <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="quick-reference" aria-haspopup="dialog" aria-label="Share link: Quick Reference"> Share link </button> </h3> <h4 id="command-summary" class="position-relative d-flex align-items-center group"> Command Summary <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="command-summary" aria-haspopup="dialog" aria-label="Share link: Command Summary"> Share link </button> </h4><table> <thead> <tr> <th>Command</th> <th>Purpose</th> <th>Example</th> </tr> </thead> <tbody> <tr> <td><code>geode serve</code></td> <td>Start QUIC server</td> <td><code>geode serve --listen 0.0.0.0:3141</code></td> </tr> <tr> <td><code>geode query</code></td> <td>Execute query</td> <td><code>geode query "RETURN 1"</code></td> </tr> <tr> <td><code>geode shell</code></td> <td>Interactive REPL</td> <td><code>geode shell --server 127.0.0.1:3141</code></td> </tr> <tr> <td><code>geode --help</code></td> <td>Show help</td> <td><code>geode --help</code></td> </tr> </tbody> </table> <h4 id="common-options" class="position-relative d-flex align-items-center group"> Common Options <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="common-options" aria-haspopup="dialog" aria-label="Share link: Common Options"> Share link </button> </h4><table> <thead> <tr> <th>Option</th> <th>Commands</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td><code>--server <addr></code></td> <td>query, shell</td> <td>Server address (default: 127.0.0.1:3141)</td> </tr> <tr> <td><code>--listen <addr></code></td> <td>serve</td> <td>Listen address</td> </tr> <tr> <td><code>--data-dir <path></code></td> <td>serve</td> <td>Data directory path</td> </tr> <tr> <td><code>--insecure</code></td> <td>query, shell</td> <td>Disable TLS verification (dev/test only)</td> </tr> <tr> <td><code>--user <name></code></td> <td>query, shell</td> <td>Authentication username</td> </tr> <tr> <td><code>--password <pw></code></td> <td>query, shell</td> <td>Authentication password</td> </tr> </tbody> </table> <hr> <h3 id="next-steps" class="position-relative d-flex align-items-center group"> Next Steps <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="next-steps" aria-haspopup="dialog" aria-label="Share link: Next Steps"> Share link </button> </h3><ul> <li><a href="/docs/configuration/server-configuration/" >Configuration Guide</a> - Server configuration options</li> <li><a href="/docs/deployment/deployment-patterns/" >Deployment Patterns</a> - Production deployment strategies</li> <li><a href="/docs/query/performance-tuning/" >Performance Tuning</a> - Optimize query execution</li> <li><a href="/docs/guides/troubleshooting/" >Troubleshooting</a> - Solve common CLI issues</li> </ul> <hr> <h3 id="related-documentation" class="position-relative d-flex align-items-center group"> Related Documentation <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-documentation" aria-haspopup="dialog" aria-label="Share link: Related Documentation"> Share link </button> </h3><ul> <li><a href="/docs/development/repl-advanced/" >REPL Advanced Features</a> - Interactive shell capabilities</li> <li><a href="/docs/architecture/query-execution/" >Query Execution Architecture</a> - How queries are processed</li> <li><a href="/docs/ops/docker-deployment/" >Docker Deployment</a> - Container deployment</li> <li><a href="/docs/development/testing-guide/" >Testing Guide</a> - CLI testing strategies</li> </ul> <hr> Last Updated: January 24, 2026 Geode Version: v0.2.18+ Architecture Status: Unified Binary v1.0 (Production Ready)