Skip to content
Cyoda Documentation
Settings

cyoda CLI — subcommand reference

cyoda-go version 0.6.2

cli

Section titled “cli”

NAME

Section titled “NAME”

cli — the cyoda command-line interface.

SYNOPSIS

Section titled “SYNOPSIS”

cyoda [<subcommand>] [<flags>]

DESCRIPTION

Section titled “DESCRIPTION”

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.

Global flags --help (or -h) and --version (or -v) are recognized before subcommand dispatch.

SUBCOMMANDS

Section titled “SUBCOMMANDS”
  • cyoda (no subcommand) — start the API server. See cli serve. Exit codes: 0 clean shutdown after SIGINT/SIGTERM; 1 startup failure (IAM validation, OTel init, port bind, backend connect).
  • cyoda init [--force] — Write a starter user config enabling sqlite. See cyoda help cli init. Exit codes: 0 success or idempotent no-op; 1 I/O error; 2 bad flags.
  • cyoda health — Probe /readyz on the admin listener. See cyoda help cli health. Exit codes: 0 readyz returned 200; 1 connection error or non-200 status.
  • cyoda migrate [--timeout <duration>] — Run schema migrations for the configured backend and exit. See cyoda help cli migrate. Exit codes: 0 success or no-op (memory/sqlite); 1 runtime error (bad config, DB unreachable, migration failure, timeout); 2 flag-parse error.
  • cyoda help [<topic>...] [--format=<fmt>] — Browse the help topic tree. See cyoda help cli help. Exit codes: 0 topic found; 1 topic not found.

OPTIONS

Section titled “OPTIONS”
  • --help, -h — Print top-level help summary. Exit code: 0.
  • --version, -v — Print the binary’s ldflag-injected version, commit SHA, and build date. Exit code: 0.

CONFIGURATION

Section titled “CONFIGURATION”

All server configuration is via environment variables with the CYODA_ prefix. Variables can be placed in .env files and loaded automatically using profiles. See cyoda help config for the full reference.

EXAMPLES

Section titled “EXAMPLES”
# Start the server with defaults (in-memory storage, mock auth)
cyoda


# First-run bootstrap then start
cyoda init && cyoda


# Check version of an installed binary
cyoda --version


# Run with profiles: postgres storage + observability
CYODA_PROFILES=postgres,otel cyoda


# Run via docker compose (dev helper)
./scripts/dev/run-docker-dev.sh

SEE ALSO

Section titled “SEE ALSO”
  • config
  • run
  • quickstart

Subtopics

Section titled “Subtopics”
  • cyoda help cli health — cyoda health sends an HTTP GET to http://127.0.0.1:<port>/readyz and exits 0 if the server responds with HTTP 200. Any non-200 response or connection error causes exit 1.
  • cyoda help cli help — cyoda help is the built-in documentation browser. Topics are organized in a dot-separated tree (cli, cli.serve, config.database, etc.). Invoking cyoda help with no arguments prints a summary of all top-level topics. Invoking it with one or more topic segments navigates the tree.
  • cyoda help cli init — cyoda init is the recommended first step for local desktop use. It writes a minimal user config file that sets CYODA_STORAGE_BACKEND=sqlite, enabling persistent local storage without requiring a database server.
  • cyoda help cli migrate — cyoda migrate is a short-lived process that applies pending schema migrations for the configured storage backend, then exits cleanly — no admin listener, no background loops, no lingering goroutines.
  • cyoda help cli serve — Starting with no subcommand loads configuration from environment variables, validates the IAM mode, and binds the REST, gRPC, and admin listeners. The server is single-process, multi-tenant, and stateful — storage is provided by one of the pluggable backends (memory, sqlite, or postgres); see cyoda help config for backend selection.

See also

Section titled “See also”
  • cyoda help config — 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.
  • cyoda help run — 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.
  • cyoda help quickstart — 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.

Raw formats

Section titled “Raw formats”