Skip to content
tonic

serve

tonic serve --stdio exposes target-aware cache-only completion, target resolution, execution, artifact planning, inspect, and session behavior through newline-delimited JSON-RPC 2.0.

Terminal window
tonic serve --stdio

--stdio is currently required.

Transport

Section titled “Transport”
  • One JSON-RPC message per UTF-8 line.
  • Request-response only; server-initiated notifications are not implemented.
  • Sessions are process-local and close when the server process exits.
  • Open transactions are rolled back best-effort when their session closes.

Capabilities

Section titled “Capabilities”
{"jsonrpc":"2.0","id":1,"method":"server.capabilities","params":{}}

The result includes the service name, binary version, transport, supported backends, and method list.

Current backends reported by the service are postgres, snowflake, sqlite, mysql, and duckdb.

Common Methods

Section titled “Common Methods”
  • completion.items resolves the query-file statement at the cursor, then returns cached catalog, namespace, table, view, and knowable column suggestions without opening live database connections.
  • Column suggestions are conservative and alias-aware for common unquoted table/view sources. For example, after FROM orders o, FROM orders AS o, or JOIN customers c, completing o. or c.<prefix> may return cached columns when the source object is unambiguous and cached.
  • Completion uses a cache-only/no-guess safety model. Ambiguous aliases, unresolved objects, unsupported source syntax, stale metadata, malformed cache payloads, missing column metadata, or unavailable cache storage return items: [] instead of guessing or invoking live inspect/query/session paths.
  • Public completion responses preserve the JSON-RPC result shape { "items": [...] } and intentionally omit cache diagnostics. Invalid request, directive, or target-context inputs still return structured JSON-RPC errors.
  • targets.list
  • targets.ping
  • query.executeInline
  • query.planArtifact
  • query.executeArtifact
  • sessions.open
  • sessions.execute
  • sessions.close
  • inspect.catalogs
  • inspect.namespaces
  • inspect.tables
  • inspect.views
  • inspect.columns
  • inspect.viewDefinition
  • inspect.ddl

See Serve JSON-RPC for request and response shapes.