Skip to content
Cyoda Documentation
Settings

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.8.3. The binary you run is the authority for the version you run; if your binary is newer, prefer its output.

Browse the tree

Section titled “Browse the tree”
admin — runtime-switchable admin endpoints Both endpoint families require `ROLE_ADMIN` on the JWT and update process-local state atomically. State is **not** propagated across nodes; multi-node deployments must hit each node's endpoint separately.
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.
audit — entity audit event API The audit API exposes a per-entity event log covering entity lifecycle changes (`EntityChange` events) and workflow state-machine progression (`StateMachine` events). Events are returned newest-first and support cursor-based pagination.
auth — authenticate client applications against cyoda auth — authenticate client applications against cyoda.
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).
cluster — multi-node topology and operations Multi-node cyoda is supported only on the `postgres` storage backend. All nodes are stateless and identical: no leader election, no shard ownership, no external service-discovery infrastructure. PostgreSQL is the single coordination layer. Snapshot Isolation with first-committer-wins (`REPEATABLE READ` + commit-time validation) provides correctness; gossip provides peer awareness; HMAC-signed routing tokens bind in-flight `pgx.Tx` handles to their owning node.
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).
messages — edge message store API An edge message is an arbitrary JSON payload stored under a server-generated time-UUID together with a fixed set of AMQP-aligned headers and an optional flat metadata map. The store is standalone: a message is not an entity, and creating one does not touch the workflow engine — no transition fires, no processor or criterion runs. Edge messaging is a durable, tenant-scoped staging buffer at the platform edge, a peer of the entity store rather than part of it.
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`.
predicates — search & criteria condition semantics predicates — operator catalog and evaluation semantics for the `Condition` DSL used by search (`cyoda help search`) and workflow/transition criteria (`cyoda help workflows`). Both consume the same kernel, so everything here applies identically to both.
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`). The **metric scrape pipeline is always on**: at startup the binary creates a meter provider with an OpenTelemetry → Prometheus exporter and serves it at `:9091/metrics`, regardless of `CYODA_OTEL_ENABLED`. No collector is required to scrape metrics.
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

Section titled “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

Section titled “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/.