Browse cyoda help

This section is a static mirror of the cyoda-go binary’s help surface — the same content cyoda help … prints on the CLI and the live HTTP help API serves at runtime. It exists for readers who don’t have a local cyoda-go runtime installed, and for AI agents that need to discover and consume cyoda-go’s help without running the binary.

Every rendered page below has a sibling raw-markdown view at <page-url>.md and a structured JSON descriptor at <page-url>.json. For example, /help/cli/ has /help/cli.md (markdown body only) and /help/cli.json (full descriptor with body, sections, see_also, children, etc.).

The pages under /help/ are pinned to cyoda-go v0.6.2. The binary you run is the authority for the version you run; if your binary is newer, prefer its output.

Browse the tree

analytics — Trino SQL analytics interface Cyoda Cloud exposes entity data as Trino SQL tables through a Trino connector. The connector uses the Schema Management REST API to discover table definitions and the WebSocket (STOMP) messaging API to stream entity rows at query time.

cyoda CLI — subcommand reference cyoda is a Go binary that embeds the full platform: API server, schema engine, workflow runner, and storage plugins. Invoked with no subcommand, it starts the server using environment-provided configuration. Subcommands provide operational affordances — `init` for first-run bootstrap, `health` for liveness probes, `migrate` for schema migrations.

cloudevents — CloudEvent payload JSON Schemas cyoda-go uses [CloudEvents v1.0](https://cloudevents.io) as the transport envelope for event-driven processing. Every payload carried inside a CloudEvent — workflow calculation requests, calculation responses, entity transaction events, snapshot state, model descriptors — is validated against a JSON Schema (Draft 2020-12).

cyoda configuration reference Environment variables beat default values. The `_FILE` suffix variant takes precedence over the plain variable when both are set — for example, `CYODA_POSTGRES_URL_FILE=/etc/secrets/db-url` wins over `CYODA_POSTGRES_URL`. There are no command-line flags for configuration values; env vars are the sole configuration surface.

crud — entity lifecycle API Entities are instances of models. Each entity has a UUID, a model reference (`entityName`, `modelVersion`), and a lifecycle state managed by the workflow engine. Creating an entity requires the referenced model to be in `LOCKED` state. All write operations run within a Cyoda transaction and return a `transactionId` alongside the affected entity IDs.

cyoda error reference Every error response from the Cyoda REST API carries a structured `errorCode` in the `properties` object. Multiple codes may share the same HTTP status. Programmatic handling keys on `errorCode`, not HTTP status.

grpc — gRPC service contract cyoda-go exposes one gRPC service: `CloudEventsService` (package `org.cyoda.cloud.api.grpc`). All gRPC methods use the CloudEvents Protobuf envelope (`io.cloudevents.v1.CloudEvent`) as both request and response types. The event type string in the CloudEvent envelope selects the operation; the JSON payload in `text_data` (or `binary_data`) carries the operation-specific body.

helm — Helm chart for Kubernetes deployment The chart at `deploy/helm/cyoda` deploys cyoda-go on Kubernetes as a StatefulSet backed by an external PostgreSQL database. The chart requires Kubernetes `>=1.31.0`. Chart version: `0.1.0`. App version: `0.1.0` (synchronized to the binary by the `bump-chart-appversion.yml` CI workflow).

models — entity model schema system A model is a named, versioned schema registered per tenant. Every entity in the system is an instance of exactly one model. Models are identified by `(entityName, modelVersion)`. The model ID is a deterministic UUID v5 derived from that key: `UUID.newSHA1(NameSpaceURL, "{entityName}.{modelVersion}")`.

openapi — OpenAPI 3 spec and discovery endpoints cyoda-go generates its OpenAPI 3.1 specification from the embedded `api/openapi.yaml` file compiled into the binary at build time. The spec is served at `/openapi.json` with runtime-patched server URLs. The Scalar API Reference UI is served at `/docs` and loads the spec from `/openapi.json`.

cyoda quickstart — minimum invocations cyoda-go is a single-process, multi-tenant REST and gRPC API server backed by a pluggable embedded database management system. Storage backends are `memory`, `sqlite`, and `postgres`; authentication modes are `mock` and `jwt`. All configuration is via environment variables with a `CYODA_` prefix.

run — runtime modes and operational semantics cyoda-go is a single-process, multi-tenant REST and gRPC API server. It starts in serving mode when invoked with no subcommand. All configuration is via environment variables with a `CYODA_` prefix. The binary, Docker image, and Helm chart run the same binary; only the environment configuration differs across run modes.

search — entity search API Search operates against a specific entity model `(entityName, modelVersion)`. Two modes are supported:

telemetry — OpenTelemetry emission cyoda-go integrates the OpenTelemetry Go SDK (`go.opentelemetry.io/otel`). When `CYODA_OTEL_ENABLED=true`, the binary initializes a trace provider and a meter provider at startup using OTLP HTTP exporters. When `CYODA_OTEL_ENABLED=false` (default), no OTel SDK is initialized and no spans or metrics are emitted; the global OTel provider remains a no-op.

workflows — state machine definitions A workflow definition is a named finite state machine attached to an entity model. Workflows are stored per model reference `(entityName, modelVersion)`. A model may have multiple workflow definitions; the engine selects the matching one per entity using the workflow-level `criterion` field evaluated at entity creation time. When no `criterion` matches, the engine uses the default built-in workflow.

For a flat view of every topic and subtopic, see cyoda help topic tree.

For agents

Agents navigate the mirror via three primitives plus a discovery file:

• /help/index.json — manifest of every topic with topic, title, stability, tagline, see_also. The envelope is byte-equivalent to the live API’s GET /help response.
• /help/<slug>.json — full topic descriptor including body, sections[], see_also, stability, actions, children. Same shape as the live API’s GET /help/{topic} response.
• /help/<slug>.md — body only, no frontmatter, no chrome.
• /help/versions.json — version registry.

Discovery hint: /help/llms.txt and the site-level /llms.txt both advertise these endpoints and the URL convention.

URL convention

cyoda help A B C ↔ https://docs.cyoda.net/help/a/b/c/ for the rendered page, or .md/.json for the raw payloads. Manifest topic IDs use the live API’s dotted form and may be mixed-case (config.database, errors.BAD_REQUEST); replace dots with slashes and lowercase to build the URL — e.g. errors.BAD_REQUEST → /help/errors/bad_request/.